> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/skill/configure-site.md).

# 配置站点

端到端创建和维护完整的 GitBook 文档站点——从源内容设计站点结构，以 monorepo 布局搭建 Git 仓库，设置 GitHub/GitLab 远程仓库，推动

用于创建和维护整个 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 工具已连接，直接调用它们——它们自己的 schema 描述了参数。如果你走的是 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 不覆盖的任何内容。需要 `GITBOOK_TOKEN` 作为每个请求中的 bearer 头。

同一个个人访问令牌（来自 <https://app.gitbook.com/account/developer）可作为这两者的> bearer token。MCP 另外支持 OAuth，作为比粘贴令牌更友好的替代方案。

**如果你最终需要令牌** （REST API 路径，或未使用 OAuth 的 MCP），请在会话开始时检查：

```bash
[ -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（其包装了它）都只允许你 *读取* 最终的 Git Sync 状态，不能设置它。虽然有一个 API 操作， `installGitSyncProviderOnTarget`，它可以针对站点或空间，但账户连接（OAuth）步骤仍然必须在应用中完成，而且它尚未通过 GitBook 的 MCP 服务器暴露——把它视为尚不可用，而不是围绕它构建流程。

**Git Sync 现在在站点级别配置，这也是默认应该选择的方式。** 一个连接（一个仓库，一个分支）覆盖整个站点； `gitbook-docs.yaml` 将每个空间映射到自己的目录，这与此技能已经为 monorepo 搭建的形状相同。按空间的 Git Sync 仍然存在，但现在是例外——只有当某个特定空间需要独立仓库或分支时才使用它（例如，无法放在公共文档仓库中的私有空间）。

这意味着最干净的端到端流程始终是：

1. Claude 在本地把 Git 仓库搭建成 monorepo（每个空间一个目录），最好带有 `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: site` Ultimate 方案**、公开可见，除非用户明确说明其他情况。大多数真实客户都希望 Ultimate 功能集（自定义域名、AI 助手、高级自定义、隐藏 GitBook 商标、自定义字体、自定义徽标）。免费层级（`type: basic`）只适用于明显低风险的用例，例如个人开源副项目。如果不确定，就问： *“我会按 Ultimate 方案帮你设置，除非你更想用免费层级——要我降级吗？”* ——Ultimate 中静默缺失的功能 `basic` （没有 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（浅色 + 深色）、favicon、字体选择（或 GitBook 的默认字体之一）、页眉链接、页脚文本/链接、主题预设（`简洁`, `柔和`, `醒目`, `渐变`）。对于 Ultimate 站点，还可以考虑 AI 助手的入门提示（3-5 个访客可能会问的简短问题）。
* **站点结构** ——章节，而不是站点空间。如果站点有多个空间，请与用户明确规划 **章节列表** ：每个章节都有标题、Font Awesome 图标名称和描述。章节图标和描述是一级导航家具——访客会看到它们——提前收集能省去之后每个章节的后续更新。示例： `[{title: "Guides", icon: "book-open", description: "概念与教程"}, {title: "API Reference", icon: "code", description: "REST API 和 SDK"}, {title: "Changelog", icon: "clock-rotate-left", description: "更新和发布说明"}]`.
* **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. **绝不要替换来源。** 不要搜索、猜测或退回到一个同名的仓库或站点——哪怕看起来完全一样。从错误来源构建文档站点，远比停下来询问更糟糕。任何更改来源都需要用户明确同意。

## 状态变更操作的确认门槛

创建站点、创建空间、添加章节、附加 site-spaces，以及自定义更改，都会创建或修改那些 **会立即对组织中的所有人可见** 且清理起来需要真实成本的对象。把它们视为重操作。

规则： **在没有先向用户展示一个单屏预览、准确说明即将发生什么并获得明确“yes”之前，绝不要进行状态变更。**

一个好的预览应该简短且具体：

> 即将在组织中执行 **Acme Inc** (`org_abc123`):
>
> * 创建站点 **“Acme Platform Docs”** （类型：site，方案：ultimate，可见性：public）
> * 创建 3 个空空间： **指南**, **API 参考**, **更新日志**
> * 将 Guides 设为默认章节；为 API Reference 和 Changelog 创建章节
>
> 继续？（yes/no）

糟糕的预览很模糊（“我现在会创建站点”）或者埋在长篇解释里。保持可扫描。

同样的规则也适用于破坏性操作——删除站点、空间、章节或自定义覆盖——只是要更少歧义（“这将删除站点 **Acme Platform Docs** 以及它的 3 个空间。空间和站点可在 7 天内恢复，之后永久删除。确认？”）。

当用户已经在结构设计步骤中确认了一个多步骤计划时，你不需要对该计划中的每个单独操作再次询问——但如果计划中的任何内容发生变化（额外的空间、不同的可见性），要重新确认。

对于只读操作（获取或列出），不需要确认。

## 在变更请求推送后：必须提供两个链接

每当这个技能（或 `write-docs`，它把页面编写委托给）通过变更请求推送内容时——通过 MCP 的 `updateChangeRequestContent`/`create_change_request`/`submit_or_merge_change_request` 精选工具， `invoke_operation`，或 REST 等价方法——编辑 **尚未完成** ，直到每次都向用户报告以下两项：

1. **变更请求的 diff/editor 链接** (`urls.app`）——在 GitBook 应用中查看该变更的链接。
2. **站点预览链接** ——应用了该变更后的渲染文档。这里需要单独查找：站点 URL 位于 **Site** 对象的站点 URL（`urls.published` 当站点公开时，否则为 `urls.preview`）上，而不在变更请求对象上，而且 **你必须将 `/~/changes/<number>/` 附加到它后面**，并去掉 API 返回的尾部斜杠。若没有这个段，链接显示的是站点的 *当前* 内容，而不是这次变更请求——它能正常加载，但显示的是错误内容。

这是硬性规则，与上面的确认门槛同等重要——不是有时间才加的锦上添花。参见 `write-docs`中的“每当涉及变更请求时，必须提供两个链接”和 `cr-create` 技能中的“显示预览链接”，了解确切解析步骤（MCP： `getSpaceById` → 通过 `list_sites`/`get_site_structure` 或每个站点的 site-spaces → 查找站点 `getSiteById` ；REST：对应的链式 `.urls.preview`GET `调用）。如果该空间没有附加到已发布站点，请直接说明，而不是只给出 diff 链接却不解释。` 设计站点结构

## 在编写任何文件或在 GitBook 中创建任何内容之前，先决定结构并让用户审阅。薄弱的结构是文档站点失败的单一最大原因。

这一步的输出是一个小计划，理想情况下包含三部分：

空间列表

1. **——每个内容连贯的主体一个空间。保持它小巧（通常 1–4 个空间）。空间是导航和 Git Sync 的单位，所以不要把单个受众的内容拆到多个空间。** 章节分组
2. **（如果是多空间）——章节是站点导航中的顶级分区，例如“产品” / “开发者” / “资源”。一个章节可以容纳一个或多个空间。** 每个空间的页面树
3. **——文件夹和页面，并为每个页面提供一两句摘要。深度应与内容匹配；浅层树（1–2 级）通常最好。** 从原始输入到结构计划的完整启发式规则集合在

references/site-structure-design.md `——当你第一次为非平凡站点做这件事时请阅读它。` 在搭建文件之前，始终向用户展示计划并获得明确批准。 **在 Git 内重组很便宜，但一旦站点发布并被索引，成本就高了。** 当用户给出一个折叠后的单条指令时，关于确认的一点说明：诸如

“规划结构然后搭建它” *这样的提示会诱使你跳过门槛。不要。先把计划作为一个清晰、易扫读的块展示出来，然后要么等待“yes”，要么——如果因为提示非常明确而你已经开始搭建——展示你在计划中做出的决定，并提供一个简单的纠正机会（“如果有任何不对，请告诉我，我会在继续之前重做”）。关键是用户在盯着二十个生成文件时，能看到这个计划* ，而重做此时仍然成本很低。 **然后再** 搭建仓库脚手架

## 一旦结构达成一致，就按 monorepo 布局仓库——即使是单空间站点，这样也一致且面向未来。每个空间都是一个目录，包含自己的

README.md `（主页）和` SUMMARY.md `（目录）。可选地还有一个` 文件夹用于每个空间的变量和可复用内容块，此外可选一个 `.gitbook/` 用于高级同步配置。 `.gitbook.yaml` 三空间站点的示例布局：

my-docs/

```
├── .gitignore
├── README.md                    # 仓库级 README（不是空间主页）
├── guides/                      # 空间 1
│   ├── README.md                # 空间主页
│   ├── SUMMARY.md
│   ├── .gitbook/
│   │   └── vars.yaml            # 可选：空间级变量
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quickstart.md
│   └── concepts/
│       └── ...
├── api-reference/               # 空间 2
│   ├── README.md
│   └── endpoints/
│   ├── .gitbook/
└── changelog/                   # 空间 3
├── api-reference/               # 空间 2
├── README.md
    └── SUMMARY.md
    关于此布局，有几点经常让人踩坑：
```

.gitbook/vars.yaml

* **`.gitbook.yaml` 是可选的。** GitBook 在默认约定下运作良好，即 `（主页）和` + `（目录）。可选地还有一个` 每个空间一个。只有在需要覆盖根目录、定义重定向或做其他非默认操作时，才添加一个 `.gitbook.yaml` 。捆绑示例站点（`references/example-site/`）没有任何 `.gitbook.yaml` 文件，但运行完美。
* **`.gitbook/vars.yaml`** 保存空间作用域变量，页面可以内联引用它们（例如 `support_email: support@evolve.com` 引用为 `{% vars.support_email %}`）。适用于任何会出现在许多页面上的值。
* **`.gitbook/includes/<name>.md`** 保存可复用的内容块——一个你可以通过 `{% include "...persona-switcher" %}`嵌入许多页面的片段。用它们替代复制粘贴样板。
* 空间目录名称（例如 `guides/`）是用户在 **内容映射** 下将该空间映射到的名称，当为整个站点配置 Git Sync 时——而不是站点的“Project directory”字段，后者只指向 `gitbook-docs.yaml` 本身所在的位置（在此布局中是仓库根目录）。不要把两者混淆；参见 `references/git-sync-handoff.md`.
* 考虑在仓库根目录预先编写一个 `gitbook-docs.yaml` ，把每个空间映射到它的目录（形状见 `references/git-sync-handoff.md` ）。GitBook 会在首次同步时读取它，因此用户在设置期间需要手工填写的内容更少。

一个最小的 `.gitbook.yaml`，如果你确实需要一个的话，看起来像这样：

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

### 仓库级 README 和 .gitignore

仓库级 `（主页）和` （仓库顶部，不在空间内）应该解释这个文件夹是什么以及它与已发布站点的关系——而不是重复文档本身。简短一段就够了：

```markdown
# my-docs

My Product 文档站点的源文件（https://docs.example.com）。每个顶层文件夹
都是一个独立的 GitBook 空间；一旦配置好，编辑会通过 Git Sync 双向流动。
```

一个 `.gitignore` 应把操作系统垃圾文件和编辑器设置排除在仓库之外。合理默认值：

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

如果团队还有其他生成产物（例如在别处从源代码构建出的 OpenAPI 规范），也加进去。

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

最常见的脚手架错误是沿着文件树生成 SUMMARY.md：顶部是 README，其他每个文件都作为缩进在 README 下的子项。这会产生令人沮丧的导航——每个页面都是“主页的子页面”，文件夹名会变成组标题，不管它们对读者是否有意义，信息架构镜像的是文件系统而不是用户的心智模型。

**正确模式，按顺序：**

1. **在结构设计期间，从用户那里收集期望的导航。** 明确要求他们列出每个空间的顶层页面和命名分组。这里是让文件夹名称与导航现实相匹配的地方，也是用户可以告诉你“其实我想把 Authentication 作为顶层页面，而不是放在 Concepts 下面”的地方。
2. **把文件夹布局成与约定好的导航一致，而不是反过来。** 如果用户希望一个空间里有三个分组——“Getting started”、“Concepts”、“Tutorials”——那么空间目录就应该有三个同名子文件夹（slug 化），每个都带自己的页面。不要从一个偶然的子文件夹里自动抽取出第四个分组。
3. **把 SUMMARY.md 写成用户明确同意的形状。** GitBook 支持的语法：

   ```markdown
   # 目录

   * [空间主页](README.md)
   * [顶层页面 A](top-level-a.md)
   * [顶层页面 B](top-level-b.md)

   ## 第一组

   * [组内页面](first-group/page.md)
   * [另一页](first-group/another.md)

   ## 第二组

   * [页面](second-group/page.md)
   ```

   关键结构规则：

   * **README.md 单独占据最顶部的一行，作为同级项**，而不是父级。其他顶级页面作为同级项依次排列。
   * **`## 组名` 标题引入各组。** 组内页面以扁平项目符号列在标题下方—— *不是* 缩进在 README 之下。
   * *避免机械地用“ README.md”再把所有内容都嵌套到其下。*\* 这会把整个导航折叠成主页下的一棵树，并让侧边栏里的每个页面都看起来像主页的子页面。
   * **组名来自用户，而不是文件夹名。** “concepts/” 可以是文件夹 slug，但如果更清晰，组标题可以是“工作原理”。
   * **每个页面一条项目符号，不要额外格式。** SUMMARY 中不要加粗，也不要写描述——这些内容放在页面 frontmatter 里。
4. **特殊情况模式** 不是普通项目符号的：
   * **OpenAPI 自动生成的端点页面** 将围栏 YAML 块作为项目符号内容（`type: builtin:openapi` — 见 `references/api-cheatsheet.md`).
   * **外部链接** 是 `* [标题](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 文件** — `（主页）和`, `（目录）。可选地还有一个`，每个页面都——遵循 `write-docs` 技能。它是以下内容的权威参考：

* **Frontmatter** 包括 `图标：` 字段。图标是 Font Awesome 名称，不带 `fa-` 前缀（例如 `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`等）。
* **`（目录）。可选地还有一个` 语法。** 严格格式——每页一个项目符号，可选 `## 组名` 标题，不要额外格式。以及用于自动从规范生成端点页面的特殊 `type: builtin:openapi` 语法。
* **富块** ——标签页、提示、步骤器、列、卡片表格、可展开内容、嵌入、带有以下条件内容 `{% if visitor.claims... %}`，OpenAPI 块、 **更新** 块（changelog）、可复用内容 include。
* **GitBook 风格的 markdown 差异** 相对于 CommonMark。

这里不要重新发明这些。随附的 `references/example-site/` 是最实用的参考，可了解惯用内容的样子。

### 主动选择合适的块——而不是默认回退

一种常见失败模式：Claude 生成的文档 *能用* ，却对所有内容都使用普通 markdown，错过了让 GitBook 站点像真实产品一样的富块。 **该技能应主动使用专门的块**，而不是退回到纯文本和项目符号。需要内化的具体模式：

* **更新日志** → `{% updates %}` 块，使用 `{% update date="..." tags="..." %}` 条目。自动生成 RSS，支持标签（定义于 `.gitbook/tags.yaml`）。不要写 `## YYYY-MM-DD` 标题——那是错误的结构。
* **API 端点参考** → 只需上传一次 OpenAPI 规范，通过以下方式自动生成页面 `type: builtin:openapi` 在 SUMMARY.md 中。不要手工编写端点页面——它们会漂移，而且规范本来就是权威来源。如果用户没有规范，先提议起草一个最小版本，而不是用长篇文字硬写。
* **状态机、流程、时序、简单架构** → ` ```mermaid ` 围栏块。不要用 ASCII 画方框和箭头；Mermaid 被支持，渲染清晰，而且对屏幕阅读器友好。
* **空间主页** → 对普通文档落地页使用 GitBook 默认布局（显示目录，默认宽度）。仅在以下情况使用 `layout: width: wide` ——只有当页面确实是营销风格时，例如英雄图、大型卡片网格、多列仪表盘布局。默认设置适合文档。
* **“选择你的路径”内容** → 卡片表格（`<table data-view="cards">`）。HTML 虽然冗长，但视觉效果胜过任何 markdown 方案。
* **并排介绍模式** → `{% columns %}` 块。标准是 50/50 两列。
* **重复性模板文本（3 个及以上位置）** → `.gitbook/includes/<name>.md` + `{% include "..." %}`.
* **重复的字面值（环境 URL、支持邮箱、版本固定值）** → `.gitbook/vars.yaml` + `<code class="expression">space.vars.<name></code>`.
* **多语言代码示例** → `{% tabs %}` 块。
* **3 步及以上的顺序式演示** → `{% stepper %}` 块。

完整的逐块指南，包含示例调用和“问题征兆 vs 修复”决策表，位于 `references/block-ecosystem.md`. **在生成任何非平凡页面之前先阅读它**，并为每个正在搭建的内容区域走一遍决策表——在默认使用普通 markdown 之前先问一句“这里有专门的块吗？”。

### 跨空间链接

多空间站点 *需要* 跨空间链接——它们能让站点感觉像一个连贯的产品，而不是一堆彼此独立的手册。 **不要为了避免它们而复制内容，也不要省略它们。** 它们是 GitBook 的一等功能；唯一的区别是它们需要真实的空间 ID 才能正确渲染，而 ID 只有在站点创建后才会存在。

markdown 中的模式其实就是指向目标空间 GitBook URL 的普通链接：

```markdown
概念方面请参见 [Authentication 概念页](https://app.gitbook.com/s/<spaceId>/concepts/authentication)。
```

GitBook 会在 `https://app.gitbook.com/s/<spaceId>/<path>` 渲染时解析它们，不受你的自定义域名影响。内部它们是 `ContentRefPage` 或 `ContentRefSpace` 设置了空间 ID 的内容引用；在 markdown 中它们只是显示为 URL。

**脚手架流程：**

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

   ```markdown
   参见 [Authentication 概念页](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication)。
   完整参考请见 [API Reference](https://app.gitbook.com/s/XSPACE_API/)。
   ```

   这些是指向不存在 GitBook 空间的有效 markdown 链接——不会破坏解析器，便于 grep 搜索，并且可以在 Git 中干净地往返。
2. **在空间创建后**，一旦拿到每个新空间的真实 ID，就遍历每个 markdown 文件并替换 `XSPACE_<KEY>` 为真实空间 ID：

   ```bash
   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`.

**这些内容会写入哪里：** 脚手架（带哨兵）、你在跨空间生成的 markdown 内容，以及创建后的解析步骤。不要尝试在脚手架阶段写入真实的 `app.gitbook.com/s/<id>/...` 链接——在搭建脚手架时 ID 还不存在，任何猜测都会变成坏链接。

### 示例内容看哪里

`references/example-site/` 是一个 **裁剪后的快照** ，它是与该技能捆绑的生产风格 GitBook 站点的快照。原始站点是一个包含 12 个空间的站点（主页、3 个产品空间、开发者 API 的 3 个版本、3 个指南空间、合作伙伴、changelog，以及一个外部内容 `connections/` 树），共有约 200 个内容文件；随附快照保留了约 150 个，以满足文件数量限制。

**先阅读 `references/example-site/PRUNE-NOTES.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 文件也描述了原始树状结构——其中一些链接指向已裁剪的页面，这是预期行为。

值得研究的文件， **按你想展示的模式来组织**:

| 模式                                        | 要阅读的文件                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Updates 块 + 标签                            | `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`                                                 |
| 可复用内容 include                             | `home/.gitbook/includes/persona-switcher.md`                                                     |
| `.gitbook/vars.yaml` 变量                   | 任意空间的 `.gitbook/vars.yaml`                                                                       |
| 分组 SUMMARY.md（通过以下方式划分章节 `## 标题`)         | 任意按空间分开的 `（目录）。可选地还有一个` 文件                                                                       |

当你需要随附快照中未体现的模式时（例如旧版/测试版的分版本 API 空间并排展示、完整的外部内容文章目录）， `structure.json` 是结构方面的权威来源，而 PRUNE-NOTES.md 说明了这些删减所代表的模式。

搭建脚手架后：

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

如果用户想要一个远程仓库 `gh`/`glab` 可用：

```bash
# 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 UI 步骤之前——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 或相对路径。跳过这一步会产出一个 *几乎* 能渲染的仓库。

**不要自动生成你没有的 frontmatter。** 当源内容没有图标时，不要根据 URL slug 自动挑选图标——你会生成一片不匹配的齿轮图标海洋。当源内容没有描述时，留空该字段；不要用以下内容填充： `来源：<url>` （该文本会泄漏到侧边栏预览和搜索中）。

**API 参考优先采用 OpenAPI。** 如果迁移站点包含 API 参考内容，并且你能拿到 OpenAPI 规范（或从其代码库生成一个），就把整个参考空间通过 `builtin:openapi`。一个 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`；在进行任何调用前先读它——这些 schema 很讲究（尤其是自定义）。在 MCP 路径上，对应工具覆盖相同步骤——请阅读它们自己的 schema，而不是去查 REST 路径。

### 新站点的标准顺序

1. **验证访问并找到组织**：确认已认证用户，然后列出组织。
2. **创建站点** 使用 `{title, type, visibility, spaces?}`. **默认选择 Ultimate** (`type: "site"`；套餐层级在创建后或通过组织计费设置到站点上）。使用 `type: "basic"` （免费）仅在用户明确选择时使用。不要包含 `spaces` 如果目前还没有空间——你可以稍后再添加。
3. **决定空间将如何创建。** 两条路径：
   * **全站 Git Sync（推荐，默认）**：告诉用户打开 **Git Sync** 只需从网站侧边栏执行一次，连接仓库/分支，并将每个空间映射到其下的目录 **内容映射**。这一次 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. **应用自定义** （品牌）——完整 schema 很宽泛：主题预设、颜色（每个颜色都以 `{light, dark}` 成对主题的形式）、favicon、页眉（logo、primaryLink、links）、页脚（链接组、版权）、主题（默认浅色/深色，可切换）、AI 模式、PDF 导出等等。常见品牌场景的配方见 `references/customization-recipes.md`。只修改你确实想改的字段——先获取当前设置，在内存中修改，然后把完整结果写回，而不是猜测一个部分负载。
7. **验证**：获取站点结构以确认最终树状结构，并获取其自定义以确认设置。

### 多语言站点和自动翻译空间

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

这在实践中意味着：

* **不要在仓库中为每种语言脚手架化目录。** Git 仓库中每个主题只有一个空间，使用英语。该技能每个内容区域只写一套 markdown 文件，仅此而已。
* **每个部分可以包含多个站点空间。** 一个“Payments”部分可能包含 `Payments` （en，Git 同步） `Payments（FR）` （fr，计算生成） `Payments（DE）` （de，计算生成）等等。结构响应会列出所有这些；只有英文的需要 Git Sync 交接。
* **`localizedTitle` 会在各处出现。** 部分、部分组、页眉链接、页脚链接，以及站点标题本身，都会带有一个 `localizedTitle: {de: "...", fr: "...", ...}` 映射。在读取自定义时，即使字段是用户只用英语设置的，也应预期会看到翻译。除非被要求，否则不要把这些去掉。
* 自动翻译目前只是 UI 侧功能。如果用户希望在某个部分上启用它，请将其作为站点级 Git Sync 交接的一部分来提示：“配置好 Git Sync 后，前往 **站点 → 部分 → Payments → 翻译** 并启用你想要的语言。”

当用户要求“一个五语言文档站点”时，答案是：Git 中一棵英语内容树，并在 UI 中按部分启用自动翻译——不是 markdown 的五份拷贝。

### 部分组

站点结构在导航中有三种可能的嵌套层级：

1. **站点空间** 位于根级（扁平站点，没有部分）
2. **分区** 包含站点空间（典型的多空间站点）
3. **部分组** 包含部分的部分组，部分再包含站点空间（用于归类相关部分，例如包含 Payments / Identity / Connect 部分的“Products”组）

站点的结构响应是递归的——某个部分组的 `章节` 数组既可容纳部分，也可容纳其他部分组。在设计结构时，只有当存在 3 个或以上紧密相关、且放在顶级导航中视觉分组更有利的部分时，才使用部分组。对于只有 2 个部分的站点，根级部分更清晰。

### 更新现有站点

当被要求修改一个已经存在的站点时， *始终* 先获取当前状态：

* 站点元数据
* 结构（部分 + 空间）
* 自定义（站点级或按站点空间），用于品牌设置

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

### 何时使用内容导入而不是 Git Sync

* **内容导入** 用于将外部内容（网站 URL、一组文件）导入到某个空间中。它适合从其他文档工具进行一次性迁移。
* **Git Sync** 用于 Git 仓库与站点之间的持续双向同步（或者，作为后备方案，单个空间同步）。这就是我们在标准流程中优化的内容。
* 如果用户已经有了位于 Git 和 GitBook 之外的优质内容（例如 Notion 导出），先导入它，然后再根据需要开启 Git Sync。

## 品牌与自定义

该 `SiteCustomizationSettings` schema 很大。捆绑的 `references/example-site/customization.json` 是来自一个生产风格演示的真实导出，也是最有用的参考——在编写任何自定义负载之前先阅读它。它展示了所有嵌套字段如何组合在一起，以及如何 `localizedTitle` 映射如何工作，以及条件页眉链接如何构造。

完整字段列表、schema 怪癖（`styling.background` 必需但已成遗留, `header.links[]` 需要 `links: []`), `ContentRef` 页眉/页脚链接的格式，以及条件链接模式都在 `references/customization-recipes.md` ——见“字段速查表”和场景 4–5。Premium 和 Ultimate 功能（自定义 logo、自定义字体、语义颜色、页脚 logo、高级自定义）在免费站点上会被拒绝——请优雅处理；在 REST 路径中请参见 `references/api-cheatsheet.md` 以获取确切的错误响应。

`references/customization-recipes.md` 提供了以下场景的工作示例：最小品牌配置（仅颜色 + favicon）、带 logo 和字体的完整品牌、仅深色模式且可切换、以及启用 AI 助手并附带建议提示词。

如需学习一个完整的真实负载， `references/example-site/customization.json` 是此技能附带的一个生产站点的自定义导出。阅读它是最快了解所有字段在实践中如何组合的方式——比抽象 schema 有用得多。不要把它原封不动地粘贴到新站点中；请把它作为结构和字段选择的模板。

如需查看结构响应的真实示例（部分、部分组、多语言站点空间），请参见 `references/example-site/structure.json` 以及它配套查看。

## Git Sync 交接

这一部分必须显得精致。仓库推送完成且站点已存在后，为整个站点生成一份清晰的交接——不要每个空间一块。用户需要：

1. 仓库 URL 和分支名（通常是 `main`)
2. 站点的 **项目目录** ——其中 `gitbook-docs.yaml` 所在的位置（如果不是更大的 monorepo，则为空/根目录）
3. 初始同步方向——几乎总是 **GitHub → GitBook** （或 GitLab → GitBook），因为此时仓库是事实来源
4. 该 **内容映射** ——每个空间的标题与其目录配对（例如 `指南` → `./guides`, `API 参考` → `./api-reference`)

`references/git-sync-handoff.md` 有一个你可以填写并展示给用户的模板：一次连接，在同一次操作中映射每个空间。把它渲染成单个编号列表，不要写成大段散文，也不要按空间重复。只有当某个特定空间需要被拆分到自己独立的仓库/分支时，才添加第二个交接块——参见该文件中的“当某个空间需要自己的仓库或分支时”。用户完成后，请让他们确认——到那时你就可以以编程方式检查每个空间的同步状态进行验证（目前还没有站点级状态端点，所以底层仍是逐空间检查）。

## 需要避免的常见错误

* **不要把 PAT 放在 Claude 写入的任何文件中。** 始终从环境变量中读取它。
* **不要悄悄更换内容来源。** 如果用户指定的仓库或文件夹无法读取（记住：私有仓库会返回 404，与不存在的仓库一样），就停下来并询问——绝不要使用外观相似的公开仓库继续。参见“在构建前验证内容来源。”
* **不要尝试以编程方式设置 Git Sync。** 无论传输方式如何，它都只能在 UI 中完成——始终通过 UI 交接流程。（`installGitSyncProviderOnTarget` 虽然它存在于 API 中，但并不能免除 OAuth 步骤，也尚未通过 MCP 暴露——不要因为看起来很诱人就绕过交接。）
* **不要一次只交接一个空间的 Git Sync。** 站点级 Git Sync 是默认方式——一次连接、一次为所有空间完成内容映射。只有当某个特定空间需要独立的仓库或分支时，才回退到按空间的 Git Sync。
* **不要凭记忆粘贴整个自定义负载。** 先获取当前状态，修改它，然后把完整结果写回。schema 会演进，这样可以少写很多 bug。
* **不要为内容的每个部分都创建一个空间。** 空间是一个重量级单元（它有自己的 URL slug、同步和设置）。空间内的页面和文件夹才是用于子分组的合适工具。
* **不要跳过结构规划与确认这一步**，即使用户很着急也不行。重组已发布站点是很痛苦的。
* **不要把 SUMMARY.md 格式化过度。** GitBook 的解析器对此非常严格。遵循其中的规则： `write-docs`.
* **不要在缺少两个链接的情况下完成变更请求编辑。** 参见“在变更请求推送后：两个链接都是必需的”——只有 CR diff 链接是不完整的答案。

## 参考文件

* `references/api-cheatsheet.md` ——此技能使用的完整 API 调用集合，包含 curl 风格的请求体和预期响应
* `——当你第一次为非平凡站点做这件事时请阅读它。` ——从原始输入到空间/部分/页面计划的启发式方法和完整示例
* `references/migration-from-other-platforms.md` ——预检、源平台映射（Mintlify、Docusaurus、GitBook v1、RTD）、锚点页策略、格式化处理、内部链接扫描。 **在进行任何迁移构建之前阅读这个，而不是之后。**
* `references/block-ecosystem.md` ——在何种内容场景下该使用哪个 GitBook 块，附决策表和完整示例（更新、Mermaid、OpenAPI 自动生成、布局标志、卡片表、条件内容、includes、vars）。 **在生成任何非平凡页面之前阅读这个。**
* `references/cross-space-links.md` ——markdown 中跨空间链接的哨兵标记与解析工作流，附可用的替换脚本
* `references/git-sync-handoff.md` ——面向用户的 Git Sync 设置说明模板，默认先站点级，按空间作为文档化后备方案
* `references/customization-recipes.md` ——常见场景的品牌负载示例
* `references/example-site/` ——一个真实生产风格 GitBook 站点仓库的精简快照（约 150 个文件，包含 markdown、 `（目录）。可选地还有一个`s、 `.gitbook/` 配置）。先阅读 `PRUNE-NOTES.md` 其中的说明——它解释了保留了什么、删除了什么，并列出了针对特定模式的高信号文件。
* `references/example-site/customization.json` ——该站点的自定义导出，展示了一个完整的真实世界品牌负载
* `references/example-site/structure.json` ——结构导出，展示部分、部分组，以及多语言站点空间（英语 Git 同步 + 自动翻译）


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/skill/configure-site.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.