fix(cli): keep MDX comments in rawMarkdown for the visual editor

[devin-ai-integration]

Description

Linear ticket: N/A (reported in Slack #sales-eng-devin-runs)

The visual editor loads a page's source from rawMarkdown in the published docs definition (getNormalizedMarkdown in fern-platform prefers rawMarkdown over markdown). Since b57c131 (fix(cli): strip MDX comments from markdown output) the CLI applied stripMdxComments to both markdown and rawMarkdown, so {/* ... */} comments never reached the editor's code view, and the first editor commit wrote the stripped file back to the customer's repo (see fern-support/willktrial-437063#11).

This keeps the rendered markdown comment-free (public site / LLM output unchanged) and stores rawMarkdown verbatim:

- this.rawMarkdownFiles[path] = stripMdxComments(markdown);   // pages
- this.rawMarkdownFiles[path] = stripMdxComments(file.contents); // changelogs
- this.rawMarkdownFiles[path] = stripMdxComments(processedContent); // tag descriptions
+ this.rawMarkdownFiles[path] = markdown / file.contents / processedContent;

  pages[id] = { markdown: stripMdxComments(markdown), rawMarkdown }  // unchanged

Same change in docs-preview/previewDocs.ts for fern docs dev, and in the translated-page paths (buildTranslatedDocsDefinition.ts, publishDocs.ts, runPreviewServer.ts, runAppPreviewServer.ts), which previously set rawMarkdown: processedMarkdown and now use the original locale source.

Companion editor-side fix (inline comment round-trip + visible comment chip): fern-api/fern-platform#14450. Customers need to re-publish with a CLI containing this fix for existing pages to regain comments in the editor.

Changes Made

• DocsDefinitionResolver.ts: stop stripping comments from rawMarkdownFiles (pages, changelogs, tag descriptions); markdown still stripped
• previewDocs.ts: same for local preview
• Translated pages (buildTranslatedDocsDefinition.ts, publishDocs.ts, runPreviewServer.ts, runAppPreviewServer.ts): rawMarkdown = original locale source instead of processed markdown
• New docs-resolver test mdx-comments.test.ts + minimal fixtures/mdx-comments (top-level, nested-in-Callout, and inline comments); asserts markdown has no {/* and rawMarkdown equals the source file byte-for-byte
• New remote-workspace-runner test buildTranslatedDocsDefinition.test.ts with the same assertions for translated pages
• Unreleased changelog keep-mdx-comments-in-raw-markdown.yml (type: fix)
• Updated README.md generator (not applicable)

Testing

• Unit tests added/updated — docs-resolver 17 files / 119 tests pass, docs-markdown-utils 293 tests pass, new translated-page test passes; both new tests verified to fail with the fix stashed
• pnpm turbo run compile for docs-resolver, docs-preview, remote-workspace-runner (49/49 tasks), biome check clean
• Manual testing completed (requires publishing with the built CLI; not run)

Link to Devin session: https://app.devin.ai/sessions/ce3af3fd00c147ef8f83eed951b6592f
Open in Devin Desktop: https://app.devin.ai/desktop/session/ce3af3fd00c147ef8f83eed951b6592f?variant=devin

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[nitpickybot]

AI Review Summary

Small, focused fix: rawMarkdown is now stored verbatim while rendered markdown remains comment-stripped. Change looks correct and the test fixture covers the three comment placements. Only minor concerns: possible now-unused stripMdxComments import in previewDocs.ts (if it's no longer referenced elsewhere) and a brittle whitespace assertion in the test.

• 🔵 2 suggestion(s)

---

To request another review, comment /ai-review on this pull request.

[devin-ai-integration]

Devin Review found 1 potential issue.

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-09-03T05:10:38Z).

Fixture	main	PR	Delta
docs	269.1s (n=5)	248.5s (35 versions)	-20.6s (-7.7%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-09-03T05:10:38Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-09-03 21:31 UTC