fix(mdx-loader): parse markdown.mdx1Compat comments to AST so explicit heading IDs are recognized

packages/docusaurus-mdx-loader/src/__tests__/processor.test.ts

@@ -290,6 +290,22 @@ Body
     expect(result.content).toMatchSnapshot();
   });
 
+  it('extracts explicit heading ID from HTML comment with mdx1Compat.comments', async () => {
+    const options = createOptions({
+      markdownConfig: {
+        format: 'md',
+        mdx1Compat: {comments: true},
+      },
+    });
+    const result = await processContent(
+      '## Hello World <!-- #my-explicit-id -->',
+      options,
+    );
+    expect(result.content).toContain('id: "my-explicit-id"');
+    expect(result.content).toContain('"value": "Hello World"');
+    expect(result.content).not.toContain('hello-world');
+  });
+
   it('preserves legacy heading IDs', async () => {
     const options = createOptions();
     const result = await processContent('## Heading {#custom-id}', options);

packages/docusaurus-mdx-loader/src/processor.ts

@@ -169,7 +169,9 @@ function createProcessorUncached({
       } satisfies TransformLinksOptions,
     ],
     gfm,
-    options.markdownConfig.mdx1Compat.comments ? remarkComment : null,
+    options.markdownConfig.mdx1Compat.comments
+      ? [remarkComment, {ast: true}]
+      : null,
     ...(options.remarkPlugins ?? []),
     [
       unusedDirectives,

packages/docusaurus-mdx-loader/src/remark/headings/__tests__/index.test.ts

@@ -10,6 +10,7 @@
 import {describe, expect, it} from 'vitest';
 import {remark} from 'remark';
 import mdx from 'remark-mdx';
+import remarkComment from '@slorber/remark-comment';
 import {u} from 'unist-builder';
 import {visit} from 'unist-util-visit';
 import {escapeMarkdownHeadingIds} from '@docusaurus/utils';
@@ -439,6 +440,30 @@ describe('headings remark plugin', () => {
           const id = await headingIdFor('# Heading {/* #my-id */}', 'md');
           expect(id).not.toEqual('my-id');
         });
+
+        it('extracts id from HTML comment when remarkComment is enabled', async () => {
+          const result = await process(
+            '## Heading <!-- #my-id -->',
+            [[remarkComment, {ast: true}]],
+            {},
+            'md',
+          );
+          const heading = result.children[0] as Heading;
+          expect((heading.data as {id: string}).id).toEqual('my-id');
+          expect(heading).toEqual(h('Heading', 2, 'my-id'));
+        });
+
+        it('removes the remark-comment node when it is the only heading content', async () => {
+          const result = await process(
+            '## <!-- #id-only -->',
+            [[remarkComment, {ast: true}]],
+            {},
+            'md',
+          );
+          const heading = result.children[0] as Heading;
+          expect((heading.data as {id: string}).id).toEqual('id-only');
+          expect(heading).toEqual(h(null, 2, 'id-only'));
+        });
       });
 
       describe('works for format MDX', () => {

packages/docusaurus-mdx-loader/src/remark/headings/index.ts

@@ -61,6 +61,15 @@ function getCommentHeadingId(heading: Heading): string | undefined {
     }
   }
 
+  // remark-comment AST node: <!-- my-id --> or <!-- #my-id -->
+  if (lastChild?.type === ('comment' as unknown)) {
+    const commentContent = (lastChild as unknown as {commentValue?: string})
+      .commentValue;
+    if (commentContent) {
+      return getCommentContentHeadingId(commentContent);
+    }
+  }
+
   return undefined;
 }
 
@@ -114,7 +123,7 @@ const plugin: Plugin<PluginOptions[], Root> = function plugin({
   return (root) => {
     function getHeadingText(heading: Heading) {
       const headingTextNodes = heading.children.filter(
-        ({type}) => !['html', 'jsx'].includes(type),
+        ({type}) => !['html', 'jsx', 'comment'].includes(type),
       );
       return toString(headingTextNodes.length > 0 ? headingTextNodes : heading);
     }