chore(api): generate heading IDs with MDX comment syntax

[thetaPC]

Issue URL: internal

What is the current behavior?

The component API plugin generates heading IDs using the classic {#my-id} syntax: spinner {#prop-spinner}

Docusaurus calls this "proprietary Docusaurus syntax, leading to ecosystem incompatibilities" and recommends the native MDX comment form instead.. We migrated our hand written docs off this syntax in #4628, but the plugin kept emitting it, so it comes back on every build. On main that is 1435 headings across 910 generated partials (1263 property headings, 172 method headings).

What is the new behavior?

The plugin emits the MDX comment form: spinner {/* #prop-spinner */}

Two lines change, one for properties and one for methods, which covers all 1435 headings. No other partial type is affected: events, parts, slots and custom-props contain tables rather than headings.

Does this introduce a breaking change?

• Yes
• No

Other information

Part of the mdx migration.

No anchors change. Both syntaxes produce the same id, so #prop-spinner, #method-dismiss and every other API anchor continue to resolve.

How to test

Check that each heading renders its name only, with no visible {/* ... */} text, and that both the anchor link and the table of contents entry jump to it.

• Properties: https://ionic-docs-git-fw-6456-pt4-ionic1.vercel.app/docs/api/loading
  • The spinner heading should link to #prop-spinner
• Methods: https://ionic-docs-git-fw-6456-pt4-ionic1.vercel.app/docs/api/alert
  • The dismiss heading should link to #method-dismiss
• Deprecated properties: https://ionic-docs-git-fw-6456-pt4-ionic1.vercel.app/docs/v7/api/input
  • accept (deprecated) should link to #prop-accept
  • This is the case where the comment sits next to the (deprecated) interpolation on the same line
• Links into generated anchors: https://ionic-docs-git-fw-6456-pt4-ionic1.vercel.app/docs/api/datetime#showing-confirmation-buttons
  • In the Showing Confirmation Buttons section, the sentence "The default Done and Cancel buttons are already preconfigured to call the confirm and cancel methods" has two links
  • Both should jump down to those method headings under Methods
  • This is the only page in the repo with hand written links into plugin generated anchors

[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 9:47pm

[ShaneK]

LGTM!