AI 编程协作中的 Docusaurus 基础
本文介绍 Docusaurus 的核心工作方式，以及如何为 AI 编程协作建立可维护、可检索的文档基础。关于 Provider、插件和多智能体流程，请继续阅读账号、Provider 与插件边界和多智能体开发工作流。
Docusaurus 是什么
Docusaurus 是一个基于 React 的静态站点生成器，适合把 Markdown 或 MDX 文档、博客和 React 页面编译成可部署的网站。它在构建阶段生成预渲染 HTML，浏览器加载后再由 React 接管交互，因此文档既便于阅读，也适合静态托管和搜索引擎抓取。
它的主要能力包括：
- 文档管理：支持 Markdown/MDX、自动侧边栏、上一篇/下一篇导航、版本化文档和文档内链。
- 站点扩展：通过插件生命周期处理 docs、blog、pages 等内容，也可以加入自定义 React 组件。
- 主题与交互：classic preset 提供导航栏、页脚、代码高亮、搜索接入点和暗色模式等基础主题能力。
- 国际化：通过 locale 配置和翻译目录维护多语言站点。
- 静态部署：构建输出是静态资源，可部署到 CDN 或其他静态托管平台。
Docusaurus 适合产品文档、API 指南、团队工程知识库、教程和技术博客。它尤其适合“内容由 Git 管理、需要代码示例、希望通过评审协作”的场景；如果页面主要是复杂的后台业务系统，通常应使用更适合应用状态管理的 React 应用框架。
Docusaurus 的 SEO 基础
静态生成只是 SEO 基础，内容质量、站点配置和发布后的检查仍然需要负责。新文档应先把页面主题和搜索意图写清楚，再检查以下项目。
页面元数据
title应唯一、准确，并包含自然的核心主题。description应说明读者能获得什么，不要把关键词机械堆叠在一起。keywords只保留正文实际覆盖的主题，不能代替正文质量。- 文件路径默认形成文档 URL；只有需要稳定或更具描述性的地址时，才显式设置
slug。
页面结构
- 页面只保留一个 H1，H2/H3 层级连续。
- 开头尽早回答页面核心问题，避免只用于铺垫的空泛引言。
- 使用描述性的锚文本连接相关文档，避免孤立页面和“点击这里”。
- 内容中的事实、版本、日期和引用应可核验，不要编造数据或作者资历。
构建后检查
生产构建完成后，应检查生成 HTML 中的 title、description、canonical、Open Graph 标签和唯一 H1，并确认页面可以通过侧边栏或相关文档内链访问。站点尚未配置真实生产域名时，应把它记录为部署风险，不要在单篇文档中虚构域名。