chore(i18n, docs): rename doc pages and usage partials to .mdx

[thetaPC]

Issue URL: internal

What is the current behavior?

Most doc pages on this branch are named .md while actually being MDX: they import components and render JSX. They work today only because Docusaurus still parses .md as MDX by default.

Docusaurus is moving toward Strict MDX, where .md is parsed as CommonMark instead. Once that flag is enabled, every import becomes literal text and every component renders as nothing.

That flag will be enabled on main and on this branch. Main has already moved its pages over, so leaving this branch behind would mean it breaks at that point rather than at a time of our choosing.

What is the new behavior?

951 files are renamed to .mdx: 265 pages under docs, 255 under versioned_docs/version-v8, and the 431 playground partials under static/usage/v8.

The references to them are rewritten to match: 654 markdown links, 935 component API imports, 439 playground imports, and the 5 config partial imports. Each link was resolved to the file it actually points at and rewritten only where that file became .mdx.

Two config fixes come with it.

The editUrl patterns in docusaurus.config.js were not anchored, so api/(.*)\.md still matched api/alert.mdx, captured the name, and produced a link to a file that no longer exists. Every API page's "Edit this page" link would have pointed at a missing file with nothing in the build to report it. This matches the fix already on main.

The glossary entries in .prettierignore named the old extension, so the rename silently dropped those files out of the ignore list. That protection is still needed here: this branch's glossary pages use raw HTML anchors, and prettier's mdx parser reflows their children onto separate lines, which MDX then wraps in a paragraph and renders as invalid markup. The patterns now cover both extensions, which also keeps the archived v7 copy protected.

Three groups are deliberately left as .md.

Archived versions are untouched: v5, v6 and v7 keep all of their pages and their static/usage partials, since those versions are never built.

The generated trees, docs/native and docs/cli/commands and their v8 copies, are rewritten by the generation scripts on every build and self-ignore through nested .gitignore files. The 66 links pointing into them are unchanged for the same reason.

docs/README.md and its v8 copy are contributor notes with no imports or JSX, and exclude: ['README.md'] keeps them out of the site. Renaming them would drop them out of that exclude and publish them as pages.

Does this introduce a breaking change?

• Yes
• No

Other information

This does not need to be coordinated with anything on main. That was verified rather than assumed: a Japanese build combining main's tree with this branch's prose in its unmigrated form completed with no errors and no unresolved modules, because the extensionAlias entry resolves the old names. The two branches can move independently.

It does depend on the plugin change that already merged here, which is what makes the .mdx partial names exist for this branch's own build to import.

The scope is larger than main's equivalent PR because it also completes what the playground rename deliberately left behind. That PR moved only the v9 partials, since this branch's versioned_docs was out of scope at the time. Migrating the v8 pages means their partials have to follow, so they are included here.

Verification was done by diffing a full build against a build of this branch taken before any changes, since a wrong link does not fail the build. onBrokenLinks is only set to warn, so a mistake here would ship silently. The build produces 2326 pages both before and after, with 0 errors. Broken links stay at 24 and broken anchors at 103, with none introduced. Prettier reports no differences across the touched paths.

How to test

Nothing should look different. The rename changes how pages are named and linked, not what they contain, so a failure shows up as a missing page, a dead link, or an empty API table rather than as altered prose.

1. Button, current version confirms an API page renders its generated tables and its playgrounds.
2. Button, v8 is the same check against the versioned tree, whose partials moved in this PR.
3. Config, current version renders the five partials whose imports changed.
4. Glossary, current version should render each definition as a single paragraph with an inline link. Link text sitting on its own line above the definition would mean the prettier protection was lost.

On each page, check that the content renders, that the framework tabs in each playground show code, and that no raw import line or literal component tag appears in the text.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview	Aug 31, 2026 10:45pm

[ShaneK]

Looks good to me, awesome work 🎉