Migrate docs to MDX with self-dogfooding fingerprint + CLI rendering#37
Merged
nahiyankhan merged 2 commits intomainfrom Apr 20, 2026
Merged
Migrate docs to MDX with self-dogfooding fingerprint + CLI rendering#37nahiyankhan merged 2 commits intomainfrom
nahiyankhan merged 2 commits intomainfrom
Conversation
Three prose pages (self-hosting, getting-started, cli-reference) move from handwritten JSX to MDX so the docs corpus is LLM-maintainable and diff-friendly. Interactive pages (concepts, components, foundations) stay as React. Pipeline: @mdx-js/rollup + remark-gfm/remark-frontmatter + rehype-slug/autolink/shiki wired into apps/docs. Zod-validated frontmatter drives routing via import.meta.glob; a new DocsMdxRoute reuses the existing DocsPageLayout + AnimatedPageHeader + DocProse so visual parity is preserved. Self-dogfooding: - New @ghost/core/browser subpath export re-exports only pure modules (parse, lint, diff, reporters, types). FingerprintPreview + FingerprintSample MDX components parse and lint a real fingerprint.md in the browser. - New scripts/dump-cli-help.mjs walks the cac registry via buildCli() from the refactored ghost-cli/cli.ts and emits apps/docs/src/generated/cli-manifest.json. CliHelp MDX component renders flag tables from the manifest; CLI reference page collapses from 539 JSX lines to ~170 MDX lines. Validation: check:docs lints MDX frontmatter, broken internal links, and runs lintFingerprint against fingerprint samples. check:cli-manifest fails when the committed CLI manifest drifts from the CLI. Both wired into pnpm check. Design vocabulary: swapped 'design system' to 'design language' across docs, skill bundle, types, fingerprint samples, and the review-command generator (snapshot regenerated). Renamed 'Drift Engine' to 'Drift' and 'How Ghost Works' to 'How Ghost Drift Works'. Self-hosting page carries a yellow Callout banner flagging the end-to-end flow as untested; project's @theme resets the default Tailwind palette so the callout uses the project's yellow swatches, not amber. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
scripts/check-docs-frontmatter.mjs runs from the repo root and imports gray-matter + zod. Locally, pnpm hoisted both from workspace transitives (apps/docs already depends on zod + gray-matter), so the script resolved them. CI with stricter pnpm isolation (shamefully-hoist=false in .npmrc) doesn't hoist transitively, so the script can't find them. Also fix a biome template-literal warning in the same script. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
self-hosting,getting-started,cli-reference) migrate from handwritten JSX to MDX so the docs corpus is LLM-maintainable. Interactive pages (concepts, components, foundations) stay as React.@ghost/core/browsersubpath, and a CLI reference that renders from a codegen'd manifest walked off thecacregistry — docs can't drift from CLI behavior.design system→design languageacross docs, skill bundle, types, and the review-command generator.Drift Engine→Drift. Self-hosting page carries a yellow "Work in progress" banner flagging the end-to-end flow as untested.What's new
MDX pipeline —
@mdx-js/rollup+remark-gfm/remark-frontmatter/remark-mdx-frontmatter+rehype-slug/rehype-autolink-headings/@shikijs/rehype. Zod-validated frontmatter atsrc/content/docs-frontmatter.tsdrives routing viaimport.meta.glob.DocsMdxRoutereuses existingDocsPageLayout+AnimatedPageHeader+DocProseso there's no visual regression.Browser-safe core — new
./browsersubpath export in@ghost/corere-exports only pure modules (parse,lint,diff,reporters, types) via deep file-level imports. Node-only modules (sync.js,history.js,parent.js,writer.js) stay out of the browser bundle.Fingerprint hooks —
<FingerprintPreview>/<FingerprintSample>MDX components parse and lint a realfingerprint.mdinline. Sample atapps/docs/src/content/fingerprint-samples/ghost-ui.mdis lint-gated in CI.CLI manifest codegen —
packages/ghost-cli/src/cli.tsnow exportsbuildCli()(bin.tsis a 5-line runner).scripts/dump-cli-help.mjswalks the cac registry and writesapps/docs/src/generated/cli-manifest.json.<CliHelp command="…">renders flag tables from the manifest; the CLI reference page shrinks from 539 JSX lines to ~170 MDX lines.Validation —
check:docsvalidates MDX frontmatter, scans for broken internal links, and runslintFingerprintagainst fingerprint samples.check:cli-manifestfails when the committed manifest drifts from the CLI. Both wired intopnpm check.Test plan
pnpm check(biome + typecheck + file-sizes + docs frontmatter + CLI manifest drift)pnpm test(159 tests, snapshot regenerated after design-language rename)pnpm --filter @ghost/docs buildcleanpnpm --filter @ghost/docs dev— browse/tools/drift/self-hosting(yellow banner),/tools/drift/getting-started(inline FingerprintSample),/tools/drift/cli(generated flag tables)apps/docs/src/content/docs/self-hosting.mdx→ HMR reloads with no rebuildpackages/ghost-cli/src/cli.ts, runpnpm dump:cli-help→ CLI reference picks it up🤖 Generated with Claude Code