<!-- #id --> explicit heading ID is ignored when markdown.mdx1Compat.comments is enabled (AI-assisted) #12927

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

The documented CommonMark explicit heading ID syntax (## Hello World <!-- #my-explicit-id -->, added in #11755) is ignored when markdown.mdx1Compat.comments is true (the default in Docusaurus 3.x without future.v4, or when explicitly enabled).

@slorber/remark-comment strips HTML comments during parsing before the headings remark plugin runs. When extractCommentId in packages/docusaurus-mdx-loader/src/remark/headings/index.ts checks heading.children.at(-1) for type === 'html', the comment node is already gone, and the trailing space before the comment remains on the text node. The heading is assigned id="hello-world-" instead of id="my-explicit-id", and links to #my-explicit-id are reported as broken anchors.

Reproducible demo

https://gist.github.com/trackoor/5d95dbc99c8cdb446c2870a2a2370762

Steps to reproduce

1. Run npx create-docusaurus@3.10.2 site classic --javascript

2. In docusaurus.config.js, configure markdown: { format: 'detect', mdx1Compat: { comments: true } } (or omit future.v4 so mdx1Compat.comments uses its 3.x default of true).

3. Create docs/a.md:

   # A
   
   ## Hello World <!-- #my-explicit-id -->

4. Create docs/b.md:

   # B
   
   [explicit](./a.md#my-explicit-id)

5. Run npm run build and inspect build/docs/a/index.html.

Expected behavior

build/docs/a/index.html renders <h2 ... id="my-explicit-id"> and npm run build succeeds without broken anchor warnings (which is what happens when mdx1Compat.comments is false).

Actual behavior

npm run build logs a broken anchor warning:

[WARNING] Docusaurus found broken anchors!

Exhaustive list of all broken anchors found:
- Broken anchor on source page path = /docs/b:
   -> linking to /docs/a#my-explicit-id

And grep -o '<h2[^>]*>' build/docs/a/index.html shows:

<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="hello-world-">

Also reproduced with @docusaurus/mdx-loader@4.0.0-canary-7078 and on main (c00f04e) when mdx1Compat.comments: true.

Your environment

• Public source code: https://gist.github.com/trackoor/5d95dbc99c8cdb446c2870a2a2370762
• Public site URL: n/a
• Docusaurus version used: 3.10.2 and 4.0.0-canary-7078 (main at c00f04e)
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js v26.13.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Linux x64

Self-service

• I'd be willing to fix this bug myself.

Found with a differential-testing tool; the report was drafted with AI assistance and reviewed and edited by me. (AI-assisted)

Credit: https://ucsbplse.github.io/