write-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此 Skill

Use this skill when working with GitBook documentation through:

Git-synced repositories (GitHub, GitLab)
Local markdown editors
IDE integrations
Any environment where you're editing GitBook content as files rather than through the GitBook UI

在以下方式中处理 GitBook 文档时使用此 skill：

Git 同步仓库（GitHub、GitLab）
本地 Markdown 编辑器
IDE 集成
任何以文件形式而非通过 GitBook UI 编辑 GitBook 内容的环境

Quick Reference

快速参考

GitBook Content Structure

GitBook 内容结构

GitBook organizes content through pages, spaces, and collections:

Pages are individual markdown files that make up your documentation
Spaces are collections of pages organized into a documentation site
Collections are groups of spaces

File structure:

/
  .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 fields (quick form):

markdown

---
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
---

Variables and expressions:

Space variables:
```
/.gitbook/vars.yaml
```
Page variables: Frontmatter
```
vars:
```

Expression syntax:

<code class="expression">space.vars.variableName</code>

Most common custom blocks:

```
{% tabs %}...{% endtabs %}
```
— for alternatives
```
{% hint style="..." %}...{% endhint %}
```
— callouts (info/warning/danger/success)
```
{% stepper %}...{% endstepper %}
```
— sequential steps
```
<details>...<summary>...</details>
```
— expandable content

Links:

External:
```
[text](https://example.com)
```

Relative (same space):

[text](page.md)

[text](../folder/page.md)

Cross-space (different space):
```
[text](https://app.gitbook.com/s/<spaceId>/<path>)
```
— relative paths never cross space boundaries, and
```
/spaces/<id>/pages/<id>
```
is not a valid link form. The org-qualified alias
```
https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path>
```
resolves the same way — write the short form, but don't rewrite or lint against either (
```
references/git-sync-serialisation.md
```
). Get
```
<spaceId>
```
from
```
GET /orgs/{orgId}/spaces
```
and
```
<path>
```
from a page's
```
path
```
field in
```
GET /spaces/{spaceId}/content/pages
```
. Scaffolding a new site where the target space doesn't exist yet? Use
```
XSPACE_<KEY>
```
sentinels;
```
configure-site
```
resolves them after creation. Full examples:
```
references/markdown.md
```
.
Moved/renamed pages keep working — GitBook auto-creates a redirect from the old path.

Key reminders:

Read SUMMARY.md first when working with existing content
Test in GitBook after editing locally
Keep SUMMARY.md synchronized with your file structure and page titles
OpenAPI specs must be uploaded via the UI, API, MCP, or CLI, not embedded in markdown

GitBook 通过 Pages、Spaces 和 Collections 组织内容：

Pages 是构成文档的各个 Markdown 文件
Spaces 是组织为文档站点的页面集合
Collections 是 Spaces 的分组

文件结构：

/
  .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 字段（快速模板）：

markdown

---
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
---

变量与表达式：

Space 变量：
```
/.gitbook/vars.yaml
```
Page 变量：Frontmatter
```
vars:
```

表达式语法：

<code class="expression">space.vars.variableName</code>

最常用的自定义 block：

```
{% tabs %}...{% endtabs %}
```
— 用于展示备选方案
```
{% hint style="..." %}...{% endhint %}
```
— 标注框（info/warning/danger/success）
```
{% stepper %}...{% endstepper %}
```
— 顺序步骤
```
<details>...<summary>...</details>
```
— 可折叠内容

链接：

外部链接：
```
[text](https://example.com)
```

相对链接（同一 Space 内）：

[text](page.md)

、

[text](../folder/page.md)

跨 Space 链接（不同 Space）：
```
[text](https://app.gitbook.com/s/<spaceId>/<path>)
```
— 相对路径无法跨越 Space 边界，且
```
/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>
```
。如果要搭建新站点，但目标 Space 尚不存在，请使用
```
XSPACE_<KEY>
```
哨兵值；
```
configure-site
```
会在创建后解析它们。完整示例见
```
references/markdown.md
```
。
移动或重命名后的页面仍可继续使用——GitBook 会自动基于旧路径创建重定向。

关键提醒：

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

When to Use Which Block

何时使用哪种 Block

Need	Use	Why
Sequential, ordered instructions	`{% stepper %}`	Clear step progression
Alternative options (languages, platforms)	`{% tabs %}`	User chooses without page clutter
Optional or detailed information	`<details>`	Keeps page scannable
Important warnings or tips	`{% hint %}`	Colored callout (info/warning/danger/success)
Side-by-side comparisons	`{% columns %}`	Parallel layout (max 2 columns)
Timeline or changelog	`{% updates %}`	Dated entries with tag filtering
Visual navigation cards	`<table data-view="cards">`	Clickable card grid
Downloadable files	`{% file %}`	File with caption
Call-to-action links	`<a class="button">`	Primary or secondary button
Reusable content across pages	`{% include %}`	Single source of truth
Dynamic content	`<code class="expression">`	Renders variable values

Variable scope:

If variable is...	Define in...	Access with...
Used across multiple pages	`/.gitbook/vars.yaml`	`space.vars.variableName`
Specific to one page	Frontmatter `vars:`	`page.vars.variableName`

使用场景	使用方式	原因
需要顺序、分步的说明	`{% stepper %}`	步骤递进清晰
备选方案（语言、平台）	`{% tabs %}`	用户可自主选择，且不会让页面显得杂乱
可选信息或详细信息	`<details>`	保持页面易于浏览
重要警告或提示	`{% hint %}`	彩色标注框（info/warning/danger/success）
并排比较	`{% 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`

Working with Existing Content

处理已有内容

Read SUMMARY.md first — complete table of contents and file hierarchy
If no SUMMARY.md — browse the directory structure directly
Check .gitbook.yaml — root path, custom README/SUMMARY locations, redirects
Check .gitbook/assets/ — uploaded images and files
Check .gitbook/vars.yaml — space-level variables

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

Common Pitfalls

常见陷阱

Cross-space links:

Don't use relative paths to link to a page in a different space — they won't resolve.
Don't use
```
/spaces/<spaceId>/pages/<pageId>
```
— that's not a valid GitBook link form.

Use

https://app.gitbook.com/s/<spaceId>/<path>

instead, where

<path>

is the target page's

path

field (from

GET /spaces/{spaceId}/content/pages

), not its page ID.

Don't "fix" the org-qualified form
```
https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path>
```
when you find it — it's a valid alias, and normalising between the two forms churns against Git Sync.
Use
```
XSPACE_<KEY>
```
sentinels when space IDs aren't known yet (new space, not yet created).

File organization:

Don't reference the same markdown file twice in SUMMARY.md
Keep file paths consistent between SUMMARY.md and actual file locations
When you rename a page's title (its
```
#
```
heading or
```
title
```
frontmatter), also update SUMMARY.md's link text for that page — it drives the sidebar nav, pagination, and relative link text, and won't update itself. Skip this only if the SUMMARY.md entry intentionally uses the quoted link-title override (
```
[Page main title](page.md "Page link title")
```
) to show something different on purpose.

Configuration:

When using Git Sync, manage README.md only through your repository
Test redirects after moving or renaming files

Custom blocks:

Always close blocks properly (
```
{% endtab %}
```
,
```
{% endhint %}
```
, etc.)
Match opening and closing tags exactly

Frontmatter:

Always quote
```
description:
```
values containing
```
:
```
,
```
#
```
, or other YAML-significant characters — unquoted special characters cause silent Git Sync failures with no error message
But don't require quotes on the way back out: GitBook re-emits descriptions in whatever YAML scalar style its serialiser picks, including folded blocks (
```
>-
```
). Validate that frontmatter parses, not how it's written (
```
references/git-sync-serialisation.md
```
)
Frontmatter must be at the very top of the file

跨 Space 链接：

不要使用相对路径链接到不同 Space 中的页面——这样无法解析。
不要使用
```
/spaces/<spaceId>/pages/<pageId>
```
——那不是有效的 GitBook 链接形式。

改用

https://app.gitbook.com/s/<spaceId>/<path>

，其中

<path>

必须是目标页面的

path

字段（来自

GET /spaces/{spaceId}/content/pages

），而不是 page ID。

不要在发现
```
https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path>
```
时“修复”带组织限定符的形式——它是有效的别名，在两种形式之间做规范化会与 Git Sync 产生无意义的变动。
Space ID 尚不可知时（新 Space 尚未创建），使用
```
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
移动或重命名文件后，测试重定向

自定义 block：

始终正确闭合 block（
```
{% endtab %}
```
、
```
{% endhint %}
```
等）
开始和结束标签必须完全匹配

Frontmatter：

始终为包含
```
:
```
、
```
#
```
或其他 YAML 显著字符的
```
description:
```
值加引号——未加引号的特殊字符会导致 Git Sync 静默失败，且不显示错误消息
但反向写回时不要要求必须加引号：GitBook 会使用其序列化器所选的 YAML 标量样式重新输出 description，包括折叠块（
```
>-
```
）。应验证 Frontmatter 能否解析，而不是验证其书写形式（
```
references/git-sync-serialisation.md
```
）
Frontmatter 必须位于文件最顶部

Working with Git Sync

使用 Git Sync

When GitBook is synced with Git, changes flow in both directions — Git changes update GitBook, and GitBook UI changes commit back to Git. Merge conflicts are resolved in Git.

Best practices: make structural changes via SUMMARY.md in Git; use branch-based workflows for significant updates; review auto-generated commits from GitBook.

当 GitBook 与 Git 同步时，更改会双向流转——Git 中的更改会更新 GitBook，GitBook UI 中的更改也会提交回 Git。合并冲突在 Git 中解决。

**最佳实践：**通过在 Git 中修改 SUMMARY.md 完成结构变更；对重大更新采用基于分支的工作流；审查 GitBook 自动生成的提交。

Previewing a pushed branch

预览已推送的分支

The two-link rule below covers content pushed through a change request. When you push through Git instead, the equivalent is the commit status: opening a pull/merge request — or pushing to a branch that already has one — makes GitBook import that branch and post a status linking a preview of the rendered site. Give the user that link whenever you push docs changes, without being asked. Read it off the commit status rather than building a URL: the revision id is minted at import time and can't be derived from the branch or the PR, and every push mints a new one, so an earlier link goes stale. See

references/git-sync-previews.md

for the GitHub and GitLab commands and what to do while the import is still running.

下面的双链接规则适用于通过 change request 推送的内容。如果改为通过 Git 推送，相应的信息是 commit status：开启 pull/merge request——或向已存在此类 request 的 branch 推送——会让 GitBook 导入该 branch，并发布一条指向渲染后站点预览的 status。每当推送文档更改时，都应主动向用户提供该链接，无需等待询问。应从 commit status 中读取该链接，而不要自行构建 URL：revision ID 会在导入时生成，无法从 branch 或 PR 推导；每次 push 都会生成新的 revision ID，因此旧链接会失效。有关 GitHub 和 GitLab 命令，以及导入仍在运行时该怎么办，请参阅

references/git-sync-previews.md

。

Choosing Git Sync vs. a change-request content push

在 Git Sync 与变更请求内容推送之间选择

When a space has Git Sync configured and you have (or can get) a local checkout of the synced repo, prefer editing the files directly and committing/pushing — Git Sync propagates the change to GitBook. This holds even in an MCP session where a change-request content-push tool (e.g.

updateChangeRequestContent

) is available and connected: the tool being one call away isn't a reason to bypass Git as the source of truth. An agent that discovers it can push straight into a CR should still check whether Git Sync is set up and reachable before doing so.

Reach for the change-request content-push path instead (MCP's

updateChangeRequestContent

or similar, or the REST

POST .../change-requests/<cr>/content

endpoint — see the

cr-create

skill) when:

the space has no Git Sync configured yet (e.g. a brand-new space still mid-setup),
there's no local Git checkout available in the current environment (no filesystem access to the synced repo), or
the change is small and targeted (a typo, one paragraph, one field) — opening a CR is proportionate, and a full clone/commit/push cycle isn't worth it for that.

For anything larger — a new page tree, a multi-page rewrite, a migration — prefer Git Sync, even if that means pausing to confirm the repo is cloned locally first. Don't default to the change-request tool just because it's the first one that worked.

当 Space 已配置 Git Sync，且你拥有（或可获得）同步仓库的本地 checkout 时，优先直接编辑文件并 commit/push——Git Sync 会将更改传播到 GitBook。即使在 MCP session 中存在可用且已连接的 change-request content-push 工具（例如

updateChangeRequestContent

），也不能仅因为该工具近在咫尺就绕过 Git 这一事实来源。即使某个 Agent 发现自己可以直接 push 到 CR，也仍应先检查 Git Sync 是否已配置且可访问。

仅在以下情况下改用 change-request content-push 路径（MCP 的

updateChangeRequestContent

或类似工具，或 REST

POST .../change-requests/<cr>/content

接口——参见

cr-create

skill）：

Space 尚未配置 Git Sync（例如仍处于设置阶段的新 Space）

当前环境中没有同步仓库的本地 Git checkout（即无法访问该仓库的文件系统）
更改较小且目标明确（一个错别字、一个段落或一个字段），开启 CR 与改动规模相称，完整的 clone/commit/push 流程并不值得。

对于规模更大的工作——新的页面树、多页面重写或迁移——应优先使用 Git Sync，即使这意味着需要暂停操作并先确认仓库已在本地 clone。不要仅仅因为 change-request 工具最先调用成功，就默认使用它。

Locked Git Sync spaces

锁定的 Git Sync Space

When the space API shows

editMode: "locked"

and

gitSync

is configured/active, the GitBook UI treats Git as the source of truth for that space. Before editing, read those fields (

GET /spaces/{spaceId}

or equivalent) so you pick the right path.

Rules for locked + synced spaces:

Prefer git push for content and structure when you have a checkout of the synced repo (same preference as above). Change requests still work for small targeted edits when a checkout is unavailable.
Do not call
```
POST /spaces/{spaceId}/git/import
```
or
```
…/git/export
```
when Git Sync is already configured — those endpoints return 400 (
```
Cannot use git API when space has a git sync configured
```
). The managed sync webhook handles import/export.
After
git push
, wait for the webhook import to finish. Poll space Git Sync status (e.g.
```
GET /spaces/{spaceId}/git/info
```
→
```
operation.state
```
/
```
direction
```
) rather than assuming the published site updated instantly. See
```
references/git-sync-previews.md
```
for branch-preview timing.
Space variables live in
```
/.gitbook/vars.yaml
```
(or the Library UI). They are not settable via change-request content ops (
```
updateChangeRequestContent
```
has no variables change). Push
```
vars.yaml
```
through Git Sync (or edit in the UI).
Expressions: published
```
.md
```
keeps
```
<code class="expression">…</code>
```
as source and does not inline resolved values. To verify variables/expressions rendered, check published HTML, the site preview, or the GitBook UI — not the
```
.md
```
export alone.
Bidirectional sync: merging a change request can export back to the GitHub/GitLab repo. Pull (or keep a clean working tree) before more local commits so Git Sync export does not clobber WIP.

当 Space API 显示

editMode: "locked"

且

gitSync

已配置或启用时，GitBook UI 会将 Git 视为该 Space 的事实来源。编辑前，先读取这些字段（

GET /spaces/{spaceId}

或等价接口），以选择正确的处理路径。

锁定且已同步 Space 的规则：

优先使用 git push 处理内容和结构（如果拥有同步仓库的 checkout）。没有 checkout 时，小范围的目标性编辑仍可使用 change request。

Git Sync 已配置时，不要调用
```
POST /spaces/{spaceId}/git/import
```
或
```
…/git/export
```
——这些接口会返回 400（
```
Cannot use git API when space has a git sync configured
```
）。托管的 sync webhook 会处理 import/export。
执行 git push 后，等待 webhook import 完成。轮询 Space 的 Git Sync 状态（例如
```
GET /spaces/{spaceId}/git/info
```
→
```
operation.state
```
/
```
direction
```
），不要假定已发布的站点会立即更新。有关 branch 预览的时序，请参阅
```
references/git-sync-previews.md
```
。
Space 变量位于
```
/.gitbook/vars.yaml
```
（或 Library UI），无法通过 change-request content 操作进行设置（
```
updateChangeRequestContent
```
没有 variables change）。应通过 Git Sync 推送
```
vars.yaml
```
（或在 UI 中编辑）。
表达式：已发布的
.md
会将
<code class="expression">…</code>
保留为源代码，且不会内联解析后的值。要验证变量或表达式的渲染结果，应检查已发布的 HTML、站点预览或 GitBook UI，而不能只检查
```
.md
```
导出。
**双向同步：**合并 change request 时，内容可能会导出回 GitHub/GitLab 仓库。在进行更多本地 commit 前先执行 pull（或保持工作树干净），以免 Git Sync export 覆盖 WIP。

Two links are mandatory whenever a change request is involved

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

If any part of this edit went through a change request (

create_change_request

updateChangeRequestContent

, or the REST equivalents), the edit is not done until both of the following have been reported back, every single time — this is a hard rule, not a reminder to skim past:

The CR diff/editor link —

urls.app

on the change-request object, returned by

create_change_request

updateChangeRequestContent

, or

getChangeRequestById

The site preview link — the site URL from the Site object (
```
urls.published
```
when the site is public, else
```
urls.preview
```
) with /~/changes/<number>/
appended. This is never part of the change-request response — it requires a separate lookup — which is exactly why it's the one that gets forgotten. Resolve it every time, not just when it comes to mind. Without the
~/changes/
segment the link is not a preview of the change request — it renders the site's current content, so it will look plausible and be wrong.

This applies no matter which skill pushed the content (this skill or

configure-site

) and no matter the transport (MCP or REST). See the

cr-create

skill's "Surfacing the preview link" for the full write-up and the REST resolution steps. MCP equivalent (GitBook MCP has no single ready-made "give me the preview link" call):

Resolve the space's organization —
```
invoke_operation("getSpaceById", {path:{spaceId}})
```
→
```
.organization
```
(skip if you already have the org ID).
Find which site the space belongs to —
```
list_sites
```
/
```
get_site_structure
```
, or check each site's site-spaces for a match on
```
.space.id
```
.

invoke_operation("getSiteById", {path:{organizationId, siteId}})

→

.urls.published

(once the site is live), else

.urls.preview

. Append

/~/changes/<number>/

, stripping the trailing slash the API returns.

If the space isn't attached to any published site, say so plainly and give only the diff link — don't quietly drop the preview line without explanation.

This has already failed silently in practice: an edit was pushed and merged with only the diff link reported, and the preview link only surfaced when a person asked for it directly. Treat the two-link checklist above as literal.

如果此次编辑有任何部分通过 change request 完成（

create_change_request

updateChangeRequestContent

，或 REST 等价接口），那么每次都必须回报以下两项，否则编辑尚未完成——这是硬性规则，不是可以略过的提醒：

CR diff/editor 链接 — change-request 对象上的

urls.app

，由

create_change_request

、

updateChangeRequestContent

或

getChangeRequestById

返回。

站点预览链接 — 来自 Site 对象（站点为公开时使用
```
urls.published
```
，否则使用
```
urls.preview
```
）的站点 URL，并附加 /~/changes/<number>/
。它绝不会包含在 change-request 响应中——必须另行查询，而人们正是因此经常忘记它。每次都要解析该链接，不能只在想起来时才处理。缺少
~/changes/
路径段时，该链接就不是 change request 的预览——它会呈现站点的当前内容，看起来合理但实际错误。

无论由哪个 skill 推送内容（此 skill 或

configure-site

），也无论使用 MCP 还是 REST，都适用此项要求。请参阅

cr-create

skill 中的“Surfacing the preview link”，了解完整说明和 REST 解析步骤。MCP 等价操作（GitBook MCP 没有单一现成的“给我预览链接”调用）：

解析 Space 所属的组织——
```
invoke_operation("getSpaceById", {path:{spaceId}})
```
→
```
.organization
```
（如果已经拥有 org ID，则可跳过）。
查找 Space 所属的站点——使用
```
list_sites
```
/
```
get_site_structure
```
，或检查每个站点的 site-spaces，查找
```
.space.id
```
匹配项。

invoke_operation("getSiteById", {path:{organizationId, siteId}})

→

.urls.published

（站点上线后），否则使用

.urls.preview

。附加

/~/changes/<number>/

，并移除 API 返回的末尾斜杠。

如果 Space 未附加到任何已发布的站点，应明确说明这一点，并且只提供 diff 链接——不要在不作解释的情况下悄悄省略预览链接。

实践中这种情况已经静默失败过：编辑已 push 并 merge，却只报告了 diff link，直到有人直接询问才提供 preview link。请严格按上述双链接清单执行。

Reference files

参考文件

Load these on demand when the task requires deeper detail:

```
references/blocks.md
```
— full syntax and worked examples for every GitBook block type: tabs, steppers, hints, expandable, columns, updates, cards, embeds, files, buttons, icons, reusable content, and OpenAPI blocks. Load when authoring non-trivial pages or when the quick-reference above isn't enough.
```
references/frontmatter.md
```
— all frontmatter fields with descriptions, YAML quoting rules, cover images, adaptive content (
```
if:
```
), and the variables/expressions deep-dive. Load when configuring page layout, covers, conditional visibility, or variables.
```
references/markdown.md
```
— standard markdown, code blocks with titles, math/TeX, Mermaid diagram types and examples, and SVG handling quirks. Load when working with diagrams, math, or SVG assets.
```
references/configuration.md
```
—
```
.gitbook.yaml
```
options, the
```
.gitbook/
```
directory structure (assets, includes, vars, tags), and SUMMARY.md grammar rules in full. Load when setting up a space, adding redirects, or authoring/editing SUMMARY.md.
```
references/git-sync-serialisation.md
```
— what GitBook rewrites when it exports a space back to the repo:
```
description:
```
scalar style, cross-space link URL form, block re-serialisation, and the rule that you lint for validity rather than for form. Load when a Git Sync diff contains changes nobody made by hand, or before writing any check or build step that validates docs frontmatter or links.
```
references/git-sync-previews.md
```
— getting a preview link for a branch pushed through Git Sync: reading the GitBook commit status on GitHub and GitLab, telling the site preview from the editor diff, and handling an import that's still running. Load whenever you push docs changes to a branch with a pull/merge request open.

仅在任务需要更深入的信息时按需加载以下文件：

```
references/blocks.md
```
— 涵盖所有 GitBook block 类型的完整语法和实例：tabs、steppers、hints、expandable、columns、updates、cards、embeds、files、buttons、icons、reusable content 和 OpenAPI blocks。在编写非简单页面，或上述快速参考不够用时加载。
```
references/frontmatter.md
```
— 包含所有 Frontmatter 字段及其说明、YAML 引号规则、封面图片、自适应内容（
```
if:
```
），以及 variables/expressions 深入说明。在配置页面布局、封面、条件可见性或变量时加载。
```
references/markdown.md
```
— 标准 Markdown、带标题的代码块、math/TeX、Mermaid 图表类型与示例，以及 SVG 处理 quirks。在处理图表、数学公式或 SVG 资源时加载。
```
references/configuration.md
```
—
```
.gitbook.yaml
```
选项、
```
.gitbook/
```
目录结构（assets、includes、vars、tags），以及完整的 SUMMARY.md 语法规则。在设置 Space、添加重定向或编写/编辑 SUMMARY.md 时加载。
```
references/git-sync-serialisation.md
```
— GitBook 将 Space 导出回仓库时会重写的内容：
```
description:
```
标量样式、跨 Space 链接 URL 形式、block 重新序列化，以及应验证有效性而非格式的规则。当 Git Sync diff 包含无人手动做出的更改时，或在编写任何用于验证文档 Frontmatter 或链接的检查或构建步骤之前加载。
```
references/git-sync-previews.md
```
— 获取通过 Git Sync 推送的 branch 的预览链接：读取 GitHub 和 GitLab 上的 GitBook commit status、区分站点预览与 editor diff，以及处理仍在运行的 import。每当向已开启 pull/merge request 的 branch 推送文档更改时加载。