write-docs

何时使用此技能

在以下情况下，通过 GitBook 文档工作时使用此技能：

• Git 同步的仓库（GitHub、GitLab）
• 本地 Markdown 编辑器
• IDE 集成
• 任何将 GitBook 内容作为文件而非通过 GitBook 界面编辑的环境

快速参考

GitBook 内容结构

GitBook 通过页面、空间和集合来组织内容：

• 页面是构成文档的独立 Markdown 文件
• 空间是按文档站点组织的页面集合
• 集合是多个空间的分组

文件结构：

/
  .gitbook/
    assets/              # GitBook-managed images and files
    includes/            # Reusable content blocks
    vars.yaml            # Space-level variables
  .gitbook.yaml          # Configuration
  README.md              # Homepage
  SUMMARY.md             # Table of contents
  getting-started/
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md

Frontmatter 字段（简要格式）：

---
description: "Page description for SEO"
icon: book-open
hidden: true
vars:
  page_variable: value
layout:
  width: default  # or 'wide'
  tableOfContents:
    visible: true
  pagination:
    visible: true
---

变量和表达式：

• 空间变量：/.gitbook/vars.yaml
• 页面变量：Frontmatter vars:
• 表达式语法：<code class="expression">space.vars.variableName</code>

最常用的自定义区块：

• {% tabs %}...{% endtabs %} — 用于展示不同选项
• {% hint style="..." %}...{% endhint %} — 提示框（信息／警告／危险／成功）
• {% stepper %}...{% endstepper %} — 按顺序排列的步骤
• <details>...<summary>...</details> — 可展开的内容

链接：

• 外部链接：[text](https://example.com)
• 相对链接（同一空间）：[text](page.md)、[text](../folder/page.md)
• 跨空间链接（不同空间）：[text](https://app.gitbook.com/s/<spaceId>/<path>) — 相对路径无法跨越空间边界，且 /spaces/<id>/pages/<id> 不是有效的链接格式。组织限定别名 https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> 的解析方式相同 — 请使用简短格式，但不要重写任一格式，也不要针对任一格式运行 lint（references/git-sync-serialisation.md）。通过 GET /orgs/{orgId}/spaces 获取 <spaceId>，并通过 GET /spaces/{spaceId}/content/pages 中页面的 path 字段获取 <path>。要搭建一个目标空间尚不存在的新站点？请使用 XSPACE_<KEY> 占位符；configure-site 会在创建空间后解析这些占位符。完整示例：references/markdown.md。
• 页面移动或重命名后仍可正常访问 — GitBook 会自动从旧路径创建重定向。

重要提示：

• 处理现有内容时，先阅读 SUMMARY.md
• 在本地编辑后，在 GitBook 中测试
• 确保 SUMMARY.md 与文件结构和页面标题保持同步
• OpenAPI 规范必须通过界面、API、MCP 或 CLI 上传，不能嵌入 Markdown

何时使用哪种区块

需求	使用	原因
按顺序排列的说明	{% stepper %}	清晰展示步骤顺序
可选方案（语言、平台）	{% tabs %}	用户可自行选择，避免页面杂乱
可选或详细信息	<details>	便于快速浏览页面
重要警告或提示	{% hint %}	彩色提示框（信息／警告／危险／成功）
并排比较	{% columns %}	并列布局（最多 2 列）
时间线或变更日志	{% updates %}	带日期的条目，可按标签筛选
可视化导航卡片	<table data-view="cards">	可点击的卡片网格
可下载文件	{% file %}	附带说明文字的文件
行动号召链接	<a class="button">	主要或次要按钮
跨页面复用的内容	{% include %}	单一事实来源
动态内容	<code class="expression">	渲染变量值

变量作用域：

如果变量...	定义于...	使用...访问
用于多个页面	/.gitbook/vars.yaml	space.vars.variableName
仅用于一个页面	Frontmatter vars:	page.vars.variableName

处理现有内容

1. 先阅读 SUMMARY.md — 查看完整目录和文件层级
2. 如果没有 SUMMARY.md — 直接浏览目录结构
3. 检查 .gitbook.yaml — 根路径、自定义 README/SUMMARY 位置、重定向
4. 检查 .gitbook/assets/ — 已上传的图片和文件
5. 检查 .gitbook/vars.yaml — 空间级变量

常见陷阱

跨空间链接：

• 不要使用相对路径链接到其他空间中的页面——这类链接无法解析。
• 不要使用 /spaces/<spaceId>/pages/<pageId>——这不是有效的 GitBook 链接格式。
• 请改用 https://app.gitbook.com/s/<spaceId>/<path>，其中 <path> 是目标页面的 path 字段（来自 GET /spaces/{spaceId}/content/pages），而不是页面 ID。
• 如果发现 https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> 这种包含组织 ID 的格式，不要“修正”它——它是有效的别名，在两种格式之间规范化会与 Git Sync 产生冲突。
• 如果尚不清楚空间 ID（例如新空间尚未创建），请使用 XSPACE_<KEY> 占位符。

文件组织：

• 不要在 SUMMARY.md 中重复引用同一个 Markdown 文件。
• 确保 SUMMARY.md 中的文件路径与实际文件位置一致。
• 重命名页面标题（其 # 标题或 title frontmatter）时，也要更新 SUMMARY.md 中该页面链接的文本——该文本会用于侧边栏导航、分页和相对链接文本，且不会自动更新。只有在 SUMMARY.md 条目有意使用带引号的链接标题覆盖形式（[Page main title](page.md "Page link title")）来显示不同标题时，才可跳过此操作。

配置：

• 使用 Git Sync 时，只能通过代码仓库管理 README.md。
• 移动或重命名文件后，请测试重定向。

自定义块：

• 始终正确关闭块（{% endtab %}、{% endhint %} 等）。
• 确保开始和结束标签完全一致。

Frontmatter：

• description: 的值包含 :、# 或其他 YAML 特殊字符时，务必加引号——未加引号的特殊字符会导致 Git Sync 静默失败，且不会显示任何错误消息。
• 但反向同步时不必强制加引号：GitBook 会根据其序列化器的选择，以任意 YAML 标量格式重新输出描述，包括折叠块（>-）。请验证 frontmatter 能否解析，而不是检查其书写格式（references/git-sync-serialisation.md）。
• Frontmatter 必须位于文件最顶部。

使用 Git Sync

GitBook 与 Git 同步后，变更会双向流动——Git 中的变更会更新 GitBook，而 GitBook 界面中的变更也会提交回 Git。合并冲突在 Git 中解决。

**最佳实践：**通过 Git 中的 SUMMARY.md 进行结构性变更；重要更新使用基于分支的工作流；检查 GitBook 自动生成的提交。

预览已推送的分支

以下双链接规则适用于通过变更请求推送的内容。如果你直接通过 Git 推送，对应的方式是查看提交状态：打开拉取请求／合并请求，或推送到已有此类请求的分支，GitBook 就会导入该分支，并发布一个状态，其中包含指向已渲染站点预览的链接。**每次推送文档变更时，都要主动把该链接提供给用户。**请从提交状态中读取链接，而不要自行构造 URL：修订 ID 会在导入时生成，无法从分支或 PR 推导出来，而且每次推送都会生成一个新的 ID，因此之前的链接会失效。请参阅 references/git-sync-previews.md，了解 GitHub 和 GitLab 命令，以及导入仍在进行时的处理方法。

选择 Git Sync 还是推送变更请求内容

当某个空间已配置 Git Sync，且你有（或可以获取）同步仓库的本地检出副本时，优先直接编辑文件并提交/推送——Git Sync 会将更改同步到 GitBook。即使在 MCP 会话中可以使用并已连接变更请求内容推送工具（例如 updateChangeRequestContent），这一原则也不变：工具只需调用一次，并不意味着可以绕过作为事实来源的 Git。即使 Agent 发现自己可以直接推送到 CR，也仍应先检查是否已设置并可访问 Git Sync。

以下情况可改用变更请求内容推送路径（MCP 的 updateChangeRequestContent 或类似工具，或 REST POST .../change-requests/<cr>/content 端点——请参阅 cr-create 技能）：

• 空间尚未配置 Git Sync（例如，全新空间仍在设置过程中）；
• 当前环境中没有可用的本地 Git 检出副本（无法访问同步仓库的文件系统）；或
• 更改范围较小且明确（一个错别字、一段文字、一个字段）——创建 CR 合乎比例，而完整的克隆/提交/推送流程不值得为此采用。

对于更大规模的更改——新建页面树、重写多个页面、迁移——优先使用 Git Sync，即使这意味着先暂停并确认仓库已在本地克隆。不要仅仅因为变更请求工具是第一个可用的工具，就默认使用它。

已锁定的 Git Sync 空间

当空间 API 显示 editMode: "locked"，且已配置/启用 gitSync 时，GitBook UI 会将 Git 视为该空间的事实来源。编辑前，读取这些字段（GET /spaces/{spaceId} 或等效接口），以便选择正确的操作路径。

已锁定且已同步空间的规则：

• 有同步仓库的检出副本时，优先推送 Git，用于内容和结构更改（与上述偏好相同）。无法获取检出副本时，仍可通过变更请求进行小范围的明确修改。
• Git Sync 已配置时，不要调用 POST /spaces/{spaceId}/git/import 或 …/git/export——这些端点会返回 400（Cannot use git API when space has a git sync configured）。由托管同步 Webhook 负责导入/导出。
• git push 后，等待 Webhook 导入完成。轮询空间的 Git Sync 状态（例如，GET /spaces/{spaceId}/git/info → operation.state / direction），不要假设已发布的网站会立即更新。分支预览的时间安排请参阅 references/git-sync-previews.md。
• 空间变量存放在 /.gitbook/vars.yaml（或 Library UI）中。无法通过变更请求内容操作设置这些变量（updateChangeRequestContent 不包含变量更改）。通过 Git Sync 推送 vars.yaml（或在 UI 中编辑）。
• **表达式：**已发布的 .md 会保留 <code class="expression">…</code> 作为源代码，不会内联解析后的值。要验证变量/表达式的渲染结果，请检查已发布的 HTML、网站预览或 GitBook UI，而不能只检查 .md 导出内容。
• **双向同步：**合并变更请求可能会将更改导出回 GitHub/GitLab 仓库。在进行更多本地提交前，请先拉取（或确保工作树干净），以免 Git Sync 导出覆盖 WIP。

涉及变更请求时，必须提供两个链接

如果此编辑的任何部分经过了变更请求（create_change_request / updateChangeRequestContent，或对应的 REST 操作），每次都必须回报以下两个链接，缺一不可，编辑才算完成——这是硬性规则，不是提醒你略过时扫一眼：

1. CR 差异/编辑器链接——变更请求对象中的 urls.app，由 create_change_request、updateChangeRequestContent 或 getChangeRequestById 返回。
2. 站点预览链接——来自 Site 对象的站点 URL（站点公开时使用 urls.published，否则使用 urls.preview），并在末尾追加 /~/changes/<number>/。此链接绝不会出现在变更请求响应中——需要单独查询——这也正是它容易被遗忘的原因。每次都要解析，不要等到想起来时才处理。如果没有 ~/changes/ 这一段，链接就不是变更请求的预览——它显示的是站点当前内容，看起来可能没问题，实际却是错的。

无论内容是由哪个技能（本技能或 configure-site）推送，也无论使用何种传输方式（MCP 或 REST），都适用此规则。完整说明和 REST 解析步骤请参阅 cr-create 技能中的“提供预览链接”。MCP 对应流程（GitBook MCP 没有一个现成的调用可以直接“提供预览链接”）：

1. 解析空间所属的组织——invoke_operation("getSpaceById", {path:{spaceId}}) → .organization（如果已知组织 ID，则跳过）。
2. 查找空间所属的站点——使用 list_sites / get_site_structure，或检查每个站点的 site-spaces，匹配 .space.id。
3. invoke_operation("getSiteById", {path:{organizationId, siteId}}) → .urls.published（站点上线后），否则使用 .urls.preview。追加 /~/changes/<number>/，并去掉 API 返回的末尾斜杠。

如果空间未关联到任何已发布的站点，请明确说明，并且只提供差异链接——不要默默省略预览链接而不作解释。

过去确实发生过这种疏漏：编辑已推送并合并，却只回报了差异链接；直到有人直接询问，预览链接才被补上。请将上述双链接清单视为必须严格执行的规定。

参考文件

需要深入了解时，按需加载以下文件：

• references/blocks.md — GitBook 所有块类型的完整语法和示例：选项卡、步骤条、提示框、可展开内容、分栏、更新、卡片、嵌入内容、文件、按钮、图标、可复用内容和 OpenAPI 块。编写复杂页面，或快速参考内容不足以满足需求时，请加载此文件。
• references/frontmatter.md — 所有 frontmatter 字段及其说明、YAML 引号规则、封面图片、自适应内容（if:）以及变量和表达式的深入说明。配置页面布局、封面、条件可见性或变量时，请加载此文件。
• references/markdown.md — 标准 Markdown、带标题的代码块、数学公式/TeX、Mermaid 图表类型和示例，以及 SVG 处理注意事项。处理图表、数学公式或 SVG 资源时，请加载此文件。
• references/configuration.md — .gitbook.yaml 选项、.gitbook/ 目录结构（资源、包含文件、变量、标签）以及完整的 SUMMARY.md 语法规则。设置空间、添加重定向或编写/编辑 SUMMARY.md 时，请加载此文件。
• references/git-sync-serialisation.md — GitBook 将空间导出回代码库时会重写的内容：description: 标量样式、跨空间链接 URL 格式、块的重新序列化，以及只需检查有效性而非格式的规则。Git Sync 差异中出现无人手动修改的内容时，或在编写检查文档 frontmatter 或链接的校验步骤之前，请加载此文件。
• references/git-sync-previews.md — 获取通过 Git Sync 推送的分支的预览链接：在 GitHub 和 GitLab 上查看 GitBook 提交状态、区分站点预览与编辑器差异，以及处理仍在导入中的内容。当你向存在未关闭拉取/合并请求的分支推送文档更改时，请加载此文件。