chore(docs): rename doc pages to .mdx

[thetaPC]

Issue URL: internal

What is the current behavior?

Doc pages are named .md, but most of them are 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. When that default changes, every import becomes literal text and every component renders as nothing.

What is the new behavior?

512 pages are renamed to .mdx: 257 under docs and 255 under versioned_docs/version-v8.

641 links to those pages are rewritten to match. They appear in three shapes, and all three resolve today, so all three would have broken: relative links such as ../api/button.md, site absolute links such as /docs/api/button.md, and bare sibling links such as colors.md. Each link was resolved to the file it actually points at and rewritten only when that file became .mdx.

The ten @site/docs/developing/config partial imports are updated, which covers the five partials deferred from the playground rename.

docusaurus.config.js needed a fix that is easy to miss. The editUrl patterns were not anchored, so api/(.*)\.md still matched api/alert.mdx, captured the name, and produced a link to a .md file that no longer exists. Every API page's "Edit this page" link would have pointed at a missing file, and nothing in the build would have reported it. The patterns are now anchored on the extension and carry the real one through.

Three groups are deliberately left as .md.

The generated trees, docs/native and docs/cli/commands, are written by scripts/native.mjs and scripts/cli.mjs on every build and self-ignore through nested .gitignore files. Renaming them would only fight the generators. The 87 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.

Archived versions are untouched. v5, v6 and v7 keep all of their .md pages, since those versions are never built.

Does this introduce a breaking change?

• Yes
• No

Other information

Merge this before the companion PR on translation/jp. There is no time pressure after that, but the order matters: the extensionAlias entry added earlier rewrites .md requests to find .mdx files, not the reverse.

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 2298 pages both before and after, with 0 errors. Broken links stay at 21 and broken anchors at 47, with none introduced by this change. Prettier reports no differences repo wide.

Two table alignments in theming/advanced.mdx shifted, because .mdx is one character longer than .md and the links sit inside a markdown table. Both files were clean before, so this is Prettier restoring the alignment the rename disturbed.

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 or a dead link rather than as altered prose.

1. Button, current version confirms an API page with partials and playgrounds still renders.
2. Angular quickstart, v8 has ten absolute links to API pages, the form most likely to break.
3. Config, current version renders the five partials whose imports changed.
4. CSS utilities, current version is a common link target, reached from the Grid page among others.

On each page, check that the content renders, that inbound links from the pages above land somewhere real, and that no raw import line or literal component tag appears in the text.

Also worth checking one "Edit this page" link at the bottom of an API page. It should open an existing .mdx file on GitHub rather than a 404.

[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 6:12pm

[ShaneK]

Looks good to me, awesome work 🎉