chore(usage): rename playground index partials to .mdx

[thetaPC]

Issue URL: internal

What is the current behavior?

Playground partials under static/usage are named index.md, but they are MDX files: each one imports the Playground component and renders it as JSX. They only work today because Docusaurus resolves them through its MDX fallback loader, which honors markdown.format, and that option still defaults to mdx.

Docusaurus is moving toward Strict MDX, where .md is parsed as CommonMark instead. When that default changes, every one of these files would have its imports and JSX treated as literal text, and all playgrounds would stop rendering.

What is the new behavior?

index.md is renamed to index.mdx across the two live usage trees, static/usage/v8 and static/usage/v9, for 863 files total. The 880 imports that reference them, 441 in docs and 439 in versioned_docs/version-v8, are updated to match.

The playground generator is updated so newly created playgrounds emit index.mdx from the start, along with the usage example in the templates README.

The component API plugin gains a resolve.extensionAlias entry mapping .md to .mdx and then .md, so an import written with the old extension still resolves after the rename. This is what makes this PR and its translation branch companion independent of merge order. It carries a TODO(FW-6456) marker and comes out once every branch is migrated, alongside the dual-write it supersedes.

Two things are deliberately left alone:

The per-framework snippet files, such as javascript.md and react.md, stay as .md because each one is a single fenced code block containing no imports or JSX, so the extension already matches what is in them.

Archived versions are untouched. static/usage/v6 and static/usage/v7 keep their 713 index.md files, since those versions are never built.

Does this introduce a breaking change?

• Yes
• No

Other information

The companion PR on translation/jp still needs to land, but it is no longer order sensitive.

The Japanese site is built from this branch's tree combined with prose pulled from the translation branch, and both sides reference partials by explicit path including the extension. Renaming on either side alone used to break the other, and because preview builds run --locale en, nothing here would catch it. It would surface only on the production deploy. The extensionAlias entry removes that coupling, so the two PRs can merge in any order and with any gap between them.

Verification performed locally:

Building --locale ja against the unmerged translation branch reproduces the original failure exactly: 428 unresolved modules, exit 1. All 428 have an .mdx counterpart on disk, so it is purely the extension. With the alias in place the same build completes, emitting 2298 pages with 0 errors and playgrounds rendering.

The resolver behavior was characterized directly rather than assumed. A request for a .md file with neither file present is still a build error, so genuinely missing files do not go quiet. The only new behavior is .mdx winning when both exist, which already describes the 950 dual-written API partials.

A full English production build passes, reporting 0 errors, 0 warnings, 0 unresolved modules, and 0 broken links. The single broken anchor it reports predates this work and is unrelated: glossary.md defines web-standards as a raw HTML section id, which the anchor checker does not index because it only reads heading IDs. That file is not in this diff.

Prettier reports no files needing changes repo wide. Worth noting that the rename is parser neutral, because @ionic/prettier-config already forces the mdx parser for *.md.

All 855 unique import targets were confirmed to exist on disk, and a repo wide sweep found no remaining reference to a v8 or v9 usage index.md in any file type.

The five partials under docs/developing/config are the same shape and are not renamed here. They ride along with the doc page rename, since they need the translation branch to change in the same window. That work is tracked on the ticket, along with two problems found in those files: two imports crossed against their directories, and a set of v8 copies that nothing reads.

Refer to the Docusaurus 3.10 Strict MDX release note for background.

How to test

Open each page below and confirm the playgrounds still render. The rename only affects how the partials are imported, so a failure shows up as a missing or blank playground rather than as broken prose.

1. Datetime, current version has 28 playgrounds, the most on any page.
2. Accordion, current version covers the playgrounds that pull in separate CSS snippet files.
3. Datetime, v8 confirms the versioned tree resolves independently of the current one.

On each page, check that:

Every playground appears, with its live demo loading in the embedded frame.

Switching between the Angular, React, Vue, and JavaScript tabs shows the code for each. A playground can render correctly while its tabs come up empty, so this is the only step that confirms the code snippets themselves loaded.

No raw text such as an import line or a literal component tag is visible anywhere in the rendered page. That would mean a partial was parsed as plain markdown instead of MDX.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview	Aug 26, 2026 9:30pm

[ShaneK]

Looks good to me, great work! Just the i18n coupling I'd like made order-proof first

[ShaneK]

You've already got the coupling written up on #4663, so this is just the measurement from this side: building --locale ja on this branch exits 1 with 428 Cannot find module errors, one for every usage import in the i18n/ja tree that i18n.sh pulls.

Same worry I had on the api partials, and the same ask: can we make this safe whatever order things merge in? Back to back is fine right up until something else merges to main in the gap, and nothing here would catch that, since CI never builds and previews are --locale en. Adding resolve.extensionAlias with '.md': ['.mdx', '.md'] to the configureWebpack hook in the component-api plugin would do it without 863 duplicate files, though it does apply to every .md import in the repo, so a genuinely missing file stops being an error. I'd want it carrying the same TODO(FW-6456) note as the transitional block above it, and something filed to track dropping it.

[thetaPC]

846734e

[ShaneK]

The five @site/docs/developing/config partials imported above this line are the same shape as the ones you're renaming here, imports and Tabs JSX inside a .md file. #4663 says they're coming in a later PR in the series, which works for me. Could you file something to track it? Nothing on this PR says they're deferred, and this series has enough moving parts that I'd rather it didn't live only in a sibling PR's description.

One thing for whoever picks it up: versioned_docs/version-v8/developing/config/*/index.md exists too, but nothing reads it, since the v8 page imports these current-version copies instead of its own.

[thetaPC]

I've updated the Jira ticket to keep track of this.

[ShaneK]

Nit: the version prompt above still offers choices: ['6', '7', '8', '9'], so picking 6 or 7 scaffolds an index.mdx into a tree that's otherwise all index.md. Up to you whether that's worth trimming, I doubt anyone's picking them at this point.

[thetaPC]

I'll create a PR for this since Contributing will also need to be updated.