From 9d48e596ea5fdeff8daf63586cdbba47a4fd0df5 Mon Sep 17 00:00:00 2001
From: Charlie Luo <cvxluo@gmail.com>
Date: Mon, 1 Jun 2026 16:19:51 -0700
Subject: [PATCH] fix(md-exports): clean up artifacts in API docs markdown
 exports

Two sources of noise leaked into the API .md exports, e.g.
`*&#x20;<!-- -->(<!-- -->string<!-- -->)*`:

- React inserts empty `<!-- -->` separator comments between adjacent text
  nodes in server-rendered output (common on component-rendered pages like
  the API docs). Drop comment nodes in the HTML->markdown pipeline; comments
  dispatch by node type, so this lives in nodeHandlers, not handlers.
- The parameter type was wrapped in an <em> with a leading space inside it,
  which remark encoded as `&#x20;`. Move the space outside the <em> so it
  serializes as a normal space.

Also bump CACHE_VERSION, since cached entries are keyed on input HTML (not on
this script) and would otherwise serve stale output after the logic change.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 scripts/generate-md-exports.mjs      |  8 +++++++-
 scripts/generate-md-exports.test.mjs | 23 +++++++++++++++++++++++
 src/components/apiPage/index.tsx     |  3 +--
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/scripts/generate-md-exports.mjs b/scripts/generate-md-exports.mjs
index e07e71fc4ef6d3..a1f505d6a7ca6e 100644
--- a/scripts/generate-md-exports.mjs
+++ b/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) => {
diff --git a/scripts/generate-md-exports.test.mjs b/scripts/generate-md-exports.test.mjs
index 65074eb9116e6e..30b09b776afcf4 100644
--- a/scripts/generate-md-exports.test.mjs
+++ b/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');
+  });
+});
diff --git a/src/components/apiPage/index.tsx b/src/components/apiPage/index.tsx
index 8b98eeeb665308..d49fd86eaa1557 100644
--- a/src/components/apiPage/index.tsx
+++ b/src/components/apiPage/index.tsx
@@ -20,10 +20,9 @@ function Params({params}) {
           <Fragment key={param.name}>
             <dt>
               <div>
-                <code data-index>{param.name}</code>
+                <code data-index>{param.name}</code>{' '}
                 {!!param.schema?.type && (
                   <em>
-                    {' '}
                     ({param.schema.type}
                     {param.schema.items && `(${param.schema.items.type})`})
                   </em>