fix(md-exports): strip empty HTML comments from markdown exports

React inserts empty `<!-- -->` separator comments between adjacent text
nodes in server-rendered output. On component-rendered pages like the API
docs, this littered the `.md` exports with artifacts such as
`(<!-- -->string<!-- -->)` around parameter types.

Drop comment nodes in the HTML-to-markdown pipeline. Comments are dispatched
by node type in hast-util-to-mdast, so the override goes in `nodeHandlers`
rather than `handlers` (where it would be silently ignored). The field type
text survives the strip, so `(<!-- -->string<!-- -->)` becomes `(string)`.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cvxluo

scripts/generate-md-exports.mjs

@@ -32,7 +32,7 @@ import {rehypeExpandCodeTabs} from './rehype-expand-code-tabs.mjs';
 const DOCS_ORIGIN = process.env.NEXT_PUBLIC_DEVELOPER_DOCS
   ? 'https://develop.sentry.dev'
   : 'https://docs.sentry.io';
-const CACHE_VERSION = 9;
+const CACHE_VERSION = 10;
 const CACHE_COMPRESS_LEVEL = 4;
 const R2_BUCKET = process.env.NEXT_PUBLIC_DEVELOPER_DOCS
   ? 'sentry-develop-docs'
@@ -1009,6 +1009,12 @@ async function genMDFromHTML(source, {cacheDir, noCache, usedCacheFiles}) {
       .use(rehypeExpandCodeTabs)
       .use(rehypeRemark, {
         document: false,
+        // Drop React's empty `<!-- -->` text-node separators, which otherwise leak into the
+        // markdown on component-rendered pages like the API docs. Comments dispatch by node
+        // type, so this must live in nodeHandlers rather than handlers.
+        nodeHandlers: {
+          comment() {},
+        },
         handlers: {
           // HACK: Extract the canonical URL during parsing
           link: (_state, node) => {

scripts/generate-md-exports.test.mjs

@@ -15,6 +15,9 @@ function htmlToMarkdown(html) {
       .use(rehypeExpandCodeTabs)
       .use(rehypeRemark, {
         document: false,
+        nodeHandlers: {
+          comment() {},
+        },
         handlers: {
           button() {},
         },
@@ -306,3 +309,23 @@ describe('rehypeExpandCodeTabs', () => {
     });
   });
 });
+
+describe('comment stripping', () => {
+  it('drops React text-node separator comments emitted on component-rendered pages', () => {
+    const html =
+      '<p><code>organization_id_or_slug</code><em> (<!-- -->string<!-- -->)</em></p>';
+
+    const md = htmlToMarkdown(html);
+
+    expect(md).not.toContain('<!--');
+    expect(md).toContain('string');
+  });
+
+  it('drops standalone HTML comments', () => {
+    const md = htmlToMarkdown('<p>before<!-- a real comment -->after</p>');
+
+    expect(md).not.toContain('<!--');
+    expect(md).toContain('before');
+    expect(md).toContain('after');
+  });
+});