configure-site

配置 GitBook 站点

用于创建和维护完整 GitBook 文档站点的技能。write-docs 涵盖单个页面的内容，而此技能涵盖页面周边的一切：结构设计、仓库脚手架、GitBook API 和品牌塑造。请结合使用这两项技能——每当需要生成或编辑页面内容时，此技能都会调用 write-docs。

如何与 GitBook 交互

驱动 GitBook 的方式不止一种——GitBook 的 MCP 服务和 REST API。请检查当前会话中实际可用的方式，并优先使用 MCP：如果已连接 GitBook MCP 工具，就用它们处理其支持的任何操作（创建／配置站点、打开变更请求、起草和编辑内容、重组文档），而不是直接调用 API。不要为此运行检测脚本——你已经知道自己有哪些可用工具／MCP 连接；只需利用这些信息即可。

“MCP 优先”指的是传输方式，而不是绕过 Git Sync 来处理内容。 MCP 提供了一个变更请求内容推送工具（updateChangeRequestContent），只要它已连接，就很容易让人想在任何时候都使用它——但对于已配置 Git Sync 的空间，通过编辑本地仓库中的文件并让 Git Sync 将其同步到 GitBook，仍然是处理小规模、有针对性编辑之外的所有内容的首选方式。如果空间未与 Git 同步、环境中没有可用的本地检出，或编辑规模小到足以采用创建 CR 的方式，请改用变更请求推送（MCP 或 REST）。完整规则请参阅 write-docs 中的“选择 Git Sync 还是变更请求内容推送”；此处同样适用。

此技能中的步骤以目标结果描述（“列出组织”“创建站点”“添加章节”），而非绑定到某种传输方式，因此无论使用哪种方式都适用。如果已连接 GitBook MCP 工具，请直接调用——它们各自的架构会说明参数。如果使用 REST API，则每个步骤对应的确切端点、请求正文和预期响应都列在 references/api-cheatsheet.md 中。

• GitBook MCP — 提供对下文所述相同功能的完整读写能力，而非受限视图。如果尚未连接，且任务规模足以从中受益（例如构建完整站点、持续重组，而非一次性小调整），请提出为其配置连接：claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp（然后运行 /mcp 完成 OAuth 登录，或追加 --header "Authorization: Bearer $GITBOOK_TOKEN" 以跳过浏览器流程）。Codex 对应命令：codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp。注意：这与 GitBook 单独提供的只读“已发布文档”MCP 服务不同；后者只开放已发布的内容。
• REST API（https://api.gitbook.com/v1）——当 MCP 未连接，或遇到 MCP 不支持的操作时使用的备用方式。每个请求都需要在 bearer 标头中提供 GITBOOK_TOKEN。

同一个个人访问令牌（可从 https://app.gitbook.com/account/developer 获取）可同时用作 bearer 令牌。MCP 还支持 OAuth，作为比粘贴令牌更方便的替代方式。

如果最终需要令牌（使用 REST API，或不通过 OAuth 使用 MCP），请在会话开始时检查令牌是否存在：

[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"

如果未设置 GITBOOK_TOKEN，请直接询问用户：

1. 告诉他们需要 GitBook 个人访问令牌，并引导他们前往 https://app.gitbook.com/account/developer 创建令牌。
2. 请他们将令牌粘贴到对话中。立即将其导出为环境变量（export GITBOOK_TOKEN=<pasted value>），并且不要在回复中重复令牌。
3. 在确认环境中已存在令牌之前，不要进行任何 API 调用。

绝不要将令牌写入文件、在回复中复述令牌，或提交令牌。

核心限制

在开始任何操作之前，最重要的是要牢记：GitBook 几乎什么都能做，唯独无法设置 Git Sync，无论使用哪种传输方式。授权 GitHub/GitLab、选择存储库、选择分支以及选择初始同步方向，都只能通过 UI 操作——REST API 和 MCP（对 REST API 的封装）都只能让你 读取 最终的 Git Sync 状态，而不能设置 Git Sync。有一个名为 installGitSyncProviderOnTarget 的 API 操作，可针对站点或空间，但账户连接（OAuth）步骤仍必须在应用中完成，而且目前尚未通过 GitBook 的 MCP 服务公开；请将其视为暂不可用，不要围绕它构建工作流。

Git Sync 现在在站点级别配置，这也是默认应采用的方式。 一个连接（一个仓库、一个分支）即可覆盖整个站点；gitbook-docs.yaml 会将每个空间映射到各自的目录，这与此技能已经搭建的单体仓库结构一致。按空间配置 Git Sync 仍然可行，但现在属于例外情况——只有在某个特定空间需要独立的仓库或分支时才使用（例如，无法放在公开文档仓库中的私有空间）。

这意味着，最简洁的端到端流程始终是：

1. Claude 在本地将 Git 仓库搭建为单体仓库（每个空间对应一个目录），最好预先编写 gitbook-docs.yaml，将每个空间映射到其目录，并在工具允许时推送到远程仓库
2. Claude 创建站点、分区以及能够创建的任何空空间
3. 用户在 GitBook 中完成一个简短且有清晰指引的 UI 操作步骤：将站点连接到仓库/分支，并确认空间与目录的映射关系——无需针对每个空间分别操作
4. Claude 应用品牌设置/自定义项

步骤 3 中用户必须参与，但这绝不应让用户感到意外——请生成清晰、可直接复制粘贴的说明。参考：references/git-sync-handoff.md。

如果用户明确不想使用 Git Sync，则改用内容导入路径（内容导入和模板应用）——下文以及 references/api-cheatsheet.md 中有简要介绍。

应提前收集的信息

在确认以下信息之前，不要开始搭建。如果有信息缺失，应集中提问一次，而不是自行猜测。（身份验证另行处理——请参阅上文“如何与 GitBook 通信”。）

• 组织 — 列出用户的组织，向用户展示列表，然后请他们按名称确认目标组织。即使用户只有一个组织，也要先确认一次，以免在错误的位置创建站点。将选定的 organizationId 保存下来，供本次会话后续使用；描述后续步骤时，用组织的标题（而不是 UUID）称呼该组织。
• 站点计划和可见性 — 除非用户明确另有要求，默认使用 type: "ultimate"（Ultimate 计划）和公开可见性。大多数真实客户需要 Ultimate 的功能集（自定义域名、AI Assistant、高级自定义、隐藏 GitBook 商标、自定义字体、自定义徽标）。免费层级（type: basic）仅适用于明显低风险的场景，例如个人开源副项目。如果不确定，请询问：“我会使用 Ultimate 计划为你设置，除非你更希望使用免费层级——要改成免费层级吗？” — basic 中不会显示且用户不易察觉的 Ultimate 功能（没有 AI 助手、没有自定义字体、没有自定义域名），比简短确认计划更容易让用户感到意外。
• 内容来源 — 这个站点将基于什么内容构建？常见形式：
  • 包含现有 Markdown 文件的文件夹 — 最简洁的起点
  • 一些笔记，加上一个竞争对手的站点作为参考
  • 只有对想要记录的内容的描述
  • 需要重新整理的现有站点（这种情况下，先获取该站点的当前结构）
  • 从其他文档平台迁移（Mintlify、Docusaurus、ReadTheDocs、GitBook v1）— 工作流请参阅 references/migration-from-other-platforms.md。迁移本身是一门专业工作；不要把它当成简单的文件复制。
• API 参考的 OpenAPI 规范 — 如果站点包含任何 API 参考内容，请一开始就询问他们是否有 OpenAPI 规范（或者能否从其代码库生成）。如果有，API 参考空间只需一个 builtin:openapi SUMMARY 条目，以及每个资源各一段概述 README — 工作量远小于手动编写端点页面，而且内容永远不会过时。工作流请参阅 references/block-ecosystem.md 和 references/api-cheatsheet.md。不要默认手动编写端点页面 — 这几乎总是错误的选择。
• 品牌设计 — 至少需要主色（十六进制）。可选项：徽标 URL（浅色 + 深色）、网站图标、字体选择（或 GitBook 的默认字体之一）、页眉链接、页脚文本/链接、主题预设（clean、muted、bold、gradient）。对于 Ultimate 站点，也可以考虑 AI 助手的入门提示词（3-5 个访客可能会问的简短问题）。
• 站点结构 — 使用分区，而不是站点空间。如果站点有多个空间，请与用户明确规划分区列表：每个分区都包含标题、Font Awesome 图标名称和描述。分区图标和描述是导航的重要组成部分 — 访客能看到它们 — 提前收集可省去之后为每个分区逐一更新的步骤。例如：[{title: "Guides", icon: "book-open", description: "Concepts and tutorials"}, {title: "API Reference", icon: "code", description: "REST API and SDKs"}, {title: "Changelog", icon: "clock-rotate-left", description: "Updates and release notes"}]。
• Git 远程仓库偏好 — GitHub、GitLab 或仅限本地。在询问之前，先检查是否已安装 gh 或 glab。如果这两个工具都不可用，请明确说明，并提供两种方案：(1) 在本地提交，并将“创建远程仓库并推送”步骤放在交接事项的首位；或 (2) 请用户安装该工具。不要不告知用户就默认仅限本地 — 否则他们会得到一个没有远程仓库、也没有相关说明的代码库。
• 站点形式 — 单空间或多空间。多空间站点使用分区将空间归类到导航中；当内容面向明显不同的受众时（例如用户文档 + API 参考 + 更新日志），应选择此方案。只有翻译版本才直接使用站点空间 — 请参阅 references/api-cheatsheet.md。

构建前验证内容来源

用户指定内容种子（仓库、文件夹或文档网站 URL）后，在设计结构或搭建任何内容之前，先验证你是否确实能够读取该来源：

1. 解析并回显来源。 明确说明你即将读取的内容（仓库 URL 和分支、文件夹路径或网站 URL），并向用户展示其顶层内容——简短的文件或页面列表——以便他们确认来源是否正确。
2. 如果无法访问，就停止并说明情况。 Git 托管平台会对私有仓库返回 404，这与“仓库不存在”无法区分。用户指定的仓库若出现任何 404 或克隆失败，都应视为可能是私有仓库：告知用户失败原因，并请他们通过本地克隆、归档文件、经过身份验证的 gh/glab、公开镜像等方式使内容可访问，或修正 URL。在宣布仓库无法访问之前，先检查是否有经过身份验证的 gh/glab CLI 可用。
3. 绝不替换来源。 不要搜索、猜测或改用名称相似的仓库或网站，即使看起来完全相同也不行。基于错误来源构建文档网站，远比暂停并询问用户糟糕。任何来源变更都必须获得用户明确同意。

需要确认的状态变更操作

创建网站、创建空间、添加分区、关联网站与空间以及自定义设置变更，都会创建或修改对象，并立即对组织中的所有人可见，而且清理这些对象需要付出实际成本。请将其视为重大操作。

规则：未经事先展示一屏预览并获得用户明确的“是”，绝不执行状态变更。

好的预览应简短具体：

即将在组织 Acme Inc（org_abc123）中执行：

• 创建网站 “Acme Platform Docs”（类型：ultimate，可见性：公开）
• 创建 3 个空空间：指南、API 参考、更新日志
• 将指南设为默认分区；为 API 参考和更新日志创建分区

继续吗？（是/否）

不好的预览要么含糊不清（“我现在要创建网站”），要么埋在大段说明中。保持内容一目了然。

同一规则也适用于破坏性操作——删除网站、空间、分区或自定义覆盖项——但表述必须更加明确（“这将删除网站 Acme Platform Docs 及其 3 个空间。空间和网站可在 7 天内恢复，之后将永久删除。确认吗？”）。

如果用户已在结构设计步骤中确认了多步计划，就不必针对计划中的每项操作再次询问；但如果计划有任何变更（例如增加空间或更改可见性），则必须重新确认。

对于只读操作（获取或列出内容），无需确认。

提交变更请求后：必须提供两个链接

每当此技能（或委托 write-docs 负责页面编写）通过变更请求推送内容时——无论是通过 MCP 的 updateChangeRequestContent/create_change_request/submit_or_merge_change_request 精选工具、invoke_operation，还是 REST 等效接口——在向用户报告以下两项之前，编辑都不算完成，而且每次都必须提供：

1. 变更请求的差异/编辑器链接（urls.app）——在 GitBook 应用中查看变更的链接。
2. 站点预览链接——应用变更后渲染出的文档。此链接需要单独查询：站点 URL 位于 Site 对象上（站点公开时为 urls.published，否则为 urls.preview），不在变更请求对象上，并且必须在其后追加 /~/changes/<number>/，同时去掉 API 返回值末尾的斜杠。缺少此路径段时，链接渲染的是站点的当前内容，而不是此变更请求的内容——链接可以正常打开，但显示的是错误内容。

这是硬性规定，与上述确认关卡同等重要，并非有空时才添加的贴心做法。有关精确的解析步骤，请参阅 write-docs 中的“两条链接在涉及变更请求时始终必不可少”以及 cr-create 技能中的“提供预览链接”（MCP：getSpaceById → 通过 list_sites/get_site_structure 或各站点的 site-spaces 查找站点 → getSiteById 获取 .urls.preview；REST：调用相应的链式 GET 请求）。如果该空间未关联到已发布的站点，请明确说明，而不是只提供差异链接却不作解释。

设计站点结构

在 GitBook 中编写任何文件或创建任何内容之前，先确定结构并交由用户审核。结构薄弱是文档站点无法成功上线的首要原因。

此步骤的输出是一份简短计划，最好包含以下三项：

1. 空间列表 — 每个连贯的内容主体对应一个空间。尽量保持精简（通常为 1–4 个空间）。空间是导航和 Git Sync 的单位，因此不要把同一受众的内容拆分到多个空间。
2. 分区分组（多空间时）— 分区是站点导航中的顶层划分，例如“产品”/“开发者”/“资源”。一个分区可以包含一个或多个空间。
3. 每个空间的页面树 — 列出文件夹和页面，并用一两句话概述每个页面。树的深度应与内容相匹配；通常以较浅的树（1–2 层）为佳。

从原始输入制定结构计划的完整启发式方法见 references/site-structure-design.md — 首次为非简单站点执行此操作时，请阅读该文件。始终向用户展示计划，并在搭建文件之前取得明确同意。 在 Git 中，之后重组成本很低；但站点一旦发布并被索引，重组成本就很高。

关于用户将多个指令合并为一条时的确认说明：像 “规划结构，然后搭建文件” 这样的提示容易让你跳过确认关卡。不要这样做。将计划整理成清晰、易于浏览的区块后呈现，然后等待用户回复“是”；或者，如果提示明确到你已开始搭建，则在计划中说明你的决定，并提供一个简单的调整机会（“如果有任何不合适的地方，请告诉我，我会在继续之前重新处理”）。关键是让用户在看到二十个生成的文件之前先看到计划，此时修改仍然很容易。

搭建仓库骨架

确定结构后，将仓库布局为单仓库（monorepo）——即使是只有一个空间的网站，这种布局也一致且面向未来。每个空间都是一个目录，其中包含自己的 README.md（主页）和 SUMMARY.md（目录）。还可以选择添加 .gitbook/ 文件夹，用于存放空间级变量和可复用内容块；也可以选择添加 .gitbook.yaml，用于高级同步配置。

包含三个空间的网站布局示例：

my-docs/
├── .gitignore
├── README.md                    # repo-level readme (not a space homepage)
├── guides/                      # space 1
│   ├── README.md                # space homepage
│   ├── SUMMARY.md
│   ├── .gitbook/
│   │   └── vars.yaml            # optional: space-level variables
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quickstart.md
│   └── concepts/
│       └── ...
├── api-reference/               # space 2
│   ├── README.md
│   ├── SUMMARY.md
│   └── endpoints/
│       └── ...
└── changelog/                   # space 3
    ├── README.md
    └── SUMMARY.md

这种布局有几点常见问题需要注意：

• .gitbook.yaml 是可选的。 GitBook 使用每个空间默认的 README.md + SUMMARY.md 约定即可正常工作。只有在需要覆盖根目录、定义重定向或执行其他非默认操作时，才添加 .gitbook.yaml。附带的示例站点（references/example-site/）没有任何 .gitbook.yaml 文件，也能正常运行。
• .gitbook/vars.yaml 用于存放空间级变量，页面可以通过表达式语法引用这些变量（例如，定义 support_email: [email protected]，并以 <code class="expression">space.vars.support_email</code> 的形式引用）。任何会在多个页面中出现的值都适合放在这里。请参阅 write-docs / references/frontmatter.md——不要使用 {% vars.… %}。
• .gitbook/includes/<name>.md 用于存放可复用内容块——通过 {% include "...persona-switcher" %} 嵌入多个页面的内容片段。请用这些内容块代替重复粘贴的固定内容。
• 空间目录名称（例如 guides/）是用户在设置全站 Git Sync 时，通过 Content mapping 将空间映射到的目录——而不是站点的“Project directory”字段。该字段仅指向 gitbook-docs.yaml 所在的位置（在此布局中为仓库根目录）。不要混淆两者；请参阅 references/git-sync-handoff.md。
• 考虑在仓库根目录预先编写一个 gitbook-docs.yaml，将每个空间映射到其目录（格式请参阅 references/git-sync-handoff.md）。GitBook 会在首次同步时读取它，因此用户在设置过程中需要手动填写的内容会更少。

确实需要 .gitbook.yaml 时，最简配置如下：

root: ./
structure:
  readme: README.md
  summary: SUMMARY.md

仓库级 README 和 .gitignore

仓库级 README.md（位于仓库顶层，而非某个空间内）应说明这个文件夹的用途，以及它与已发布站点的关系——不要重复文档本身的内容。简短的一段说明即可：

# my-docs

Source for the [My Product docs site](https://docs.example.com). Each top-level folder
is a separate GitBook space; edits flow in both directions via Git Sync once configured.

.gitignore 应将操作系统生成的杂项文件和编辑器设置排除在仓库之外。以下是合理的默认配置：

.DS_Store
Thumbs.db
*.swp
*.swo
.idea/
.vscode/

如果团队还有其他生成的产物（例如从其他位置的源文件构建的 OpenAPI 规范），请将它们添加进去。

生成 SUMMARY.md — 收集导航结构，不要从文件夹推断

最常见的脚手架搭建错误，就是遍历文件树并据此生成 SUMMARY.md：把 README 放在顶部，再将其他每个文件缩进为 README 的子项。这样生成的导航令人沮丧——每个页面都是“首页的子页面”，文件夹名称无论对读者是否有意义，都会变成分组标题，而且信息架构反映的是文件系统，而不是用户的思维模型。

正确的做法，按顺序如下：

1. 在设计结构时，向用户收集所需的导航结构。 明确询问用户，列出顶层页面，以及每个空间中命名的分组。此时，你可以让文件夹名称与实际导航保持一致；用户也可以告诉你“我想把 Authentication 设为顶层页面，而不是放在 Concepts 下”。

2. 按照商定的导航结构安排文件夹，而不是反过来。 如果用户希望一个空间分为三个组——“入门”“概念”“教程”——那么空间目录就应有三个以这些名称命名（转换为 slug）的子文件夹，每个文件夹中包含各自的页面。不要从某个无关子文件夹中自动提取出第四个分组。

3. 按照用户明确同意的结构编写 SUMMARY.md。 GitBook 支持的语法：

   # Table of contents
   
   * [Space homepage](README.md)
   * [Top-level page A](top-level-a.md)
   * [Top-level page B](top-level-b.md)
   
   ## First group
   
   * [Page in group](first-group/page.md)
   * [Another page](first-group/another.md)
   
   ## Second group
   
   * [Page](second-group/page.md)
   

   关键结构规则：

   • README.md 单独占据最顶部的一行，与其他页面同级，而不是父级。其他顶层页面也作为同级项列在后面。
   • ## Group name 标题用于引入分组。 分组中的页面直接以平级项目符号列在标题下，不要缩进到 README 下。
   • 避免机械地采用“ README.md”并将所有内容都嵌套在其下的做法。* 这会把整个导航折叠到首页下的一棵树中，并让侧边栏中的每个页面看起来都像是首页的子页面。
   • 分组名称由用户指定，而不是取自文件夹名称。 文件夹 slug 可以是“concepts/”，但如果“工作原理”更清晰，分组标题就可以用它。
   • 每个页面使用一个项目符号，不添加额外格式。 SUMMARY 中不要加粗，也不要添加描述——这些内容应放在页面的 frontmatter 中。

4. 以下特殊情况不使用普通项目符号：

   • OpenAPI 自动生成的端点页面使用围栏 YAML 代码块作为项目符号内容（type: builtin:openapi — 参见 references/api-cheatsheet.md）。
   • 外部链接使用 * [Title](https://...)，并在导航中显示为外部链接。
   • 跨空间链接在 SUMMARY.md 中使用与正文相同的 https://app.gitbook.com/s/<spaceId>/<path> 格式。路径不带 .md 后缀。搭建脚手架时先写入占位形式（XSPACE_<KEY>）；空间创建后再替换。参见 references/cross-space-links.md。

如果你的脚手架辅助工具会通过遍历文件夹自动生成 SUMMARY.md，请确保其操作具有幂等性，并跳过已存在的文件。绝不能悄悄覆盖用户编辑过的 SUMMARY.md——否则用户精心调整的导航结构就会丢失。

单页 Markdown——以 write-docs 为准，但优先使用丰富区块

适用于所有 Markdown 文件——README.md、SUMMARY.md 和每个页面——请遵循 write-docs 技能。它是以下内容的权威参考：

• Frontmatter，包括 icon: 字段。图标使用不带 fa- 前缀的 Font Awesome 名称（例如 book-open、bolt、house、code、puzzle-piece、id-card、circle-dollar-to-slot）。不要自行编造名称——请从 Font Awesome 图标目录中选择。示例站点几乎每个页面的 frontmatter 都使用了这些图标。
• 布局标记，包括 layout: width: wide（谨慎使用——适用于营销风格的落地页、带有 Updates 时间线的更新日志页面、包含多列区块或确实较宽的表格的页面。不要默认所有空间首页都使用 wide——GitBook 的默认宽度适合文档，包括带卡片表格的文档落地页。Wide 适用于主视觉营销布局，而非普通文档。）、cover: 图片，以及每页的可见性标记（title.visible、tableOfContents.visible 等）。
• SUMMARY.md 语法。 格式严格——每页一个项目符号，可选 ## 分组名称 标题，不添加其他格式。此外，还包括用于从规范自动生成端点页面的特殊 type: builtin:openapi 语法。
• 丰富区块——标签页、提示框、步骤条、分栏、卡片表格、可展开内容、嵌入内容、使用 {% if visitor.claims... %} 的条件内容、OpenAPI 区块、Updates 区块（更新日志）、可复用内容引入。
• GitBook 风格的 Markdown 与 CommonMark 的差异。

这里不要另创一套规则。随附的 references/example-site/ 是了解地道内容写法的最佳实践参考。

主动选择合适的区块，而非默认使用纯文本

一种常见的失败模式：Claude 生成的文档能够正常使用，但所有内容都采用纯 Markdown，错过了让 GitBook 网站更具产品感的丰富区块。技能应主动选用专用区块，而不是退回到单纯的段落和项目符号。需要熟练掌握以下具体模式：

• 更新日志 → 使用 {% updates %} 区块，并通过 {% update date="..." tags="..." %} 添加条目。该区块会自动生成 RSS，并支持标签（在 .gitbook/tags.yaml 中定义）。不要编写 ## YYYY-MM-DD 标题——这不是正确的格式。
• API 端点参考 → 上传一次 OpenAPI 规范，再通过 SUMMARY.md 中的 type: builtin:openapi 自动生成页面。不要手动编写端点页面——它们会逐渐偏离规范，而且规范本身才是权威来源。如果用户没有规范，可以先提出起草一份精简规范，而不是改用大段文字。
• 状态机、流程、时序、简单架构 → 使用 ```mermaid 围栏代码块。不要用 ASCII 绘制方框和箭头；Mermaid 受支持、渲染清晰，并且方便屏幕阅读器读取。
• 空间主页 → 普通文档首页使用 GitBook 默认布局（显示目录，采用默认宽度）。只有当页面确实属于营销风格时，才使用 layout: width: wide——例如包含主视觉图片、卡片网格异常庞大或采用多列仪表板布局。文档通常应使用默认布局。
• “选择你的路径”内容 → 使用卡片表格（<table data-view="cards">）。HTML 虽然冗长，但视觉效果胜过任何 Markdown 替代方案。
• 并排简介模式 → 使用 {% columns %} 区块。标准布局是两列各占 50%。
• 重复的样板内容（3 处及以上） → 使用 .gitbook/includes/<name>.md + {% include "..." %}。
• 重复的字面值（环境 URL、支持邮箱、版本固定值） → 使用 .gitbook/vars.yaml + <code class="expression">space.vars.<name></code>。
• 多语言代码示例 → 使用 {% tabs %} 区块。
• 包含 3 个及以上有序步骤的操作指南 → 使用 {% stepper %} 区块。

完整的区块指南包含各区块的示例用法，以及一张“异味与修复”决策表，详见 references/block-ecosystem.md。生成任何非简单页面之前，请先阅读该指南，并针对正在搭建的每个内容区域逐项对照决策表——在默认使用纯 Markdown 之前，先问一句：“这里是否有专用区块？”

跨空间链接

多空间站点需要跨空间链接——它们能让站点感觉像一个互联的整体产品，而不是一堆彼此独立的手册。**不要为了避免跨空间链接而重复内容，也不要删掉它们。**这是 GitBook 的一项一等功能；唯一需要注意的是，必须使用真实的空间 ID 才能正确渲染，而 ID 只有在站点创建后才会生成。

Markdown 中的写法只是一个指向目标空间 GitBook URL 的普通链接：

For the conceptual side, see the [Authentication concept page](https://app.gitbook.com/s/<spaceId>/concepts/authentication).

GitBook 会在渲染时解析 https://app.gitbook.com/s/<spaceId>/<path>，无论你是否使用自定义域名。在内部，这些链接是设置了空间 ID 的 ContentRefPage 或 ContentRefSpace 内容引用；在 Markdown 中，它们只显示为 URL。

脚手架搭建流程：

1. 在搭建脚手架期间，使用以 XSPACE_ 为前缀的哨兵空间 ID 编写跨空间链接，每个计划中的空间使用一个。将结构计划中的空间 slug 用作后缀：

   See the [Authentication concept page](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication).
   For the full reference, see the [API Reference](https://app.gitbook.com/s/XSPACE_API/).
   

   这些是指向不存在的 GitBook 空间的有效 Markdown 链接——不会导致解析器出错、便于通过 grep 搜索，而且能通过 Git 完整往返。

2. 空间创建后，拿到每个新空间的真实 ID 后，遍历所有 Markdown 文件，并将 XSPACE_<KEY> 替换为真实空间 ID：

   sed -i \
     -e "s|XSPACE_GUIDES|${GUIDES_SPACE_ID}|g" \
     -e "s|XSPACE_API|${API_SPACE_ID}|g" \
     -e "s|XSPACE_CHANGELOG|${CHANGELOG_SPACE_ID}|g" \
     $(find . -name '*.md' -not -path './.git/*')
   

3. 提交并推送替换结果。GitBook 会通过 Git Sync 获取更改，链接将在下一次渲染时解析。

若要采用整洁的实现方式，请在仓库根目录中保存一个 cross-space-links.yaml，将哨兵键映射到空间 ID，并在空间创建后生成该文件。这样，如果有人重新运行替换脚本，过程仍可复现。完整模式包括锚点链接、特定页面链接和示例替换脚本，详见 references/cross-space-links.md。

**这些内容会写入：**脚手架（使用哨兵 ID）、跨空间生成内容时的 Markdown，以及创建后的替换步骤。搭建脚手架时不要尝试编写真实的 app.gitbook.com/s/<id>/... 链接——此时 ID 尚不存在，任何猜测都会导致链接失效。

示例内容查阅位置

references/example-site/ 是此技能附带的生产风格 GitBook 站点精简快照。原站点包含 12 个空间（首页、三个产品空间、三个版本的开发者 API、三个指南空间、合作伙伴、更新日志，以及外部内容 connections/ 树），约有 200 个内容文件；附带的快照保留了约 150 个文件，以符合文件数量限制。

请先阅读 references/example-site/PRUNE-NOTES.md——其中准确说明了保留和删除的内容，并列出了可用于研究特定模式的高价值文件。简而言之：

• 每个空间的完整结构骨架均已保留，包括 README.md、SUMMARY.md、.gitbook/vars.yaml 和 .gitbook/includes/。
• developers/v2/ 完整保留，作为规范示例。developers/v1/（旧版）和 developers/v3/（测试版）已删除——它们的结构与 v2 完全相同，仅内容因版本而异。多版本 API 文档的模式记录在 PRUNE-NOTES.md 中，也可在 structure.json 中查看。
• connections/——每个子文件夹（blog/、community/、youtube/）均保留了其 index.html 和一篇代表性文章，以便保留可供学习的元数据模式。
• customization.json 和 structure.json 是完整的 API 导出文件，描述了整个原始站点，包括已精简的空间和页面。每个空间内的 SUMMARY.md 文件也描述了原始目录树——其中一些链接指向已精简的页面，这是预期情况。

值得研究的文件，按要展示的模式分类：

模式	要读取的文件
更新区块 + 标签	changelog/README.md + changelog/.gitbook/tags.yaml
builtin:openapi SUMMARY 模式	developers/v2/SUMMARY.md（查看围栏 YAML 条目）
Mermaid 图表（流程图、时序图）	products/payments/concepts/payment-lifecycle.md、developers/v2/identity-api/README.md
布局 width: wide + 封面图片	home/README.md、developers/v2/README.md
用于导航的卡片表格	home/README.md、partners/README.md
通过 {% if visitor.claims... %} 实现条件内容	products/payments/accept-payments/take-a-payment.md
组合使用选项卡和步骤导航	developers/v2/getting-started/quickstart.md、developers/v2/getting-started/authentication.md
带代码示例的 Webhook 文档	developers/v2/webhooks/verifying-signatures.md
可复用的内容引入	home/.gitbook/includes/persona-switcher.md
.gitbook/vars.yaml 变量	任意空间的 .gitbook/vars.yaml
分组的 SUMMARY.md（通过 ## Heading 划分章节）	任意空间的 SUMMARY.md 文件

如果需要查找附带快照中未包含的模式（例如，并列展示旧版/测试版 API 空间，或完整的外部内容文章目录），请以 structure.json 为权威结构来源，并参考 PRUNE-NOTES.md 了解这些省略内容所代表的模式。

脚手架搭建完成后：

cd my-docs
git init
git add .
git commit -m "Initial scaffold"

如果用户需要远程仓库，且 gh/glab 可用：

# GitHub
gh repo create <name> --private --source=. --push

# GitLab
glab repo create <name> --private && git push -u origin main

如果这两个工具都不可用，请在脚手架搭建完成前明确告知用户。以下两种做法均可：

• 仅创建本地仓库，并在交接说明中手动添加远程仓库步骤。 在本地提交，并在交接说明中为用户添加一个“步骤 0”，内容为：“在你的机器上创建一个名为 <name> 的私有 GitHub 或 GitLab 仓库，然后在此目录中运行 git remote add origin <url> && git push -u origin main。” 将此步骤放在 GitBook 界面操作步骤之前——用户需要先推送仓库，才能通过 Git Sync 连接。
• 请用户安装 gh 或 glab。 如果他们之后还要创建更多站点，这个工具值得安装。

不要悄悄默认只创建本地仓库——没有远程仓库，也没有添加远程仓库说明，会让用户在尝试配置 Git Sync 时才发现问题。

迁移与内容质量

大多数实际构建并非从零开始，而是从其他文档平台（Mintlify、Docusaurus、ReadTheDocs、旧版 GitBook）迁移，或重组现有 Markdown。这些工作有其独特的方法，与“新建一个站点”不同。如果处理不当，最终产物看起来像文档站点，读起来却像机器生成的内容。

完整工作流见 references/migration-from-other-platforms.md。要点如下：

先复现源站，再重新构思。 用户已有线上文档站点时，先获取并查看渲染后的首页，再生成任何主页内容。当前信息架构就是规范；仅凭 Markdown 文件夹通常看不出用户采用这种结构的原因。如果源站已有可行方案，却从头编造卡片网格、主视觉区块和“最新动态”版块，这是最常见的内容质量问题。

批量导出很少能作为完整内容来源。 Mintlify 的 llms-full.txt、ReadTheDocs HTML 抓取结果，以及类似的 AI 友好型导出，往往会剥离可见内容（自定义组件被渲染为原始标记，AI 提示词区块被展开为行内内容，API 表格中的参数名称被删掉）。批量转换后，应抽样将渲染页面与原站对照，并标出缺失内容的位置——不要假装导出结果就是全部内容。

重建关键页面，而非所有页面。 迁移 280 个页面，不代表要用 GitBook 的写法手工重建 280 个页面。正确做法是批量转换长尾内容，然后精心重建 4–6 个关键页面——主页、每个空间的顶层落地页，以及最重要的操作指南——并使用完整的区块体系。其余内容可以迭代改进，逐步达到标准。

格式清理是有记录的步骤。 草率的 Markdown 转换会留下残余问题（外部组件标签、格式错误的代码围栏、失效的内部链接）。批量转换后，应在首次提交前进行清理：移除不受支持的组件、规范代码围栏，并将 /docs/... 路径改写为 GitBook URL 或相对路径。跳过这一步，会导致仓库几乎能正常渲染。

不要自动生成并不存在的前置元数据。 源站没有图标时，不要根据 URL 路径自动挑选图标——否则会出现一片不匹配的齿轮图标。源站没有描述时，就让该字段留空；不要用 Source: <url> 作为占位内容（这些文字会泄露到侧边栏预览和搜索结果中）。

API 参考优先使用 OpenAPI。 如果迁移的站点包含 API 参考内容，并且你能获取 OpenAPI 规范（或从其代码库生成规范），就通过 builtin:openapi 处理整个 API 参考空间。手工转换 70 页参考文档，几乎总是比不上自动生成的 3 个文件。

内部链接转换应一次性全面处理，而不是逐页处理。 确定结构后，遍历每个 Markdown 文件，将 /docs/... 链接改写为相对 .md 路径（同一空间内）或 https://app.gitbook.com/s/<spaceId>/<path> URL（跨空间）。边看每页边处理会造成链接不一致；使用 slug 到路径的清单一次性全面处理，则可靠得多。

谨慎使用会重新生成内容的辅助脚本。 如果使用转换器或 SUMMARY 生成器，默认应使其具备幂等性。跳过已存在的文件。第二次运行就覆盖精心调整过的主页，会带来严重问题。绝不要对可能包含手工编辑内容的目录运行 rm -rf <space>/；如果必须重新生成，请写入 <space>/_generated/，再进行合并或差异比较。

驱动 GitBook 构建站点

以下步骤描述的是预期结果，而不是具体的端点调用——请使用你在上文“如何与 GitBook 通信”中选定的传输方式。使用 REST API 时，每一步对应的具体端点、请求正文和预期响应均列在 references/api-cheatsheet.md 中；进行任何调用前请先阅读，因为其中的架构细节较为复杂（尤其是自定义设置）。使用 MCP 时，对应的工具涵盖相同步骤；请阅读工具自身的架构，而不是查询 REST 路径。

新建站点的标准流程

1. 验证访问权限并查找组织：确认已通过身份验证的用户，然后列出组织。
2. 创建站点，使用 {title, type, visibility, spaces?}。默认使用 Ultimate（type: "ultimate"）。只有用户明确选择时才使用免费的 type: "basic"。如果尚无空间，请不要包含 spaces；之后可以再添加。
3. **决定如何创建空间。**有两种方式：
   • 站点级 Git Sync（推荐，默认）：告诉用户从站点侧边栏打开一次 Git Sync，连接仓库和分支，然后在 Content mapping 下将每个空间映射到对应目录。只需在 UI 中完成这一次操作，即可创建或关联所有空间，并一次性为它们配置同步。这项技能的任务是为用户提供准确、可复制的操作说明，指导其完成这一次操作。请参阅 references/git-sync-handoff.md。
   • 优先以编程方式创建：直接创建空空间，将其作为站点空间添加到站点，然后通过内容导入或应用模板来加载内容。之后，如果用户希望进行双向同步，仍需在 UI 中配置 Git Sync；届时仍应默认推荐站点级同步，而不是逐个空间配置。
4. 添加分区（带分组导航的多空间站点）：通过为一个空间关联标题和可选图标来创建分区。
5. 解析跨空间链接占位符：如果脚手架生成的 Markdown 中包含 XSPACE_<KEY> 占位符（跨越空间边界的链接都应该包含此占位符），此时应将它们替换为步骤 3 或 4 返回的实际空间 ID。替换脚本请参阅 references/cross-space-links.md。提交并推送更改——下次运行 Git Sync 时会获取这些更改。
6. 应用自定义设置（品牌形象）——完整的架构涵盖范围很广：主题预设、颜色（每种颜色均为 {light, dark} 主题配对）、favicon、页眉（logo、primaryLink、links）、页脚（链接分组、版权信息）、主题（默认浅色或深色、可切换）、AI 模式、PDF 导出等。常见品牌设置场景的操作方案请参阅 references/customization-recipes.md。只修改你需要更改的字段——先获取当前设置，在内存中修改，然后写回完整结果，不要猜测部分请求内容。
7. 验证：获取站点结构以确认最终树状结构，并获取其自定义设置以确认配置。

多语言站点与自动翻译的空间

GitBook 支持自动翻译站点空间：单个英语空间（从 Git 同步）可以与其他语言的计算翻译配对。这些翻译不是 Git 仓库中的独立空间，而是完全存放在 GitBook 中，并通过每个分区设置下的界面进行配置。它们会作为额外的 site-space 对象显示在同一分区下，每个对象都有不同的 language，且没有 gitSync 字段。

实际来说：

• 不要在仓库中为每种语言搭建目录。 Git 仓库中每个主题只有一个空间，语言为英语。该技能会为每个内容区域写入一套 Markdown 文件，仅此而已。
• 每个分区可以包含多个站点空间。 “Payments” 分区可能包含 Payments（en，Git 同步）、Payments (FR)（fr，计算翻译）、Payments (DE)（de，计算翻译）等。结构响应会列出所有空间；只有英语空间需要移交给 Git Sync。
• localizedTitle 会出现在各处。 分区、分区组、页眉链接、页脚链接以及站点标题本身都带有 localizedTitle: {de: "...", fr: "...", ...} 映射。读取自定义设置时，即使用户只用英语设置了字段，也要预期会看到翻译。除非用户要求，否则不要移除这些内容。
• 自动翻译目前仅能通过界面启用。如果用户希望在某个分区启用自动翻译，请将其作为站点级 Git Sync 移交的一部分说明：“配置好 Git Sync 后，前往 Site → Sections → Payments → Translations，启用所需的语言。”

当用户要求“创建一个支持五种语言的文档站点”时，答案应是在 Git 中维护一套英语内容树，并在界面中为各分区启用自动翻译，而不是创建五份 Markdown 副本。

分区组

站点结构的导航最多可包含三个嵌套层级：

1. 根目录下的站点空间（扁平站点，没有分区）
2. 包含站点空间的分区（典型的多空间站点）
3. 包含分区、且分区中包含站点空间的分区组（用于归类相关分区，例如包含 Payments、Identity、Connect 分区的“Products”分区组）

站点结构响应是递归的——分区组的 sections 数组可以同时包含分区和其他分区组。设计结构时，只有在有 3 个或更多密切相关的分区，且将它们在顶部导航中分组显示更合适时，才使用分区组。对于只有 2 个分区的站点，将分区放在根目录下会更清晰。

更新现有站点

如果用户要求修改已有站点，务必先获取当前状态：

• 站点元数据
• 结构（分区和空间）
• 自定义设置（站点级或各站点空间级），用于品牌设置

然后进行有针对性的修改，而不是整体替换。如果只想更改一个字段，不要替换整个自定义设置负载——先获取当前设置，在内存中修改，再写回完整结果。

何时使用内容导入，何时使用 Git Sync

• 内容导入用于将外部内容（网站 URL、一组文件）导入空间，适合从其他文档工具进行一次性迁移。
• Git Sync用于 Git 仓库与站点之间持续的双向同步（也可作为后备方案，在单个空间上使用）。这是标准流程的优化方向。
• 如果用户已有优质内容存放在 Git 和 GitBook 之外（例如 Notion 导出内容），请先导入，然后可以选择启用 Git Sync。

品牌塑造与自定义

SiteCustomizationSettings 架构内容较多。随附的 references/example-site/customization.json 是一个生产风格演示站点的真实导出文件，是最有用的参考资料——编写任何自定义配置内容之前，请先阅读。它展示了所有嵌套字段如何组合、localizedTitle 映射的工作方式，以及条件式页眉链接的结构。

完整字段列表、架构特性（styling.background 必填但已弃用、header.links[] 要求包含 links: []）、页眉/页脚链接的 ContentRef 格式，以及条件式链接模式，都在 references/customization-recipes.md 中——请参阅“字段速查表”和场景 4–5。免费站点不支持高级版和旗舰版功能（自定义徽标、自定义字体、语义颜色、页脚徽标、高级自定义），使用时会被拒绝——请妥善处理；使用 REST 路径时，请参阅 references/api-cheatsheet.md 了解确切的错误响应。

references/customization-recipes.md 提供了以下内容的完整示例：最简品牌设置（仅颜色 + 网站图标）、包含徽标和字体的完整品牌设置、仅深色模式并带切换功能，以及启用 AI 助手并提供建议提示词。

如需参考完整的真实配置内容，references/example-site/customization.json 是此技能随附的生产站点自定义配置导出文件。阅读它是了解实际应用中各字段如何组合的最快方式——比抽象架构更实用。不要将其整体粘贴到新站点；应将其用作字段结构和选择的范例。

如需了解结构响应的真实示例（分区、分区组、多语言站点空间），请同时查看 references/example-site/structure.json。

Git Sync 移交

这一部分必须做到精致完善。推送仓库并创建站点后，请为整个站点生成一份清晰的移交说明——不要为每个空间分别生成一份。用户需要了解：

1. 仓库 URL 和分支名称（通常为 main）
2. 站点的项目目录——gitbook-docs.yaml 所在位置（留空/根目录，除非这是一个大型单体仓库）
3. 初始同步方向——几乎总是 GitHub → GitBook（或 GitLab → GitBook），因为此时仓库是事实来源
4. 内容映射——每个空间的标题及对应目录（例如，Guides → ./guides，API Reference → ./api-reference）

references/git-sync-handoff.md 提供了一份可填写并呈现给用户的模板：只需连接一次，并在同一轮中映射所有空间。请将其呈现为一份编号列表，而不是一大段文字，也不要按空间重复说明。只有当某个空间需要拆分到独立仓库/分支时，才添加第二份移交说明——请参阅该文件中的“When a space needs its own repo or branch”。用户完成后，请让他们确认——此时你可以通过程序检查每个空间的同步状态以进行验证（目前还没有站点级状态端点，因此底层仍是逐空间检查）。

应避免的常见错误

• 不要将 PAT 写入 Claude 创建的任何文件。 始终从环境中读取。
• 不要悄悄替换内容来源。 如果无法读取用户指定的仓库或文件夹（请记住，私有仓库和不存在的仓库一样会返回 404），请停止并询问用户——绝不要改用相似的公开仓库。请参阅“构建前验证内容来源”。
• 不要尝试以编程方式设置 Git Sync。 无论使用哪种传输方式，都只能通过 UI 设置——始终转到 UI 移交流程。（API 中虽然存在 installGitSyncProviderOnTarget，但它无法免除 OAuth 步骤，而且尚未通过 MCP 提供——不要因为看起来很方便就绕过移交流程。）
• 不要一次只为一个空间移交 Git Sync。 默认使用全站级 Git Sync——建立一个连接，为每个空间进行一次内容映射。只有在特定空间需要独立的仓库或分支时，才改用逐空间 Git Sync。
• 不要凭记忆粘贴完整的自定义配置载荷。 获取当前状态，修改后再写回完整结果。架构会不断演变，这样做也能减少错误。
• 不要为每个内容章节都创建一个空间。 空间是一个较重的单位（有自己的 URL slug、同步和设置）。要进行子分组，应使用空间内的页面和文件夹。
• 不要跳过结构规划和确认步骤，即使用户很着急也不例外。重构已发布的网站很麻烦。
• 不要过度格式化 SUMMARY.md。 GitBook 的解析器对其格式要求严格。请遵循 write-docs 中的规则。
• 完成变更请求编辑时，必须同时提供两个链接。 请参阅“提交变更请求后：必须提供两个链接”——只提供 CR 差异链接并不是完整的答复。

参考文件

• references/api-cheatsheet.md — 本技能使用的完整 API 调用集，包含 curl 风格的请求正文和预期响应
• references/site-structure-design.md — 从原始输入制定空间／章节／页面规划的启发式方法和实例
• references/migration-from-other-platforms.md — 迁移前检查、源平台映射（Mintlify、Docusaurus、GitBook v1、RTD）、锚点页面策略、格式处理、内部链接检查。开始任何迁移构建前都要阅读，不要等到构建后再读。
• references/block-ecosystem.md — 针对不同内容情境选择 GitBook 区块的指南，包含决策表和实例（Updates、Mermaid、OpenAPI 自动生成、布局标记、卡片表格、条件内容、包含项、变量）。生成任何非简单页面前都要阅读。
• references/cross-space-links.md — Markdown 中跨空间链接的标记和解析工作流，附有可运行的替换脚本
• references/git-sync-handoff.md — 面向用户的 Git Sync 设置说明模板，优先使用全站级设置，并将逐空间设置作为有据可查的后备方案
• references/customization-recipes.md — 常见场景的品牌自定义载荷实例
• references/example-site/ — 真实生产风格 GitBook 网站仓库的精简快照（约 150 个文件），包含 Markdown、SUMMARY.md 和 .gitbook/ 配置。请先阅读其中的 PRUNE-NOTES.md——它说明保留和删去了哪些内容，并列出了针对特定模式的重要文件。
• references/example-site/customization.json — 该网站的自定义配置导出，展示了完整的真实品牌配置载荷
• references/example-site/structure.json — 结构导出，展示了章节、章节组和多语言网站空间（英文 Git 同步 + 自动翻译）