> 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/write-docs.md).

# 编写和编辑文档

在与 Git 同步的仓库、IDE 或任何文本编辑器中编写、创作、编辑并格式化 GitBook 文档页面。只要任务涉及创建或编辑 GitBook Markdown 页面、编写或更新

#### 何时使用此技能

在通过以下方式处理 GitBook 文档时使用此技能：

* 与 Git 同步的仓库（GitHub、GitLab）
* 本地 Markdown 编辑器
* IDE 集成
* 任何你是在把 GitBook 内容当作文件而不是通过 GitBook 界面进行编辑的环境

#### 快速参考

**GitBook 内容结构**

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

* **页面** 是构成你的文档的单独 Markdown 文件
* **空间** 是组织成一个文档站点的页面集合
* **合集** 是空间的分组

**文件结构：**

```
/
  .gitbook/
    assets/              # GitBook 管理的图片和文件
    includes/            # 可复用内容块
    vars.yaml            # 空间级变量
  .gitbook.yaml          # 配置
  README.md              # 首页
  SUMMARY.md             # 目录
  getting-started/
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md
```

**Frontmatter 字段（快速形式）：**

```markdown
---
description: "用于 SEO 的页面描述"
icon: book-open
hidden: true
vars:
  page_variable: value
layout:
  width: default  # 或 '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`）。获取 `<spaceId>` 来自 `GET /orgs/{orgId}/spaces` 和 `<path>` 来自页面的 `path` 字段，在 `GET /spaces/{spaceId}/content/pages`中。要为目标空间尚不存在的新站点搭建脚手架？使用 `XSPACE_<KEY>` 占位标记； `configure-site` 会在创建后解析它们。完整示例： `references/markdown.md`.
* 已移动/重命名的页面仍可正常工作——GitBook 会自动从旧路径创建重定向。

**关键提醒：**

* 处理现有内容时先阅读 SUMMARY.md
* 在本地编辑后在 GitBook 中测试
* 让 SUMMARY.md 与你的文件结构和页面标题保持同步
* OpenAPI 规范必须通过 UI、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>` ——它是有效别名，而在这两种形式之间做规范化会让 Git Sync 产生不必要的变更。
* 使用 `XSPACE_<KEY>` 当尚未知晓空间 ID 时使用占位标记（新空间，尚未创建）。

**文件组织：**

* 不要在 SUMMARY.md 中两次引用同一个 Markdown 文件
* 保持 SUMMARY.md 与实际文件位置之间的路径一致
* 当你重命名页面的标题（它的 `#` 标题或 `标题` frontmatter），也请同步更新 SUMMARY.md 中该页面的链接文本——它会驱动侧边栏导航、分页和相对链接文本，而且不会自动更新。只有在 SUMMARY.md 条目刻意使用了带引号的链接标题覆盖（`[页面主标题](page.md "页面链接标题")`）以有意显示不同内容。

**配置：**

* 使用 Git Sync 时，只通过你的仓库管理 README.md
* 移动或重命名文件后测试重定向

**自定义块：**

* 始终正确关闭块（`{% endtab %}`, `{% endhint %}`等）
* 精确匹配开始和结束标签

**Frontmatter：**

* 始终给 `description:` 值加引号 `:`, `#`，或其他对 YAML 有特殊意义的字符——未加引号的特殊字符会导致 Git Sync 静默失败，且不会显示错误消息
* 但返回时不要强制要求保留引号：GitBook 会按其序列化器选择的 YAML 标量样式重新输出 description，包括折叠块（`>-`）。验证 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 作为事实来源的理由。发现它的代理 *可以* 直接推送到 CR 中，但在这样做之前仍应检查 Git Sync 是否已设置并可访问。

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

* 该空间尚未配置 Git Sync（例如一个全新的空间仍在设置过程中），
* 当前环境中没有可用的本地 Git 检出（无法访问同步仓库的文件系统），或者
* 更改很小且有针对性（拼写错误、一段文字、一个字段）——开启 CR 是合适的，而完整的克隆/提交/推送流程为此并不值得。

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

**一旦涉及变更请求，两个链接就是强制要求**

如果这次编辑的任何部分经过了变更请求（`create_change_request` / `updateChangeRequestContent`，或 REST 对应接口）， **那么在以下两项都回报之前，编辑都不算完成——每一次都必须如此，这是硬性规则，不是可以略过的提醒：**

1. **CR 差异/编辑器链接** — `urls.app` 来自变更请求对象，由 `create_change_request`, `updateChangeRequestContent`返回，或 `getChangeRequestById`.
2. **站点预览链接** — 来自 **Site** 对象的站点 URL（`urls.published` 当站点公开时，否则为 `urls.preview`）并附加 **`/~/changes/<number>/` 。**&#x8FD9;从来不是变更请求响应的一部分——它需要单独查找——而这正是它经常被忘记的原因。每次都要解析它，而不是只在想起来时才做。 **如果没有 `~/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 返回的末尾斜杠。

如果该空间尚未挂到任何已发布站点，请直接说明，并只给出 diff 链接——不要在不解释的情况下悄悄省略预览链接。

这在实践中已经静默失败过：某次编辑被推送并合并时只报告了 diff 链接，而预览链接直到有人直接询问时才出现。请把上面的双链接清单当作字面要求。

#### 参考文件

当任务需要更深入细节时按需加载这些文件：

* `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/` 目录结构（assets、includes、vars、tags）以及 SUMMARY.md 语法规则的完整说明。 **在设置空间、添加重定向或编写/编辑 SUMMARY.md 时加载。**
* `references/git-sync-serialisation.md` — GitBook 将空间导出回仓库时会重写的内容： `description:` 标量样式、跨空间链接 URL 形式、块的重新序列化，以及你只校验有效性而不校验形式的规则。 **当 Git Sync diff 包含没有人手动做出的变更时，或者在编写任何验证文档 frontmatter 或链接的检查/构建步骤之前加载。**
* `references/git-sync-previews.md` — 通过 Git Sync 推送分支时如何获取预览链接：读取 GitHub 和 GitLab 上的 GitBook 提交状态，把站点预览与编辑器 diff 区分开来，以及处理仍在运行的导入。 **每当你把文档变更推送到一个已打开拉取/合并请求的分支时都要加载。**


---

# 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/write-docs.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.