chore(i18n, usage): rename playground partials to .mdx and update imports

[thetaPC]

Issue URL: internal

What is the current behavior?

The translated pages import playground partials by explicit path, for example @site/static/usage/v9/accordion/basic/index.md. Each of those partials imports the Playground component and renders JSX, so they are MDX files carrying a .md extension. Docusaurus is moving toward parsing .md as plain CommonMark, which would turn those imports into literal text and render every playground blank.

The companion PR on main renames the same partials there. Because this branch is a full fork of the repository rather than a prose only branch, it carries its own copy of static/usage, and @site resolves against whichever checkout is being built. That means the rename has to happen here too, not just on main.

What is the new behavior?

Two matching halves.

The 432 index.md partials under static/usage/v9 are renamed to index.mdx, and the 441 references to them across 76 files under docs are updated to match.

Three things are deliberately left alone.

The 19 @site/static/img references are unaffected by the rename.

The 5 @site/docs/developing/config partial imports stay as .md. Those files are renamed later in this series, and changing them here would break them. That work is tracked on the card, including the fact that this branch needs a matching rename when they flip.

static/usage/v6, v7, and v8 keep their .md partials, and versioned_docs is not touched at all. Renaming them would break this branch in the other direction, because its own versioned_docs imports those partials and preview builds render version-v8 from them. The trees stay internally consistent.

Does this introduce a breaking change?

• Yes
• No

Other information

Merge this after the companion PR on main. There is no time pressure once that lands, but the order does matter.

That PR adds a resolve.extensionAlias entry mapping .md to .mdx, so main's tree keeps serving the old names after its rename. Any Japanese page still importing .md resolves correctly, which means this branch can follow at any point and anything merging to main in between is safe. The alias only works in that direction though: it rewrites .md requests to find .mdx files, not the reverse. Merging this branch first would leave these imports asking for .mdx files main does not have yet, and nothing would rescue that.

Only the current version is translated here, which is why nothing under versioned_docs needs updating for the Japanese site. scripts/i18n.sh extracts only this branch's docs directory into the localized content path, so every older version falls back to main's English pages. The versioned_docs copies on this branch are untranslated snapshots that are never built or served: v8 contains Japanese text in 1 of 257 files and v7 in 0 of 241. Main's own versioned_docs/version-v8 is what actually serves those pages, and the companion PR already updates it.

Verification performed locally: a full build with the same command the preview deploy runs completes successfully, reporting 0 errors, 0 warnings, 0 unresolved modules, and 0 broken links. The two broken anchors it reports both predate this work and are unrelated to imports. Prettier reports no formatting changes.

The gap state was also verified directly, by building --locale ja from the companion branch combined with this branch's prose in its unmerged form. Without the alias that build fails with 428 unresolved modules. With it, the same build completes and emits 2298 pages with playgrounds rendering.

How to test

Open each page below and confirm the playgrounds still render. This branch renames its own copy of the v9 partials, 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 is the regression check. The v8 partials were deliberately left as .md, so this page should look exactly as it does today.

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.

One limit worth knowing. This preview builds a single English locale from this branch's own files, which is why the pages show Japanese prose under an English locale. The way the Japanese site is actually assembled in production, main's tree combined with this branch's prose, is not reproducible in any preview, which is why that path was verified locally instead.

[vercel]

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

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

[ShaneK]

LGTM! Just a minor nit

[ShaneK]

Same five @site/docs/developing/config partials as the thread on #4662, so I won't repeat the ask here. Could that card also mention that this branch needs a companion whenever they flip? Same reason as this pair.

[thetaPC]

Added it to the Jira ticket

[ShaneK]

Oops, the other comment was supposed to be approve 🤦