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:
YeonGyu-Kim
2026-05-08 16:14:55 +09:00
parent 810e3c7a51
commit e5369f3a63
10 changed files with 441 additions and 1238 deletions
+1 -172
View File
@@ -247,178 +247,7 @@
},
"docs": {
"mobileHeader": "Oh My OpenAgent 文档",
"searchPlaceholder": "搜索文档...",
"sections": {
"overview": "概览",
"quickStart": "快速开始",
"configLocations": "配置文件位置",
"agents": "Agents",
"categories": "分类",
"skills": "Skills",
"backgroundTasks": "后台任务",
"hooks": "钩子",
"mcps": "MCPs",
"browserAutomation": "浏览器自动化",
"tmux": "Tmux 集成",
"gitMaster": "Git Master",
"commentChecker": "注释检查器",
"experimental": "实验性功能",
"lsp": "LSP 配置",
"envVars": "环境变量"
},
"overview": {
"title": "配置参考",
"description": "Oh My OpenAgent 高度自有主张,但可根据个人喜好调整。大多数用户无需配置——运行 {command} 即可开始。"
},
"quickStart": {
"title": "快速开始"
},
"configLocations": {
"title": "配置文件位置",
"projectLevel": "(项目级)",
"userLevel": "(用户级)",
"jsonc": "支持 JSONC 格式,允许注释和尾随逗号。"
},
"agentsSection": {
"title": "Agents",
"description": "为内置 Agent 配置特定行为:Sisyphus、Hephaestus、Oracle、Librarian、Explore、Multimodal Looker、Prometheus、Metis、Momus、Atlas 和 Sisyphus Junior。",
"overrideOptions": "覆盖选项",
"permissions": "权限",
"options": {
"model": "模型标识符(例如 openai/gpt-4o",
"variant": "模型变体(max、high、medium、low",
"category": "从分类继承配置",
"temperature": "采样温度(0-2",
"topP": "Top-p 采样(0-1",
"prompt": "完全覆盖系统提示词",
"promptAppend": "在系统提示词后追加文本",
"tools": "启用或禁用特定工具",
"disable": "禁用此 Agent",
"maxTokens": "响应的最大 token 数",
"thinking": "扩展思考配置",
"reasoningEffort": "推理强度:low、medium、high、xhigh"
},
"permissionValues": "ask / allow / deny",
"permissionDescriptions": {
"edit": "文件编辑能力",
"bash": "Bash 命令执行",
"webfetch": "网络请求能力",
"doomLoop": "无限循环覆盖",
"externalDirectory": "访问项目外部文件"
}
},
"categoriesSection": {
"title": "分类",
"description": "分类允许你定义 Agent 可以继承的共享配置。",
"availableOptions": "分类可用选项:{options}。",
"categories": {
"visualEngineering": "前端、UI/UX、设计任务",
"ultrabrain": "深度逻辑推理",
"deep": "自主解决问题与深入研究",
"artistry": "创意任务",
"quick": "简单、快速任务",
"unspecifiedLow": "低投入一般任务",
"unspecifiedHigh": "高投入一般任务",
"writing": "文档和写作"
}
},
"skillsSection": {
"title": "Skills",
"description": "内置技能包括 {playwright}、{agentBrowser} 和 {gitMaster}。你也可以定义自定义技能。"
},
"backgroundTasksSection": {
"title": "后台任务",
"priority": "优先级:",
"options": {
"defaultConcurrency": "默认最大并发任务数",
"staleTimeoutMs": "过时任务超时时间(毫秒)",
"providerConcurrency": "每个提供商的并发限制",
"modelConcurrency": "每个模型的并发限制"
}
},
"hooksSection": {
"title": "钩子",
"description": "钩子允许你在各个生命周期点扩展功能。"
},
"mcpsSection": {
"title": "MCPs",
"websearch": {
"title": "websearch",
"description": "由 Exa 驱动,提供高质量搜索结果。"
},
"context7": {
"title": "context7",
"description": "文档检索和上下文管理。"
},
"grepApp": {
"title": "grep_app",
"description": "GitHub 代码搜索集成。"
}
},
"browserAutomationSection": {
"title": "浏览器自动化",
"playwright": {
"tool": "playwright",
"description": "完整的浏览器自动化(默认)",
"useCase": "测试、复杂交互"
},
"agentBrowser": {
"tool": "agent-browser",
"description": "轻量级浏览器 Agent",
"useCase": "快速查询、简单抓取"
}
},
"tmuxSection": {
"title": "Tmux 集成",
"options": {
"enabled": "启用 Tmux 集成",
"layout": "Tmux 窗口布局",
"mainPaneSize": "主面板大小"
}
},
"gitMasterSection": {
"title": "Git Master",
"options": {
"commitFooter": "追加到提交消息的文本",
"includeCoAuthoredBy": "添加 Co-authored-by 标记"
}
},
"commentCheckerSection": {
"title": "注释检查器",
"description": "验证代码中的注释。在自定义提示词中使用 {placeholder} 占位符。"
},
"experimentalSection": {
"title": "实验性功能",
"options": {
"aggressiveTruncation": "积极截断输出",
"autoResume": "自动恢复中断的任务",
"preemptiveCompaction": "在达到限制前压缩上下文",
"truncateAllToolOutputs": "截断所有工具输出"
},
"dynamicPruning": {
"trigger": "dynamic_context_pruning",
"description": "配置动态剪枝规则,高效管理上下文窗口使用。"
}
},
"lspSection": {
"title": "LSP 配置",
"options": {
"command": "LSP 服务器命令",
"extensions": "匹配的文件扩展名",
"priority": "服务器优先级",
"env": "环境变量",
"initialization": "初始化选项",
"disabled": "禁用此 LSP"
}
},
"envVarsSection": {
"title": "环境变量",
"opencodeConfigDir": {
"name": "OPENCODE_CONFIG_DIR",
"description": "覆盖默认配置目录路径。"
}
},
"footer": "Oh My OpenAgent 文档 © {year}"
"searchPlaceholder": "搜索文档..."
},
"manifesto": {
"badge": "宣言",