Docusaurus 技术方案
# Docusaurus 技术方案
1. 覆盖范围
Docusaurus 是 MVP 的文档展示产品，负责把已审批的 publish/** 渲染成可阅读文档站。
| LLM-WIKI 产品 | Docusaurus 支撑能力 |
|---|---|
| 文档展示产品 | 页面阅读、导航、版本化扩展、静态站点 |
| 文档编辑产品 | 提供“编辑此页”入口跳转 GitHub PR 流程 |
| 问答产品 | 提供页面内问答组件挂载点 |
| 知识索引产品 | 提供页面路径、标题、heading anchor |
2. 如何购买或获取
Docusaurus 是开源工具，不需要购买软件许可。MVP 只需要承担静态站点托管成本。
托管选择：
| 方式 | 建议 |
|---|---|
| GitHub Pages | 成本最低，适合 MVP |
| Vercel/Netlify/Render | 体验更好，适合预览和自动部署 |
| 自建静态服务器/CDN | 适合内网或自控环境 |
3. 如何开发
建议新增 website/ 目录：
website/
docusaurus.config.ts
sidebars.ts
src/components/PageAskBox.tsx
src/components/PageQualityBadge.tsx
src/components/EditContextPanel.tsx
docs/ -> generated from ../publish
不要直接在 Docusaurus docs 目录中维护正式内容。正式内容仍以 publish/** 为准，构建时复制或映射到 Docusaurus。
4. 如何部署
构建流程：
- 从
main读取publish/**。 - 读取
state/page-manifest.json、state/publish-impact-report.json和 EditContext 数据。 - 生成 Docusaurus docs 目录、sidebar、页面 metadata 和编辑上下文。
- 执行
npm run build。 - 生成
state/site-manifest.json，记录页面 URL、sourceHash 和 renderedHash。 - 将
build/发布到静态托管。
Docusaurus 官方说明其职责是构建静态文件，产物默认在 build 目录，托管方式由使用方选择。
5. 如何配置
关键配置：
| 配置 | 说明 |
|---|---|
url | 文档站正式域名 |
baseUrl | 站点路径前缀 |
organizationName | GitHub owner |
projectName | 仓库名 |
docs.routeBasePath | 文档路由 |
editUrl | 指向 GitHub 编辑/PR 入口 |
LLM-WIKI 还需要生成：
- sidebar。
- 页面 metadata。
- EditContext。
- 问答组件配置。
- 页面反馈入口。
- PageQualityBadge 状态数据 。
6. 如何使用
| 用户 | 使用方式 |
|---|---|
| 读者 | 浏览文档、搜索、页面内提问 |
| 编辑者 | 点击编辑入口，进入 GitHub PR 流程 |
| 智能体 | 不直接操作 Docusaurus，只修改 publish/** |
| 发布系统 | 从 publish/** 构建站点 |
7. 验收标准
publish/**中已审批文档能生成站点页面。- 页面 URL 稳定。
- 页面包含来源、更新时间、质量状态。
- 页面编辑入口能携带来源、历史版本、相关 Issue 和改动意图提示。
- 页面有问答入口和反馈入口。
- 发布产物能生成
site-manifest用于漂移检测。 - 构建失败会阻止发布 PR 合并或正式发布。
8. 官方资料
- Docusaurus deployment: https://docusaurus.io/docs/deployment