feat(web): render docs from repo-root docs/ as MDX SoT at build time
Replace the bespoke 16-section /docs page that pulled prose from
`messages/{locale}.json` with a build-time MDX renderer that reads the
canonical markdown in repo-root `docs/`. Each markdown file becomes
one section of the docs page, scrolled-to via the existing DocsShell
sidebar. Section data structure stays in `lib/docs-sections.ts` so the
sidebar / scroll-spy keeps working with no client changes.
Why this layout:
- One source of truth: `docs/guide/*.md`, `docs/reference/*.md`,
`docs/manifesto.md`. Edits land in one place; the website redeploys
pick them up automatically via the existing web-deploy workflow.
- Build-time only: `MDXRemote` is rendered inside an RSC and the page
is statically generated (`●` SSG). Cloudflare Workers serves the
rendered HTML; no MDX compiler runs at request time.
- next-intl unchanged for everything else: only the docs prose moves
out. `mobileHeader` and `searchPlaceholder` strings stay in
`messages/{locale}.json`; the 18 stale section keys are removed.
Files:
- web/lib/docs-sections.ts: 9 sections matching docs/ files, typed
`DocSection` with `{ id, title, file }`.
- web/lib/docs-source.ts: `loadDocSource(file)` reads
`<repo-root>/docs/<file>` at build time via `node:fs/promises`.
- web/components/docs/mdx-components.tsx: shadcn-styled overrides for
every markdown element (h1-h4, p, a, ul/ol/li, blockquote, code, pre,
table, hr, strong) so the rendered output matches the rest of the
site.
- web/app/[locale]/docs/page.tsx: rewritten as an async RSC that loads
every section's source in parallel and renders one MDXRemote per
section inside DocsShell.
- web/messages/{en,ja,ko,zh}.json: `docs` key trimmed from 20 entries
to 2 (mobileHeader, searchPlaceholder).
- web/package.json: + next-mdx-remote, + gray-matter.
Local verification: `bun run format:check`, `bun run lint`,
`bun run type-check`, `bun run build`, `bunx opennextjs-cloudflare
build` all pass; `/[locale]/docs` builds as static for all 4 locales
at 4.12 kB / 132 kB First Load.
This commit is contained in:
+22
-36
@@ -1,39 +1,25 @@
|
||||
export const DOC_SECTION_IDS = [
|
||||
"overview",
|
||||
"quick-start",
|
||||
"config-locations",
|
||||
"agents",
|
||||
"categories",
|
||||
"skills",
|
||||
"background-tasks",
|
||||
"hooks",
|
||||
"mcps",
|
||||
"browser-automation",
|
||||
"tmux",
|
||||
"git-master",
|
||||
"comment-checker",
|
||||
"experimental",
|
||||
"lsp",
|
||||
"env-vars",
|
||||
export type DocSection = {
|
||||
id: string
|
||||
title: string
|
||||
file: string
|
||||
}
|
||||
|
||||
export const DOC_SECTIONS: readonly DocSection[] = [
|
||||
{ id: "overview", file: "guide/overview.md", title: "Overview" },
|
||||
{ id: "installation", file: "guide/installation.md", title: "Installation" },
|
||||
{ id: "orchestration", file: "guide/orchestration.md", title: "Orchestration" },
|
||||
{
|
||||
id: "agent-model-matching",
|
||||
file: "guide/agent-model-matching.md",
|
||||
title: "Agent / Model Matching",
|
||||
},
|
||||
{ id: "team-mode", file: "guide/team-mode.md", title: "Team Mode" },
|
||||
{ id: "cli", file: "reference/cli.md", title: "CLI Reference" },
|
||||
{ id: "configuration", file: "reference/configuration.md", title: "Configuration" },
|
||||
{ id: "features", file: "reference/features.md", title: "Features" },
|
||||
{ id: "manifesto", file: "manifesto.md", title: "Manifesto" },
|
||||
] as const
|
||||
|
||||
export type DocSectionId = (typeof DOC_SECTION_IDS)[number]
|
||||
export const DOC_SECTION_IDS = DOC_SECTIONS.map((s) => s.id)
|
||||
|
||||
export const DOC_SECTION_TITLE_KEYS: Record<DocSectionId, string> = {
|
||||
overview: "overview",
|
||||
"quick-start": "quickStart",
|
||||
"config-locations": "configLocations",
|
||||
agents: "agents",
|
||||
categories: "categories",
|
||||
skills: "skills",
|
||||
"background-tasks": "backgroundTasks",
|
||||
hooks: "hooks",
|
||||
mcps: "mcps",
|
||||
"browser-automation": "browserAutomation",
|
||||
tmux: "tmux",
|
||||
"git-master": "gitMaster",
|
||||
"comment-checker": "commentChecker",
|
||||
experimental: "experimental",
|
||||
lsp: "lsp",
|
||||
"env-vars": "envVars",
|
||||
}
|
||||
export type DocSectionId = (typeof DOC_SECTIONS)[number]["id"]
|
||||
|
||||
Reference in New Issue
Block a user