goose 文档站开发实战：基于 Docusaurus 的构建流程、站点配置与部署全解

本篇技术文章围绕 goose 开源仓库中 documentation/README.md 所载的文档站开发工作流展开，结合 documentation/package.json 的完整脚本定义与 documentation/docusaurus.config.ts 的站点配置实现，系统讲解 goose 官网（goose-docs.ai）从本地安装、开发调试、静态构建到 GitHub Pages 部署的完整链路。读完后，你可以独立运行和维护这套基于 Docusaurus 的文档站，并理解其构建管线中自动生成的 LLM 文档地图、Markdown 导出插件等差异化设计。

一、技术栈与项目结构

goose 的文档站（即官方文档站 goose-docs.ai）基于 Docusaurus 构建。从 documentation/package.json 看，核心依赖为 @docusaurus/core、@docusaurus/preset-classic 与 @docusaurus/plugin-client-redirects（均锁定在 ^3.9.2），前端框架为 React 19，样式体系采用 Tailwind CSS 3.4 配合 PostCSS。此外还有几个与"文档可被程序消费"直接相关的依赖：

• gray-matter：解析 Markdown 文档的 YAML frontmatter，用于自动生成文档地图；
• globby：按 glob 模式批量扫描 docs/ 目录下的文档；
• js-yaml / yaml-loader：处理 YAML 配置；
• turndown：HTML 转 Markdown 的工具库。

环境要求声明在 engines 字段中："node": ">=18.0"，即 Node.js 18 及以上。

目录结构上，文档站源码集中在 documentation/ 下：

路径	职责
documentation/docs/	所有文档内容（getting-started、guides、mcp、tutorials 等）
documentation/blog/	博客文章，按日期目录组织
documentation/src/	主题、组件、自定义页面（如 extensions、recipes、deeplink-generator）
documentation/scripts/	构建辅助脚本（文档地图生成、ACP 文档生成、静态服务等）
documentation/plugins/	自定义 Docusaurus 插件（Tailwind、Markdown 导出、Webpack 补丁）
documentation/static/	静态资源（logo、llms.txt、servers.json 等）

文档站有一套严格的品牌书写规范：documentation/AGENTS.md 要求所有文档与博客内容中产品名一律使用小写的 "goose"，该规范覆盖 docs/、blog/、README 以及所有含用户可见文本的配置文件。

二、安装与本地开发

所有命令均在 documentation/ 目录下执行（见 documentation/README.md）。

1. 安装依赖

$ npm i

2. 启动本地开发服务器

$ npm run start

start 脚本在 documentation/package.json 中定义为 docusaurus start。它启动本地开发服务器并自动打开浏览器窗口，大多数改动可以热更新即时生效，无需重启服务器。

package.json 中还定义了一组完整的 Docusaurus 辅助脚本，覆盖日常开发全流程：

"scripts": {
  "docusaurus": "docusaurus",
  "start": "docusaurus start",
  "build": "node scripts/generate-docs-map.js && docusaurus build",
  "swizzle": "docusaurus swizzle",
  "deploy": "docusaurus deploy",
  "clear": "docusaurus clear",
  "serve": "docusaurus serve",
  "write-translations": "docusaurus write-translations",
  "write-heading-ids": "docusaurus write-heading-ids",
  "test": "node --test scripts/*.test.js",
  "typecheck": "tsc",
  "serve-static": "node scripts/serve-static.js"
}

各脚本的用途：

• build：生产构建，注意它比标准 docusaurus build 多了一步前置生成（下文详述）；
• swizzle：将 Docusaurus 主题组件复制到本地以便自定义；
• clear：清理构建缓存；
• serve：本地预览 build 产物；
• write-translations / write-heading-ids：i18n 与标题锚点维护工具；
• test：使用 Node 内置测试运行器执行 scripts/ 下的 *.test.js 单测；
• typecheck：运行 tsc 做 TypeScript 类型检查（对应 documentation/tsconfig.json）；
• serve-static：本地静态文件服务器（下文详述）。

三、构建管线：不只是 docusaurus build

这是 goose 文档站相对标准 Docusaurus 项目最显著的差异点。npm run build 实际执行：

$ npm run build
# 等价于：
# node scripts/generate-docs-map.js && docusaurus build

1. 前置步骤：自动生成 LLM 文档地图

documentation/scripts/generate-docs-map.js 会在构建前扫描 docs/ 目录并生成 static/goose-docs-map.md。其工作逻辑（从源码实现看）：

1. 按两个分区扫描文档：getting-started/*.{md,mdx} 归入 "Getting Started"，guides/**/*.{md,mdx} 归入 "Guides"；
2. 用 gray-matter 解析每篇文档的 frontmatter，标题优先取 frontmatter.title，缺失时回退到正文第一个 H1（getTitle 函数）；
3. 提取 H2–H6 级标题，按层级缩进渲染为嵌套列表（getHeadings 函数，缩进规则为每深一级加两个空格）；
4. 输出文件头部标注 "Auto-generated" 及生成日期，尾部附上完整文档站地址。

标题提取与层级嵌套的行为由 documentation/scripts/generate-docs-map.test.js 中的单测明确验证：frontmatter 标题优先于 H1、无标题返回 null、H2–H6 生成嵌套 bullet 等。该脚本同时以 CommonJS 模块形式导出 getTitle 与 getHeadings 供测试引用。

生成的 goose-docs-map.md 会随 static/ 目录一并进入构建产物，成为一份机器可读的文档总索引——配合 documentation/static/llms.txt 与 documentation/docusaurus.config.ts 中注入的 <link rel="alternate" type="text/plain" href="/llms.txt"> headTag（见配置第 53–63 行的 headTags），文档站显式面向 LLM / Agent 消费方提供了结构化入口。

2. Markdown 导出插件：HTML 与 .md 同源发布

构建还挂载了自定义插件 documentation/plugins/markdown-export.cjs，在 documentation/docusaurus.config.ts 中以 enabled: true 启用。该插件在 postBuild 阶段：

1. 用 globby 扫描 docs/ 下全部 *.md / *.mdx 文件；
2. 对每份文件剥离 YAML frontmatter（正则 ^---\s*\n[\s\S]*?\n---\s*\n）与 MDX 的 import 语句；
3. 将清理后的纯 Markdown 写至构建产物 build/docs/ 下，.mdx 统一改名为 .md。

这意味着生产站点上的每个文档页都存在一份同路径的 .md 纯文本版本（例如 /docs/quickstart.md），Agent 与 LLM 可以直接抓取原始 Markdown 而不必解析 HTML。

3. 构建产物

构建完成后，静态内容输出到 documentation/build/ 目录，可交由任意静态托管服务。本地可用 npm run serve 预览，或使用 npm run serve-static。

documentation/scripts/serve-static.js 是一个基于 serve-static 的极简静态服务器（默认端口 3001，可用 PORT 环境变量覆盖），与 docusaurus serve 的区别在于它不做路由逻辑、按原路径返回文件，并会为 .md 文件设置 Content-Type: text/plain; charset=utf-8。脚本启动时会打印两个用于验证 Markdown 导出效果的示例地址：

http://localhost:3001/docs/quickstart.md
http://localhost:3001/docs/getting-started/installation.md

这正好与 markdown-export 插件的输出路径对应，构成"构建后验证导出可用性"的配套手段。

四、部署到 GitHub Pages

部署流程在 documentation/README.md 中给出两种方式。

使用 SSH 认证：

$ USE_SSH=true npm run deploy

不使用 SSH（以 HTTPS 推送，需指定 GitHub 用户名）：

$ GIT_USER=<Your GitHub username> npm run deploy

deploy 脚本即 docusaurus deploy，其本质是先构建、再将产物推送到 gh-pages 分支，适合以 GitHub Pages 作为托管的场景。

部署相关的关键配置

部署行为由 documentation/docusaurus.config.ts 中的以下字段共同决定：

url: "https://goose-docs.ai/",
baseUrl: process.env.TARGET_PATH || "/",

organizationName: "aaif-goose", // Usually your GitHub org/user name.
projectName: "goose",          // Usually your repo name.

• url 声明生产环境站点地址，用于生成绝对链接与 RSS 等元数据；
• baseUrl 默认 /，但支持 TARGET_PATH 环境变量覆写——这正是 Docusaurus 官方推荐的 GitHub Pages 子路径部署手段：当站点部署在 https://<org>.github.io/<project>/ 时，通过 TARGET_PATH=/goose/ npm run build 即可让所有资源路径带上前缀，避免静态资源 404；
• organizationName: "aaif-goose" 与 projectName: "goose" 共同定位部署目标仓库（aaif-goose/goose），docusaurus deploy 依据这两个字段确定推送地址；
• 结合 USE_SSH=true / GIT_USER 两个环境变量，可分别切换为 SSH 或 HTTPS 推送认证方式。

构建期的链接质量门禁

配置中还有两条对文档站内容质量有实质影响的约束：

onBrokenLinks: "throw",
markdown: {
  hooks: { onBrokenMarkdownLinks: "warn" },
},

onBrokenLinks: "throw" 表示生产构建时任何指向不存在路由的链接都会直接让构建失败——这是保障文档站链接有效性的硬性门禁；Markdown 内部的坏链则降级为警告。此外，站点通过 @docusaurus/plugin-client-redirects 插件维护了一张大规模的旧路径重定向表（见 documentation/docusaurus.config.ts 中的 redirects 数组，涵盖从 /v1/... 旧版路径、旧 tutorials 目录到 /docs/mcp/... 新目录结构等数十条规则），确保文档重组后历史 URL 仍可访问。

五、站点配置深度解析

documentation/docusaurus.config.ts 完整定义了站点行为，几个值得关注的部分：

1. 侧边栏：文件系统自动生成 + 程序化注入

documentation/sidebars.ts 使用 Docusaurus 默认的自动侧边栏（{type: 'autogenerated', dirName: '.'}），即按 docs/ 目录结构生成。在此之上，documentation/docusaurus.config.ts 通过 sidebarItemsGenerator 钩子对默认结果做了程序化增补：它将 mcp/memory-mcp（重命名为 "Memory Extension"）和 tutorials/rpi（重命名为 "Research → Plan → Implement"）两个条目，通过递归查找 Context Engineering 分类并 push 的方式插入侧边栏——这是一种不修改 sidebars.ts 即可动态编排导航的做法。

2. 博客配置

博客启用了 RSS 与 Atom 双格式 feed（feedOptions: { type: ["rss", "atom"], xslt: true }），显示阅读时间（并支持 frontmatter 中的 reading_time 覆写默认计算），每页展示 22 篇文章（postsPerPage: 22），并对行内标签、行内作者、未截断长文三种情况给出 warn 级校验，用于维持博客最佳实践。

3. 搜索与主题

• 搜索使用 Inkeep 提供的 Docusaurus 主题（themes: ["@inkeep/docusaurus/searchBar"]），API 密钥等三个凭据通过 dotenv 从环境变量 INKEEP_API_KEY、INKEEP_INTEGRATION_ID、INKEEP_ORG_ID 注入；
• 代码高亮使用 prism-react-renderer，浅色主题 github、深色主题 nightOwl；
• 自定义 CSS 为三份：custom.css、extensions.css、tailwind.css（分别对应全站样式、扩展页样式与 Tailwind 入口）；
• Tailwind 的接入不是通过 Docusaurus 官方 Tailwind 支持，而是自定义插件 documentation/plugins/tailwind-config.cjs 注入的 configurePostCss 钩子，将 postcss-import、tailwindcss、autoprefixer 依次挂载进 PostCSS 管线；
• 公告栏当前提示 goose 已迁移至 Agentic AI Foundation（AAIF），页脚版权信息同样指向 AAIF。

4. 导航与导航栏

导航栏包含 Quickstart、Docs（指向 /docs/category/guides）、Tutorials、Blog 四个主入口，以及 "Resources" 下拉菜单（Extensions 扩展库、Recipe Cookbook、Deeplink Generator）——这些下拉项对应 src/pages/ 下的自定义页面，说明文档站不仅是文档，还承载了扩展目录与配方食谱等交互式功能页。

六、其他构建辅助脚本

除了文档地图与 Markdown 导出，scripts/ 目录还包含 documentation/scripts/generate-acp-docs.js：它读取 Rust 侧的 crates/goose/acp-schema.json 与 crates/goose/acp-meta.json，将 goose 扩展的 ACP（Agent Client Protocol）方法、请求/响应/通知类型渲染为文档页 docs/gdk/acp/reference.md，并明确标注"本文件由 schema 生成，请勿手动编辑"。该脚本的确定性渲染与非法 schema 关键字拒绝逻辑由 documentation/scripts/generate-acp-docs.test.js 单测覆盖（例如 not 等不支持的 JSON Schema 关键字会抛出 Unsupported schema keyword 错误）。配合 generate-docs-map.test.js，npm run test（node --test scripts/*.test.js）即为这套生成管线提供了可重复的回归验证。

七、完整工作流小结

综合 documentation/README.md 的原始说明与仓库实现，goose 文档站的完整生命周期为：

1. 安装：在 documentation/ 下执行 npm i（需 Node.js >= 18）；
2. 开发：npm run start 启动热更新开发服务器；npm run typecheck 与 npm run test 保障类型与脚本单测通过；
3. 构建：npm run build 先执行 generate-docs-map.js 生成 LLM 文档地图，再由 docusaurus build 产出静态站点，markdown-export 插件在构建后同步导出全部文档的纯 Markdown 版本；
4. 本地验证：npm run serve 或 npm run serve-static（验证 .md 导出可直接访问）；
5. 部署：USE_SSH=true npm run deploy（SSH）或 GIT_USER=<username> npm run deploy（HTTPS），构建产物推送至 gh-pages 分支，由 GitHub Pages 托管；子路径部署时通过 TARGET_PATH 环境变量调整 baseUrl。

这套工作流的核心价值在于：在标准 Docusaurus 站点之上，通过构建管线注入了 LLM 文档地图（goose-docs-map.md）、llms.txt 入口与同源 Markdown 导出，使文档站同时服务人类读者与 AI Agent 两类消费方——这与 goose 项目本身作为 AI Agent 的定位一脉相承。