[Aryan9891]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Fixes #12927.

When markdown.mdx1Compat.comments: true is configured in docusaurus.config.js, standard HTML comment syntax (<!-- #my-id -->) in Markdown headings was failing to extract explicit heading IDs:

• In processor.ts, remarkComment was loaded without { ast: true }, leaving comment nodes as unparsed raw text rather than structured AST comment nodes.
• In packages/docusaurus-mdx-loader/src/remark/headings/index.ts, getHeadingId only inspected lastChild.type === 'mdxJsxTextElement'. When MDX1 comment compatibility is enabled, comments are represented as AST nodes with type: 'comment'.
• In getHeadingText, comment nodes were not excluded, which could allow comment syntax to leak into heading titles and table of contents.

This PR:

1. Passes { ast: true } to remarkComment in processor.ts when mdx1Compat.comments is enabled.
2. Updates headings/index.ts to recognize lastChild.type === 'comment' and extract explicit #id comments from lastChild.value.
3. Ensures getHeadingText filters out node.type === 'comment' so the heading title string remains clean.
4. Adds unit tests in headings/__tests__/index.test.ts covering explicit #id HTML comments, non-id comments, and clean heading title extraction with MDX1 comment compatibility enabled.

Test Plan

Local unit test verification:
``bash
npx vitest run packages/docusaurus-mdx-loader/src/remark/headings/tests/index.test.ts

Result: 33/33 tests passed

``

Test links

Deploy preview: https://deploy-preview-12928--docusaurus-2.netlify.app/

Related issues/PRs

Closes #12927

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	9e21b5c
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6aef8cf7bb72e8b3c916c97f
😎 Deploy Preview	https://deploy-preview-12928--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.