chore(api): generate component API partials as .mdx

[thetaPC]

Issue URL: internal

What is the current behavior?

The component API plugin writes its generated partials with a .md extension: props, events, methods, parts and slots. Those files are MDX, not CommonMark, so the extension is inaccurate. The sixth partial, custom-props, is already .mdx, which suggests this was hit once before and fixed for a single file.

Each API page then imports them by explicit filename, so the extension is repeated across every page, for example importing Props from @ionic-internal/component-api/v8/button/props.md.

What is the new behavior?

The plugin emits .mdx for the five remaining partials, and the import specifiers are updated to match.

• 5 lines in plugins/docusaurus-plugin-ionic-component-api/index.js
• 910 import specifiers across 181 pages in docs/ (94) and versioned_docs/version-v7 (87)

Every doc file change is a specifier swap; there are no other edits.

Does this introduce a breaking change?

• Yes
• No

Other information

Part of the mdx migration.

How to test

Check a page where all six partial types have content:

• Current version: https://ionic-docs-git-fw-6456-pt4b-ionic1.vercel.app/docs/api/modal
  • Scroll to the bottom and confirm Properties, Events, Methods, CSS Shadow Parts, CSS Custom Properties and Slots all render with real content
• Versioned tree: https://ionic-docs-git-fw-6456-pt4b-ionic1.vercel.app/docs/v7/api/select
  • Same six sections; this confirms the version-v7 specifiers were rewritten too

The content, datetime, popover and select pages also populate all six if you want another sample.

[vercel]

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

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

[ShaneK]

I'm worried about the impact of these changes on i18n

[ShaneK]

This one worries me a bit, it breaks the ja build.

Our i18n.sh step pulls the translation/jp branch's docs/ tree into i18n/ja on every build, and those are whole-file copies with their own import block, still pointing at props.md and the rest. Building --locale ja on this commit fails with 470 Cannot find module errors against the old partial names. English is fine, and previews only build --locale en, so nothing here catches it. Production builds both.

The custom-props partial needed the same treatment when it flipped in 60443e2. There's a jp sync open right now in #4641 and it still has the old imports on all 94 pages, so that one won't cover it either.

Could you keep writing the five .md partials alongside the new .mdx ones, and drop them once translation/jp has caught up? They go to .docusaurus rather than a docs content root, so the duplicate basenames won't collide.

[ShaneK]

This also breaks major-9.0 on the next merge down, and the merge can't carry the fix over.

The change here merges clean there, so createData stops writing .md right away. But the v8 tree under versioned_docs keeps .md across 94 pages, and that directory doesn't exist on main, so nothing in the merge touches it. The v9 pages conflict instead, 89 of them, because that branch points at v9 where main points at v8, and keeping ours in that conflict keeps .md with it.

Writing both extensions for now covers this as well, otherwise it wants a companion PR on major-9.0 first, since nothing there covers it yet. The page edits here aren't generated output, whatever CLAUDE.md says about docs/api, so they shouldn't get dropped as stale in that merge.