configure-site

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure GitBook Site

配置GitBook站点

A skill for creating and maintaining entire GitBook documentation sites. Where

write-docs

covers what goes inside a single page, this skill covers everything around the pages: structure design, repo scaffolding, the GitBook API, and branding. Use the two skills together — this one calls into

write-docs

whenever it needs to generate or edit page content.

一款用于创建和维护完整GitBook文档站点的技能。

write-docs

技能负责单个页面的内容编写，而本技能负责页面之外的所有工作：结构设计、仓库搭建、GitBook API调用以及品牌化配置。可将这两个技能配合使用——当需要生成或编辑页面内容时，本技能会调用

write-docs

。

How you can talk to GitBook

与GitBook交互的方式

There's more than one way to drive GitBook — GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer MCP first: if GitBook MCP tools are already connected, use them for anything they cover (creating/configuring sites, opening change requests, drafting and editing content, restructuring docs) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

"MCP first" is about transport, not about bypassing Git Sync for content. MCP exposes a change-request content-push tool (

updateChangeRequestContent

) that's tempting to reach for anytime it's connected — but for spaces that already have Git Sync configured, pushing content by editing files in the local repo and letting Git Sync carry it to GitBook is still the preferred path for anything beyond a small, targeted edit. Use the change-request push (MCP or REST) instead when the space isn't Git-synced, there's no local checkout available in the environment, or the edit is small enough that opening a CR is proportionate. See

write-docs

's "Choosing Git Sync vs. a change-request content push" for the full rule — it applies here too.

The steps in this skill are described as outcomes ("list the orgs", "create the site", "add a section") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints, request bodies, and expected responses for each step are in

references/api-cheatsheet.md

GitBook MCP — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (a full site build, ongoing restructuring — not a one-off tweak), offer to set it up:
```
claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp
```
(then
```
/mcp
```
to complete OAuth sign-in — or append
```
--header "Authorization: Bearer $GITBOOK_TOKEN"
```
to skip the browser flow). Codex equivalent:
```
codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp
```
. Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
REST API (
```
https://api.gitbook.com/v1
```
) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs
```
GITBOOK_TOKEN
```
as a bearer header on every request.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer token for both. MCP additionally supports OAuth as a friendlier alternative to pasting a token.

If you end up needing a token (REST API path, or MCP without OAuth), check for it at the start of the session:

bash

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

GITBOOK_TOKEN

is not set, ask the user directly:

Tell them they need a GitBook personal access token. Direct them to https://app.gitbook.com/account/developer to create one.
Ask them to paste the token into the conversation. Immediately export it as an environment variable (
```
export GITBOOK_TOKEN=<pasted value>
```
) and don't repeat it back in your response.
Do not proceed with any API calls until the token is confirmed present in the environment.

Never write the token to a file, never echo it back in a response, never commit it.

驱动GitBook的方式不止一种——GitBook的MCP服务器和REST API。请确认当前会话中可用的方式，并优先选择MCP：如果已连接GitBook MCP工具，使用它们完成所有支持的操作（创建/配置站点、发起变更请求、起草和编辑内容、重构文档），而非直接调用API。无需运行检测脚本——你已了解自身可用的工具/MCP连接，直接使用即可。

**“优先使用MCP”指的是传输方式，而非绕过Git Sync处理内容。**MCP提供了变更请求内容推送工具（

updateChangeRequestContent

），只要已连接就很容易想用它处理所有内容，但对于已配置Git Sync的空间，除了小范围针对性编辑外，仍优先选择通过编辑本地仓库文件，再由Git Sync同步到GitBook的方式推送内容。当空间未配置Git Sync、环境中无本地检出版本，或编辑范围小到发起变更请求更为合适时，才使用变更请求推送（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不支持某些操作时的备选方案。每个请求都需要在请求头中携带
```
GITBOOK_TOKEN
```
作为Bearer令牌。

从https://app.gitbook.com/account/developer获取的个人访问令牌可同时作为两种方式的Bearer令牌。MCP还支持OAuth作为替代粘贴令牌的更友好方式。

若需要令牌（REST API方式，或未使用OAuth的MCP方式），请在会话开始时检查：

bash

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

若

GITBOOK_TOKEN

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

告知用户需要GitBook个人访问令牌，引导他们前往**https://app.gitbook.com/account/developer**创建。
请求用户将令牌粘贴到对话中，立即将其导出为环境变量（
```
export GITBOOK_TOKEN=<粘贴的值>
```
），且不要在回复中重复令牌内容。
确认令牌已存在于环境变量中后，再进行任何API调用。

切勿将令牌写入文件、在回复中回显或提交到仓库。

The fundamental constraint

核心限制

The most important thing to internalize before doing anything: GitBook can do almost everything except set up Git Sync, regardless of transport. Authorizing GitHub/GitLab, picking the repository, choosing the branch, setting the project directory for monorepo layouts, and choosing the initial sync direction are all UI-only operations — both the REST API and MCP (which wraps it) only let you read the resulting Git Sync state, never set it up.

That means the cleanest end-to-end flow is always:

Claude scaffolds a Git repo locally (and, when tooling permits, the remote)
Claude creates the site, sections, and any empty spaces it can
The user does a short, well-scripted UI step in GitBook to wire each space to its directory in the repo
Claude applies branding/customization

The user's role in step 3 is unavoidable but should never be a surprise — generate clear, copy-paste-ready instructions for them. Reference:

references/git-sync-handoff.md

If the user explicitly does not want Git Sync, fall back to the content-import path (content import and template application) — covered briefly below and in

references/api-cheatsheet.md

在执行任何操作前，必须牢记最重要的一点：无论使用哪种传输方式，GitBook几乎可以完成所有操作，除了配置Git Sync。授权GitHub/GitLab、选择仓库、选择分支、设置单体仓库布局的项目目录，以及选择初始同步方向，这些都是仅能通过UI完成的操作——REST API和MCP（包装了API）仅允许读取最终的Git Sync状态，无法进行配置。

这意味着最顺畅的端到端流程始终是：

Claude在本地搭建Git仓库（若工具允许，同时配置远程仓库）
Claude创建站点、分区以及所有可创建的空空间
用户在GitBook中完成简短且步骤明确的UI操作，将每个空间与仓库中的对应目录关联
Claude应用品牌化/自定义设置

步骤3中用户的操作是不可避免的，但不应让用户感到意外——需为用户生成清晰、可直接复制粘贴的操作指南。参考：

references/git-sync-handoff.md

。

若用户明确不需要Git Sync，则退回到内容导入路径（内容导入和模板应用）——下文及

references/api-cheatsheet.md

中有简要说明。

Inputs you should gather up front

需提前收集的输入信息

Don't start scaffolding until these are known. If something is missing, ask once with a focused question rather than guessing. (Auth is handled separately — see "How you can talk to GitBook" above.)

Organization — list the user's orgs and show the list to the user, then ask them to confirm which one is the target by name. Do this even if they have only one org — confirming once up front is cheap insurance against creating sites in the wrong place. Save the chosen
```
organizationId
```
for the rest of the session and refer to the org by its title (not its UUID) when narrating subsequent steps.
Site plan and visibility — default to
type: site
on the Ultimate plan, public visibility, unless the user explicitly says otherwise. Most real customers want the Ultimate feature set (custom domain, AI Assistant, advanced customization, hidden GitBook trademark, custom fonts, custom logos). The free tier (
```
type: basic
```
) is appropriate only for clearly low-stakes use cases like solo open-source side projects. If you're unsure, ask: "I'll set this up on the Ultimate plan unless you'd prefer the free tier — should I downgrade?" — Ultimate features that are silently absent on
```
basic
```
(no AI assistant, no custom fonts, no custom domain) are a much bigger user surprise than briefly confirming the plan.
The content seed — what's the site being built from? Common shapes:
- A folder of existing markdown — the cleanest starting point
- A handful of notes plus a competitor's site as a reference
- Just a description of what they want to document
- An existing site they want to restructure (in which case fetch the site's current structure first)
- A migration from another docs platform (Mintlify, Docusaurus, ReadTheDocs, GitBook v1) — see
```
references/migration-from-other-platforms.md
```
  for the workflow. Migration is its own discipline; don't treat it as a glorified file copy.
OpenAPI spec for the API reference — if the site has any API reference content, ask up front whether they have an OpenAPI spec (or whether one can be generated from their codebase). If yes, the API reference space is one
```
builtin:openapi
```
SUMMARY entry plus a one-paragraph overview README per resource — dramatically less work than hand-authored endpoint pages, and never drifts. See
```
references/block-ecosystem.md
```
and
```
references/api-cheatsheet.md
```
for the workflow. Don't default to hand-authored endpoint pages — they're almost always the wrong call.
Branding — at minimum, primary color (hex). Optionally: logo URLs (light + dark), favicon, font choice (or one of GitBook's defaults), header links, footer text/links, theme preset (
```
clean
```
,
```
muted
```
,
```
bold
```
,
```
gradient
```
). For Ultimate sites, also consider AI-assistant starter prompts (3-5 short questions visitors are likely to ask).
Site structure — sections, not site-spaces. If the site has more than one space, plan the section list with the user explicitly: each section has a title, a Font Awesome icon name, and a description. Section icons and descriptions are first-class navigation furniture — visitors see them — and gathering them up front saves a follow-up update per section later. Example:
```
[{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 remote preference — GitHub, GitLab, or local-only. Check whether
```
gh
```
or
```
glab
```
are installed before asking. If neither tool is available, say so explicitly and offer two paths: (1) commit locally and put the "create the remote and push" step at the top of the user's handoff, or (2) ask the user to install the tool. Don't quietly default to local-only without telling them — they'll have a repo with no remote and no instructions.
Site shape — single space or multi-space. Multi-space sites use sections to group spaces in the navigation; this is the right choice when content has clearly distinct audiences (e.g. user docs + API reference + changelog). Use site-spaces directly only for translation variants — see
```
references/api-cheatsheet.md
```
.

在开始搭建前，必须明确以下信息。若有缺失，针对性询问一次，而非猜测。（认证处理单独进行——请参考上文“与GitBook交互的方式”。）

组织——列出用户的组织，将列表展示给用户，然后请用户确认目标组织名称。即使用户只有一个组织，也要提前确认——这能避免在错误的组织中创建站点。保存选定的
```
organizationId
```
，后续会话中提及组织时使用其名称（而非UUID）。
站点计划和可见性——默认使用Ultimate计划的
type: site
类型，公开可见，除非用户明确说明。大多数实际客户需要Ultimate功能集（自定义域名、AI助手、高级自定义、隐藏GitBook商标、自定义字体、自定义Logo）。免费版（
```
type: basic
```
）仅适用于明确低风险的场景，比如个人开源项目。若不确定，询问用户：“我将按Ultimate计划搭建，除非你偏好免费版——是否需要降级？”——免费版中默认缺失的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
```
中的工作流。不要默认手动编写端点页面——这几乎总是错误的选择。
品牌化信息——至少需要主色调（十六进制值）。可选信息：Logo 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
```
。

Verify the content source before building

构建前验证内容源

Once the user names a content seed — a repo, folder, or docs-site URL — verify you can actually read it before designing structure or scaffolding anything:

Resolve and echo the source. State exactly what you're about to read (repo URL and branch, folder path, or site URL) and show the user its top-level contents — a short file or page list — so they can confirm it's the right one.
If you can't access it, stop and say so. Git hosts return 404 for private repositories — indistinguishable from "repository doesn't exist." Treat any 404 or clone failure on a user-named repo as possibly private: tell the user what failed, and ask them to either make the content reachable (local clone, archive, authenticated
```
gh
```
/
```
glab
```
, public mirror) or correct the URL. Check whether an authenticated
```
gh
```
/
```
glab
```
CLI is available before declaring the repo unreachable.
Never substitute a source. Do not search for, guess, or fall back to a similarly-named repository or site — even one that looks identical. Building a docs site from the wrong source is far worse than pausing to ask. Any change of source requires the user's explicit sign-off.

一旦用户指定了内容源——仓库、文件夹或文档站点URL，在设计结构或搭建任何内容之前，先验证是否能实际访问：

解析并回显源信息。明确说明要读取的内容（仓库URL和分支、文件夹路径或站点URL），并向用户展示其顶层内容——简短的文件或页面列表，以便用户确认是否正确。
若无法访问，立即停止并告知用户。Git托管平台对私有仓库返回404错误——与“仓库不存在”无法区分。将用户指定仓库的任何404错误或克隆失败视为可能是私有仓库：告知用户失败情况，并请求用户让内容可访问（本地克隆、归档、已认证的
```
gh
```
/
```
glab
```
、公开镜像）或修正URL。在判定仓库不可访问前，先检查是否有已认证的
```
gh
```
/
```
glab
```
CLI可用。
切勿替换内容源。不要搜索、猜测或 fallback到名称相似的仓库或站点——即使看起来完全相同。基于错误的内容源构建文档站点，远不如暂停询问用户严重。任何内容源的变更都需要用户明确确认。

Confirmation gates for state-changing operations

状态变更操作的确认机制

Site creation, space creation, adding sections, attaching site-spaces, and customization changes all create or modify objects that are immediately visible to everyone in the org and that take real effort to clean up. Treat them as heavy operations.

The rule: never make a state-changing change without first showing the user a one-screen preview of exactly what's about to happen and getting an explicit "yes".

A good preview is short and concrete:

About to run, in org Acme Inc (
org_abc123
):
Create site "Acme Platform Docs" (type: site, plan: ultimate, visibility: public)

Create 3 empty spaces: Guides, API Reference, Changelog

Add Guides as the default section; create sections for API Reference and Changelog

Proceed? (yes/no)

Bad previews are vague ("I'll create the site now") or buried in a wall of explanation. Keep it scannable.

The same rule applies to destructive operations — deleting a site, space, section, or customization override — only with even less ambiguity ("This will delete site Acme Platform Docs along with its 3 spaces. Spaces and sites are recoverable for 7 days, then permanent. Confirm?").

When the user has already confirmed a multi-step plan in the structure-design step, you don't need to ask again for each individual operation inside that plan — but if anything in the plan changes (an extra space, a different visibility), re-confirm.

For read-only operations (fetching or listing), no confirmation is needed.

创建站点、创建空间、添加分区、关联站点空间以及自定义设置变更，这些操作都会创建或修改组织内所有人立即可见的对象，且清理这些对象需要实际付出努力。请将这些操作视为高风险操作。

规则：在执行任何状态变更操作前，必须向用户展示即将执行操作的完整预览，并获得明确的“同意”。

好的预览应简洁具体：

即将在组织 Acme Inc（
org_abc123
）中执行以下操作：
创建站点 "Acme Platform Docs"（类型：site，计划：ultimate，可见性：公开）

创建3个空空间：Guides、API Reference、Changelog

将Guides设为默认分区；为API Reference和Changelog创建分区

是否继续？（是/否）

糟糕的预览模糊不清（“我现在将创建站点”）或隐藏在大量解释中。请保持预览简洁易读。

同样的规则适用于破坏性操作——删除站点、空间、分区或自定义覆盖设置——且需更加明确（“这将删除站点 Acme Platform Docs 及其3个空间。空间和站点可在7天内恢复，之后将永久删除。确认执行？”）。

若用户已在结构设计步骤中确认了多步骤计划，则无需对计划内的每个单独操作再次确认——但如果计划有任何变更（例如新增空间、修改可见性），需重新确认。

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

After a change-request push: two links are mandatory

变更请求推送后：必须返回两个链接

Whenever this skill (or

write-docs

, which it delegates page authoring to) pushes content through a change request — via MCP's

updateChangeRequestContent

create_change_request

submit_or_merge_change_request

curated tools,

invoke_operation

, or the REST equivalents — the edit is not finished until both of the following have been reported back to the user, every time:

The change request's diff/editor link (
```
urls.app
```
) — the link to review the change in the GitBook app.
The site preview link — the rendered docs with the change applied. This takes a separate lookup: the site URL lives on the Site object (
```
urls.published
```
when the site is public, else
```
urls.preview
```
), not the change-request object, and you must append
/~/changes/<number>/
to it, stripping the trailing slash the API returns. Without that segment the link renders the site's current content rather than this change request — it loads fine and shows the wrong thing.

This is a hard rule, on the same footing as the confirmation gates above — not a nicety to add if there's time. See

write-docs

's "Two links are mandatory whenever a change request is involved" and the

cr-create

skill's "Surfacing the preview link" for the exact resolution steps (MCP:

getSpaceById

→ find the site via

list_sites

get_site_structure

or each site's site-spaces →

getSiteById

for

.urls.preview

; REST: the equivalent chained

GET

calls). If the space isn't attached to a published site, say so plainly rather than only giving the diff link with no explanation.

每当本技能（或其委托页面编写的

write-docs

技能）通过变更请求推送内容——无论是通过MCP的

updateChangeRequestContent

create_change_request

submit_or_merge_change_request

工具、

invoke_operation

，还是REST等效操作——编辑操作并未完成，必须向用户返回以下两个链接，每次都要执行：

变更请求的差异/编辑器链接（
```
urls.app
```
）——在GitBook应用中查看变更的链接。
站点预览链接——应用变更后的渲染文档链接。这需要单独查询：站点URL位于Site对象中（站点公开时为
```
urls.published
```
，否则为
```
urls.preview
```
），而非变更请求对象，且必须在末尾追加
/~/changes/<number>/
，去掉API返回的末尾斜杠。如果没有这段路径，链接将显示站点的当前内容，而非变更请求的内容——链接可正常加载，但显示的内容错误。

这是硬性规则，与上述确认机制同等重要——并非有空才添加的额外操作。具体解析步骤请参考

write-docs

中的“涉及变更请求时必须返回两个链接”以及

cr-create

技能中的“展示预览链接”（MCP：

getSpaceById

→ 通过

list_sites

get_site_structure

或每个站点的站点空间找到站点 →

getSiteById

获取

.urls.preview

；REST：等效的链式

GET

调用）。若空间未关联到已发布站点，请明确告知用户，而非仅提供差异链接却不解释。

Designing the site structure

设计站点结构

Before writing any files or creating anything in GitBook, decide on the structure and run it past the user. A weak structure is the single biggest reason docs sites fail to land.

The output of this step is a small plan, ideally three pieces:

The space list — one space per coherent body of content. Keep it small (1–4 spaces is typical). A space is a unit of navigation and Git Sync, so don't split a single audience's content across spaces.
The section grouping (if multi-space) — sections are top-level partitions in the site nav, e.g. "Product" / "Developers" / "Resources". A section can hold one or more spaces.
The page tree per space — folders and pages, with one or two sentence summaries of each page. The depth should match the content; shallow trees (1–2 levels) are usually best.

The full set of heuristics for going from raw inputs to a structure plan is in

references/site-structure-design.md

— read it the first time you do this for a non-trivial site. Always show the plan to the user and get explicit sign-off before scaffolding files. Restructuring later is cheap inside Git but expensive once a site is published and indexed.

A note on confirmation when the user gives one collapsed instruction: prompts like "plan the structure and then scaffold it" tempt you to skip the gate. Don't. Present the plan as a clear, scannable block, then either wait for a "yes" or — if you've already started scaffolding because the prompt was that explicit — surface what you decided in the plan and offer one easy chance to redirect ("if any of this is off, tell me and I'll redo before going further"). The point is that the user sees the plan before they're staring at twenty generated files, while a redo is still cheap.

在编写任何文件或在GitBook中创建任何内容之前，先确定结构并与用户确认。结构薄弱是文档站点失败的最主要原因。

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

空间列表——每个空间对应一组连贯的内容。数量应少（通常1–4个空间）。空间是导航和Git Sync的单元，因此不要将同一受众的内容拆分到多个空间。
分区分组（多空间场景）——分区是站点导航中的顶级划分，例如“产品”/“开发者”/“资源”。一个分区可包含一个或多个空间。
每个空间的页面树——文件夹和页面，每个页面附带一两句摘要。深度应与内容匹配；通常浅层次结构（1–2级）最佳。

从原始输入到结构计划的完整启发式方法请参考

references/site-structure-design.md

——首次处理非 trivial站点时请阅读。在搭建文件前，务必向用户展示计划并获得明确确认。站点发布并被索引后，重构的成本很高。

注意：当用户给出一个简洁的指令时（例如“规划结构然后搭建”），不要跳过确认步骤。将计划以清晰易读的块呈现，然后等待用户“同意”——如果用户的指令非常明确，你已经开始搭建，也要将你确定的计划告知用户，并提供一次简单的调整机会（“如果有任何不合适的地方，请告诉我，我会在继续之前重新调整”）。关键是用户要在看到生成的二十个文件之前看到计划，此时重新调整的成本仍然很低。

Scaffolding the repository

搭建仓库

Once the structure is agreed, lay out the repo as a monorepo — even for single-space sites, this is consistent and future-proof. Each space is a directory containing its own

README.md

(homepage) and

SUMMARY.md

(table of contents). Optionally a

.gitbook/

folder for per-space variables and reusable content blocks, and optionally a

.gitbook.yaml

for advanced sync configuration.

Example layout for a three-space site:

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

A few notes about this layout that often trip people up:

.gitbook.yaml
is optional. GitBook works fine on the default convention of
```
README.md
```
+
```
SUMMARY.md
```
per space. Only add a
```
.gitbook.yaml
```
when you need to override the root, define redirects, or do something else non-default. The bundled example site (
```
references/example-site/
```
) has zero
```
.gitbook.yaml
```
files and works perfectly.
.gitbook/vars.yaml
holds space-scoped variables that pages can reference inline (e.g.
```
support_email: support@evolve.com
```
referenced as
```
{% vars.support_email %}
```
). Useful for any value that appears on many pages.
.gitbook/includes/<name>.md
holds reusable content blocks — a snippet you embed in many pages with
```
{% include "...persona-switcher" %}
```
. Use these instead of copy-pasting boilerplate.
The space directory name (e.g.
```
guides/
```
) is what the user enters into the "Project directory" field when wiring up Git Sync.

A minimal

.gitbook.yaml

, when you do need one, looks like:

yaml

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

结构确定后，将仓库布局为单体仓库——即使是单空间站点，这也保持了一致性且具有前瞻性。每个空间是一个目录，包含自己的

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
│   ├── SUMMARY.md
│   └── endpoints/
│       └── ...
└── changelog/                   # 空间3
    ├── README.md
    └── SUMMARY.md

关于此布局的一些常见误区：

.gitbook.yaml
是可选的。GitBook默认遵循每个空间
```
README.md
```
+
```
SUMMARY.md
```
的约定，无需额外配置。仅当需要覆盖根目录、定义重定向或执行其他非默认操作时，才添加
```
.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时输入“项目目录”字段的内容。

需要时，最简

.gitbook.yaml

如下：

yaml

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

The repo-level README and .gitignore

仓库级README和.gitignore

The repo-level

README.md

(top of the repo, not inside a space) should explain what the folder is and how it relates to the published site — not duplicate the docs themselves. A short paragraph is enough:

markdown

undefined

仓库级

README.md

（仓库根目录，而非空间内）应说明文件夹的用途以及与已发布站点的关系——不要重复文档内容。简短的一段文字即可：

markdown

undefined

my-docs

Source for the My Product docs site. Each top-level folder is a separate GitBook space; edits flow in both directions via Git Sync once configured.


A `.gitignore` should keep OS junk and editor settings out of the repo. Reasonable default:

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


If the team has additional generated artifacts (e.g. an OpenAPI spec built from source elsewhere), add those.

My Product文档站点的源码。每个顶级文件夹是一个独立的GitBook空间；配置完成后，编辑内容可通过Git Sync双向同步。


`.gitignore`应排除系统垃圾文件和编辑器设置。合理的默认配置：

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


如果团队有其他生成的工件（例如从其他源码生成的OpenAPI规范），也添加到忽略列表中。

Generating SUMMARY.md — gather the nav, don't infer it from folders

生成SUMMARY.md：收集导航，而非从文件夹推断

The most common scaffolding mistake is to walk the file tree and emit a SUMMARY.md from it: README at the top, every other file as a child indented under the README. This produces dispiriting nav — every page is a "child of the homepage", folder names become group titles whether or not they're meaningful to a reader, and the IA mirrors the file system instead of the user's mental model.

The right pattern, in order:

Gather the desired navigation from the user during structure design. Ask them — explicitly — to enumerate the top-level pages and the named groups for each space. This is the place where you make folder names match nav reality, and where the user can tell you "actually I want Authentication as a top-level page, not under Concepts."
Lay out folders to match the agreed nav, not the other way around. If the user wants three groups in a space — "Getting started", "Concepts", "Tutorials" — the space directory has three subfolders by those names (slugified), each with its own pages. Don't auto-extract a fourth group from a stray subfolder.
Write SUMMARY.md to the explicit shape the user agreed. The grammar that GitBook honors:
markdown
```
# 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)
```
Key shape rules:
- README.md is on its own line at the very top, as a sibling, not a parent. Other top-level pages follow as siblings.
- ## Group name
  headings introduce groups. Pages in a group are flat bullets directly under the heading — not indented under the README.
- Avoid mechanical " README.md" + nested-everything-under-it.* That collapses the entire nav into one tree under the homepage and makes every page look like a sub-page of the homepage in the sidebar.
- Group names come from the user, not the folder names. "concepts/" can be the folder slug, but the group heading might be "How it works" if that's clearer.
- One bullet per page, no extra formatting. No bold, no descriptions in the SUMMARY — those live in the page frontmatter.
Special-case patterns that aren't plain bullets:
- OpenAPI auto-generated endpoint pages use a fenced YAML block as the bullet content (
```
type: builtin:openapi
```
  — see
```
references/api-cheatsheet.md
```
  ).
- External links are
```
* [Title](https://...)
```
  and render as outbound links in the nav.
- Cross-space links in SUMMARY.md use the same
```
https://app.gitbook.com/s/<spaceId>/<path>
```
  form as in body content. Path has no
```
.md
```
  suffix. During scaffolding write the sentinel form (
```
XSPACE_<KEY>
```
  ); resolve after space creation. See
```
references/cross-space-links.md
```
  .

If your scaffolding helper auto-generates a SUMMARY.md by walking folders, make it idempotent and skip files that already exist. A user-edited SUMMARY.md should never be silently clobbered — that's how hand-tuned navigation gets lost.

最常见的搭建错误是遍历文件树并生成SUMMARY.md：将README放在顶部，其他所有文件作为README的子项缩进。这会导致导航效果不佳——每个页面都是“主页的子页面”，文件夹名称成为分组标题，无论对读者是否有意义，信息架构（IA）与文件系统镜像，而非用户的心智模型。

正确的步骤顺序：

在结构设计阶段从用户处收集所需的导航。明确询问用户——列出每个空间的顶级页面和命名分组。这是让文件夹名称与导航匹配的环节，用户可以告诉你“实际上我希望Authentication作为顶级页面，而非在Concepts下”。
根据确定的导航布局文件夹，而非相反。如果用户希望一个空间包含三个分组——“入门”“概念”“教程”，则空间目录包含这三个名称的子文件夹（转为短横线命名），每个子文件夹包含自己的页面。不要自动从零散的子文件夹中提取第四个分组。
按照用户确认的明确结构编写SUMMARY.md。GitBook遵循的语法：
markdown
```
# 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中添加描述——这些内容放在页面前置元数据中。
非普通项目符号的特殊模式：
- OpenAPI自动生成的端点页面使用 fenced 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不应被静默覆盖——这会导致手动调整的导航丢失。

Per-page markdown — defer to write-docs, but reach for the rich blocks

每页Markdown：委托给write-docs，但要使用丰富块

For all markdown files —

README.md

SUMMARY.md

, every page — follow the

write-docs

skill. It is the authoritative reference for:

Frontmatter including the
```
icon:
```
field. Icons are Font Awesome names without the
```
fa-
```
prefix (e.g.
```
book-open
```
,
```
bolt
```
,
```
house
```
,
```
code
```
,
```
puzzle-piece
```
,
```
id-card
```
,
```
circle-dollar-to-slot
```
). Don't invent names — pick from the Font Awesome catalogue. The example site uses these in nearly every page's frontmatter.
Layout flags including
```
layout: width: wide
```
(use selectively — on marketing-style landing pages, on changelog pages with the Updates timeline, on pages with multi-column blocks or genuinely wide tables. Don't default to wide for every space homepage — the GitBook default width is right for documentation, including documentation landing pages with card-tables. Wide is for hero-style marketing layouts, not normal docs.),
```
cover:
```
images, and per-page visibility flags (
```
title.visible
```
,
```
tableOfContents.visible
```
, etc.).
SUMMARY.md
grammar. Strict format — one bullet per page, optional
```
## Group name
```
headings, no extra formatting. Plus the special
```
type: builtin:openapi
```
syntax for auto-generating endpoint pages from a spec.
Rich blocks — tabs, hints, steppers, columns, card-tables, expandables, embeds, conditional content with
```
{% if visitor.claims... %}
```
, the OpenAPI block, the Updates block (changelog), reusable content includes.
GitBook-flavoured markdown differences from CommonMark.

Don't reinvent any of that here. The bundled

references/example-site/

is the best practical reference for what idiomatic content looks like.

所有Markdown文件——

README.md

、

SUMMARY.md

、每个页面——都遵循

write-docs

技能的规则。它是以下内容的权威参考：

前置元数据包括
```
icon:
```
字段。图标是不带
```
fa-
```
前缀的Font Awesome名称（例如
```
book-open
```
、
```
bolt
```
、
```
house
```
、
```
code
```
、
```
puzzle-piece
```
、
```
id-card
```
、
```
circle-dollar-to-slot
```
）。不要自创名称——从Font Awesome目录中选择。示例站点几乎每个页面的前置元数据都使用了图标。
布局标志包括
```
layout: width: wide
```
（选择性使用——用于营销风格的登陆页面、带有Updates时间线的更新日志页面、包含多列块或真正宽表格的页面。不要默认每个空间主页都使用宽布局——GitBook默认宽度适合文档，包括带有卡片表格的文档登陆页面。宽布局用于英雄式营销布局，而非普通文档。）、
```
cover:
```
图片，以及每页可见性标志（
```
title.visible
```
、
```
tableOfContents.visible
```
等）。
SUMMARY.md
语法。严格格式——每个页面一个项目符号，可选
```
## Group name
```
标题，无额外格式。加上用于从规范自动生成端点页面的特殊
```
type: builtin:openapi
```
语法。
丰富块——选项卡、提示、步骤器、列、卡片表格、可展开块、嵌入、使用
```
{% if visitor.claims... %}
```
的条件内容、OpenAPI块、Updates块（更新日志）、可复用内容包含。
GitBook风格Markdown与CommonMark的差异。

不要在此处重新发明任何规则。附带的

references/example-site/

是了解符合规范的内容样式的最佳实用参考。

Choosing the right block — actively, not by default

主动选择合适的块，而非默认使用普通格式

A common failure mode: Claude generates docs that work but use plain markdown for everything, missing the rich blocks that make GitBook sites feel like a real product. The skill should actively reach for specialized blocks, not fall back to bare prose-and-bullets. Concrete patterns to internalize:

Changelogs →
```
{% updates %}
```
block with
```
{% update date="..." tags="..." %}
```
entries. Auto-generates RSS, supports tags (defined in
```
.gitbook/tags.yaml
```
). Don't write
```
## YYYY-MM-DD
```
headings — that's the wrong shape.
API endpoint references → OpenAPI spec uploaded once, auto-generated pages via
```
type: builtin:openapi
```
in SUMMARY.md. Don't hand-author endpoint pages — they drift, and the spec is canonical anyway. If the user doesn't have a spec, offer to draft a minimal one rather than going prose-y.
State machines, flows, sequences, simple architecture →
```
```mermaid
```
fenced blocks. Don't draw boxes-and-arrows in ASCII; Mermaid is supported, renders cleanly, and is screen-reader friendly.
Space homepages → use the GitBook default layout for normal docs landings (TOC visible, default width). Reach for
```
layout: width: wide
```
only when the page is genuinely marketing-style — a hero image, an unusually large card grid, a multi-column dashboard layout. The default is right for docs.
"Choose your path" content → card-tables (
```
<table data-view="cards">
```
). The HTML is verbose but the visual result beats any markdown alternative.
Side-by-side intro patterns →
```
{% columns %}
```
block. Two columns at 50/50 is the standard.

Repeated boilerplate (3+ places) →

.gitbook/includes/<name>.md

{% include "..." %}

Repeated literals (env URLs, support email, version pin) →

.gitbook/vars.yaml

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

Multi-language code samples →
```
{% tabs %}
```
block.
Walkthroughs of 3+ ordered steps →
```
{% stepper %}
```
block.

The full block-by-block guide, with example invocations and a smell-vs-fix decision table, is in

references/block-ecosystem.md

. Read it before generating any non-trivial page, and walk the decision table for each content area being scaffolded — ask "is there a specialized block for this?" before defaulting to plain markdown.

常见的失败模式：Claude生成的文档可用，但所有内容都使用普通Markdown，错过了让GitBook站点感觉像真正产品的丰富块。技能应主动使用专门的块，而非 fallback到纯文本和项目符号。需要牢记的具体模式：

更新日志 → 使用
```
{% updates %}
```
块，包含
```
{% update date="..." tags="..." %}
```
条目。自动生成RSS，支持标签（在
```
.gitbook/tags.yaml
```
中定义）。不要编写
```
## YYYY-MM-DD
```
标题——这是错误的结构。
API端点参考 → 上传一次OpenAPI规范，通过SUMMARY.md中的
```
type: builtin:openapi
```
自动生成页面。不要手动编写端点页面——内容会不一致，而规范是权威的。如果用户没有规范，建议起草一个最简规范，而非使用纯文本。
状态机、流程、序列、简单架构 → 使用
```
```mermaid
```
fenced块。不要用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

。在生成任何非 trivial页面之前阅读，并为搭建的每个内容区域走一遍决策表——在默认使用普通Markdown之前，先问“是否有专门的块适合这个内容？”。

Cross-space links

跨空间链接

Multi-space sites want cross-space links — they're how a site feels like one connected product, not a bunch of separate manuals. Don't duplicate content to avoid them, and don't drop them. They're a first-class GitBook feature; the only twist is that they need real space IDs to render correctly, and IDs only exist after the site is created.

The pattern in markdown is just a regular link to the GitBook URL of the target space:

markdown

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

GitBook resolves

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

at render time, regardless of your custom domain. Internally these are

ContentRefPage

ContentRefSpace

content references with the space ID set; in markdown they just appear as URLs.

The scaffolding flow:

During scaffolding, write cross-space links using a sentinel space-ID prefixed with
```
XSPACE_
```
, one per planned space. Use the space slug from your structure plan as the suffix:
markdown
```
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/).
```
These are valid markdown links to non-existent GitBook spaces — they don't break the parser, they're easy to grep for, and they round-trip cleanly through Git.

After space creation, once you have each new space's real ID, walk every markdown file and substitute

XSPACE_<KEY>

with the real space 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/*')

Commit and push the resolution. GitBook will pick it up via Git Sync and the links will resolve on the next render.

For a clean implementation, keep a

cross-space-links.yaml

in the repo root mapping sentinel keys to space IDs, generated after creation. That makes the resolution script reproducible if anyone re-runs it. The full pattern, including anchor links, page-specific links, and a sample resolution script, is in

references/cross-space-links.md

Where this gets written into: the scaffold (with sentinels), the markdown content as you generate it across spaces, and the post-creation resolution step. Don't try to write real

app.gitbook.com/s/<id>/...

links during scaffolding — IDs don't exist yet, and any guess will be a broken link.

多空间站点需要跨空间链接——这是让站点感觉像一个互联产品，而非一堆独立手册的方式。不要为了避免跨空间链接而重复内容，也不要省略它们。这是GitBook的一等功能；唯一需要注意的是，它们需要真实的空间ID才能正确渲染，而ID只有在站点创建后才存在。

Markdown中的模式只是指向目标空间GitBook URL的普通链接：

markdown

关于概念部分，请查看[Authentication概念页面](https://app.gitbook.com/s/<spaceId>/concepts/authentication)。

GitBook在渲染时会解析

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

，无论是否使用自定义域名。内部这些是设置了空间ID的

ContentRefPage

或

ContentRefSpace

内容引用；在Markdown中它们只是URL。

搭建流程：

搭建期间，使用前缀为
```
XSPACE_
```
的占位符空间ID编写跨空间链接，每个计划的空间对应一个占位符。使用结构计划中的空间slug作为后缀：
markdown
```
请查看[Authentication概念页面](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication)。
完整参考请查看[API Reference](https://app.gitbook.com/s/XSPACE_API/)。
```
这些是指向不存在的GitBook空间的有效Markdown链接——它们不会破坏解析器，易于搜索，且能通过Git完整往返。

空间创建后，一旦获得每个新空间的真实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/*')

提交并推送解析后的内容。GitBook将通过Git Sync获取，链接将在下次渲染时解析。

为了实现清晰的实现，在仓库根目录保留一个

cross-space-links.yaml

，映射占位符键到空间ID，创建后生成。这使得解析脚本可重复执行，如果有人重新运行的话。完整模式，包括锚点链接、页面特定链接和示例解析脚本，请参考

references/cross-space-links.md

。

写入位置： 搭建时（带占位符）、跨空间生成的Markdown内容中、创建后的解析步骤中。不要在搭建时尝试写入真实的

app.gitbook.com/s/<id>/...

链接——ID还不存在，任何猜测都会导致链接失效。

Where to look for example content

示例内容参考位置

references/example-site/

is a pruned snapshot of a production-style GitBook site bundled with this skill. The original is a 12-space site (home, three product spaces, three versions of a developer API, three guides spaces, partners, changelog, plus an external-content

connections/

tree) with ~200 content files; the bundled snapshot keeps ~150 to stay within file-count limits.

Read
references/example-site/PRUNE-NOTES.md
first — it explains exactly what was kept and dropped, and lists the highest-signal files to read for specific patterns. The TL;DR:

The full structural backbone of every space is intact —
```
README.md
```
,
```
SUMMARY.md
```
,
```
.gitbook/vars.yaml
```
,
```
.gitbook/includes/
```
.
```
developers/v2/
```
is kept in full as the canonical example.
```
developers/v1/
```
(legacy) and
```
developers/v3/
```
(beta) were dropped — they were structurally identical to v2 with version-specific content variations. The pattern of multi-version API docs is documented in PRUNE-NOTES.md and visible in
```
structure.json
```
.
```
connections/
```
— each subfolder (
```
blog/
```
,
```
community/
```
,
```
youtube/
```
) keeps its
```
index.html
```
plus one representative article so the metadata patterns stay learnable.
```
customization.json
```
and
```
structure.json
```
are the complete API exports describing the entire original site, including spaces and pages that were pruned. SUMMARY.md files inside each space also describe the original tree — some links in them point to pruned pages, which is expected.

Notable files to study, organized by pattern you're trying to demonstrate:

Pattern	File to read
Updates block + tags	`changelog/README.md` + `changelog/.gitbook/tags.yaml`
`builtin:openapi` SUMMARY pattern	`developers/v2/SUMMARY.md` (look at the fenced YAML bullets)
Mermaid diagrams (flowchart, sequence)	`products/payments/concepts/payment-lifecycle.md` , `developers/v2/identity-api/README.md`
Layout `width: wide` + cover image	`home/README.md` , `developers/v2/README.md`
Card-tables for navigation	`home/README.md` , `partners/README.md`
Conditional content via `{% if visitor.claims... %}`	`products/payments/accept-payments/take-a-payment.md`
Tabs and steppers used together	`developers/v2/getting-started/quickstart.md` , `developers/v2/getting-started/authentication.md`
Webhook docs with code samples	`developers/v2/webhooks/verifying-signatures.md`
Reusable content includes	`home/.gitbook/includes/persona-switcher.md`
`.gitbook/vars.yaml` variables	Any space's `.gitbook/vars.yaml`
Grouped SUMMARY.md (sections via `## Heading` )	Any of the per-space `SUMMARY.md` files

When you need a pattern not represented in the bundled snapshot (e.g. legacy/beta versioned API spaces side-by-side, the full external-content article catalogue),

structure.json

is the authoritative source for shape, and PRUNE-NOTES.md describes the patterns those omissions represented.

After scaffolding:

bash

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

If the user wants a remote and

gh

glab

is available:

bash

undefined

references/example-site/

是与本技能捆绑的修剪后的生产风格GitBook站点快照。原始站点是一个包含12个空间的站点（主页、3个产品空间、3个开发者API版本、3个指南空间、合作伙伴、更新日志，加上外部内容

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文件也描述了原始树——其中一些链接指向被修剪的页面，这是预期的。

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

模式	参考文件
Updates块 + 标签	`changelog/README.md` + `changelog/.gitbook/tags.yaml`
`builtin:openapi` SUMMARY模式	`developers/v2/SUMMARY.md` （查看fenced 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描述了这些省略内容所代表的模式。

搭建完成后：

bash

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

如果用户需要远程仓库且

gh

glab

可用：

bash

undefined

GitHub

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

GitLab

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


If neither tool is available, **say so explicitly** before scaffolding finishes. Two valid paths:

- **Local-only repo + manual remote step in handoff.** Commit locally, leave the user a "Step 0" in their handoff that says: *"On your machine, create a private GitHub or GitLab repo named `<name>`, then `git remote add origin <url> && git push -u origin main` from this directory."* Put this above the GitBook UI steps — they need the repo pushed before Git Sync can connect to it.
- **Ask the user to install `gh` or `glab`.** If they're going to be doing more sites, the tool is worth having.

Don't quietly default to local-only — a repo with no remote and no instructions about how to add one is a footgun the user will discover when they try to wire up Git Sync.

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时会发现问题。

Migration and content quality

迁移与内容质量

Most real builds aren't greenfield — they're migrations from another docs platform (Mintlify, Docusaurus, ReadTheDocs, an older GitBook), or restructurings of existing markdown. These have their own discipline that's distinct from "make a new site." Get this wrong and you produce something that looks like a docs site but reads like a machine output.

The full workflow is in

references/migration-from-other-platforms.md

. The headlines:

Mirror the source before reimagining it. When the user has an existing live docs site, fetch the rendered landing pages and look at them before generating any homepage content. The current IA is the spec; the user's reasons for it usually aren't visible from a folder of markdown alone. Inventing card grids, hero blocks, and "what's new" sections from scratch when the source already had a working answer is the most common content-quality failure mode.

A bulk export is rarely a complete content source. Mintlify's

llms-full.txt

, ReadTheDocs HTML scrapes, and similar AI-friendly exports often strip visible content (custom components rendered to raw markup, AI-prompt blocks unrolled inline, parameter names dropped from API tables). After bulk conversion, sample-check the rendered pages against the original site and flag where content is missing — don't pretend the export is the whole story.

Anchor pages, not all pages. Migrating 280 pages doesn't mean hand-crafting 280 pages with GitBook idioms. The right move is to bulk-convert the long tail, then deliberately rebuild 4–6 anchor pages — homepage, top-level landing per space, the marquee how-to — using the full block ecosystem. The rest can be brought up to standard iteratively.

Format-pass is a documented step. Naive markdown conversion leaves artifacts (foreign component tags, malformed code fences, broken internal links). After bulk conversion, run a clean-up pass before the first commit — remove unsupported components, normalize fences, rewrite

/docs/...

paths to GitBook URLs or relative paths. Skipping this produces a repo that almost renders.

Don't auto-generate frontmatter you don't have. When the source had no icons, don't auto-pick icons from URL slugs — you'll produce a sea of mismatched cog icons. When the source had no description, leave the field blank; don't stub it with

Source: <url>

(that text leaks into sidebar previews and search).

OpenAPI-first for API references. If the migrated site has API reference content and you can get an OpenAPI spec (or generate one from their codebase), route the entire reference space through

builtin:openapi

. A 70-page hand-converted reference is almost always worse than a 3-file auto-generated one.

Internal-link conversion is a sweep, not a per-page concern. After the structure is known, walk every markdown file and rewrite

/docs/...

links to either relative

.md

paths (within a space) or

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

URLs (across spaces). Doing this per-page-as-you-go produces inconsistent links; doing it as one sweep with a slug-to-path manifest is much more reliable.

Be careful with helper scripts that regenerate content. If you're using a converter or SUMMARY-generator, make it idempotent by default. Skip files that already exist. A second run that clobbers hand-tuned homepages is a footgun. Never run

rm -rf <space>/

on a directory that might contain hand-edited content; if you must regenerate, write to

<space>/_generated/

and merge or diff.

大多数实际构建不是从零开始——而是从其他文档平台（Mintlify、Docusaurus、ReadTheDocs、旧版GitBook）迁移，或重构现有Markdown。这些工作有其独特的规则，与“创建新站点”不同。如果处理不当，生成的内容看起来像文档站点，但读起来像机器输出。

完整工作流请参考

references/migration-from-other-platforms.md

。要点：

先镜像源内容，再重新设计。当用户有现有的在线文档站点时，在生成任何主页内容之前，先获取渲染后的登陆页面并查看。当前的信息架构是规范；用户使用它的原因通常仅从Markdown文件夹中无法看出。当源内容已有可行方案时，凭空发明卡片网格、英雄块和“新功能”部分是最常见的内容质量失败模式。

批量导出很少是完整的内容源。Mintlify的

llms-full.txt

、ReadTheDocs HTML抓取，以及类似的AI友好导出通常会丢失可见内容（自定义组件渲染为原始标记、AI提示块展开为内联内容、API表格中丢失参数名称）。批量转换后，将渲染后的页面与原始站点抽样对比，标记缺失的内容——不要假装导出的内容是完整的。

重点处理锚点页面，而非所有页面。迁移280页并不意味着为280页手工添加GitBook规范。正确的做法是批量转换长尾内容，然后刻意重建4–6个锚点页面——主页、每个空间的顶级登陆页面、重要的操作指南——使用完整的块生态系统。其余内容可逐步优化到标准。

格式清理是明确的步骤。简单的Markdown转换会留下痕迹（外来组件标签、格式错误的代码块、失效的内部链接）。批量转换后，在首次提交前运行清理步骤——移除不支持的组件、规范代码块格式、将

/docs/...

路径重写为GitBook URL或相对路径。跳过此步骤会生成一个几乎可以渲染的仓库。

不要自动生成不存在的前置元数据。如果源内容没有图标，不要从URL slug自动选择图标——会生成大量不匹配的齿轮图标。如果源内容没有描述，留空该字段；不要用

Source: <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/

并合并或对比差异。

Driving GitBook to build the site

驱动GitBook构建站点

The steps below are described as outcomes, not endpoint calls — use whichever transport you settled on in "How you can talk to GitBook" above. On the REST API path, the exact endpoints, request bodies, and expected responses for every step are in

references/api-cheatsheet.md

; read it before making any calls — the schemas are nuanced (especially customization). On the MCP path, the equivalent tools cover the same steps — read their own schemas rather than looking up REST paths.

以下步骤以结果描述，而非端点调用——使用上文“与GitBook交互的方式”中确定的传输方式。若使用REST API方式，每个步骤的具体端点、请求体和预期响应请参考

references/api-cheatsheet.md

；在进行任何调用前阅读——架构细节很微妙（尤其是自定义设置）。若使用MCP方式，等效工具覆盖相同步骤——阅读其自身架构而非REST路径。

The standard sequence for a new site

新站点的标准流程

Verify access and find the org: confirm the authenticated user, then list the orgs.
Create the site with
```
{title, type, visibility, spaces?}
```
. Default to Ultimate (
```
type: "site"
```
; the plan tier is set on the site after creation or via the org's billing). Use
```
type: "basic"
```
(free) only when the user explicitly opts in. Don't include
```
spaces
```
if no spaces exist yet — you can add them later.
Decide how spaces will come into being. Two paths:
- Git-Sync-first (recommended): tell the user to create each space in the GitBook UI by clicking "Add new space" → "Sync to a GitHub or GitLab repository", picking the repo and the per-space project directory. This creates the space, sets up sync, and links it to the site in one action. The skill's job is to give exact, copyable instructions (one block per space). See
```
references/git-sync-handoff.md
```
  .
- Programmatic-first: create empty spaces directly, add them to the site as site-spaces, and use content import or template application to load content. The user will still need to wire Git Sync in the UI later if they want bidirectional sync.
Add sections (multi-space sites with grouped navigation): a section is created by associating a space with a title and optional icon.
Resolve cross-space link sentinels: if the scaffolded markdown contains
```
XSPACE_<KEY>
```
placeholders (which it should, for any link that crosses a space boundary), now is when you substitute them for the real space IDs returned by step 3 or 4. See
```
references/cross-space-links.md
```
for the substitution script. Commit and push the changes — the next Git Sync run picks them up.
Apply customization (branding) — the full schema is broad: theme preset, colors (each as a
```
{light, dark}
```
themed pair), favicon, header (logo, primaryLink, links), footer (groups of links, copyright), themes (default light/dark, toggleable), AI mode, PDF export, and more. Recipes for common branding scenarios are in
```
references/customization-recipes.md
```
. Only change the fields you mean to — fetch the current settings first, modify in memory, and write the full result back rather than guessing at a partial payload.
Verify: fetch the site's structure to confirm the final tree, and its customization to confirm settings.

验证访问权限并找到组织：确认已认证用户，然后列出组织。
创建站点，参数为
```
{title, type, visibility, spaces?}
```
。默认使用Ultimate计划（
```
type: "site"
```
；计划层级在创建后或通过组织账单设置）。仅当用户明确选择时，才使用
```
type: "basic"
```
（免费版）。如果还没有空间，不要包含
```
spaces
```
参数——可稍后添加。
确定空间的创建方式。两种路径：
- 优先使用Git Sync（推荐）：告知用户在GitBook UI中点击“添加新空间”→“同步到GitHub或GitLab仓库”，选择仓库和每个空间的项目目录，创建空间、配置同步并关联到站点。技能的任务是提供精确、可复制的操作指南（每个空间一个块）。请参考
```
references/git-sync-handoff.md
```
  。
- 优先使用程序化方式：直接创建空空间，将其作为站点空间添加到站点，使用内容导入或模板应用加载内容。如果用户需要双向同步，后续仍需在UI中配置Git Sync。
添加分区（带分组导航的多空间站点）：通过将空间与标题和可选图标关联来创建分区。
解析跨空间链接占位符：如果搭建的Markdown包含
```
XSPACE_<KEY>
```
占位符（跨空间链接应包含），此时将其替换为步骤3或4返回的真实空间ID。解析脚本请参考
```
references/cross-space-links.md
```
。提交并推送变更——下次Git Sync运行时会获取这些变更。
应用自定义设置（品牌化）——完整架构范围广泛：主题预设、颜色（每个为
```
{light, dark}
```
主题对）、网站图标、页眉（Logo、primaryLink、链接）、页脚（链接组、版权）、主题（默认亮色/暗色、可切换）、AI模式、PDF导出等。常见品牌化场景的示例请参考
```
references/customization-recipes.md
```
。仅修改需要更改的字段——先获取当前设置，在内存中修改，然后写回完整结果，而非猜测部分负载。
验证：获取站点结构以确认最终树，获取自定义设置以确认配置。

Multi-language sites and auto-translated spaces

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

GitBook supports auto-translated site-spaces: a single English space (synced from Git) can be paired with computed translations in other languages. The translations are not separate spaces in the Git repo — they live entirely in GitBook and are configured through the UI under each section's settings. They show up as additional

site-space

objects under the same section, each with a different

language

and no

gitSync

field.

What this means in practice:

Don't scaffold per-language directories in the repo. The Git repo has one space per topic, in English. The skill writes one set of markdown files per content area, full stop.
Each section can hold many site-spaces. A "Payments" section might contain
```
Payments
```
(en, git-synced),
```
Payments (FR)
```
(fr, computed),
```
Payments (DE)
```
(de, computed), etc. The structure response will list all of them; only the English ones need a Git Sync handoff.
localizedTitle
shows up everywhere. Sections, section-groups, header links, footer links, and the site title itself all carry a
```
localizedTitle: {de: "...", fr: "...", ...}
```
map. When reading the customization, expect to see translations even for fields the user only set in English. Don't strip these out unless asked.
Auto-translation is a UI-only feature today. If the user wants it enabled on a section, surface that as part of the Git Sync handoff: "After Git Sync is configured, go to Site → Sections → Payments → Translations and enable the languages you want."

When the user asks for "a docs site in five languages", the answer is one English content tree in Git plus auto-translation enabled per section in the UI — not five copies of the markdown.

GitBook支持自动翻译站点空间：单个英文空间（从Git同步）可与其他语言的自动翻译版本配对。翻译内容不在Git仓库中——完全存储在GitBook中，通过每个分区设置中的UI配置。它们作为同一分区下的额外

site-space

对象出现，每个对象具有不同的

language

，且无

gitSync

字段。

实际意义：

不要在仓库中搭建按语言划分的目录。Git仓库每个主题一个空间，使用英文。技能只为每个内容区域编写一套Markdown文件，仅此而已。
每个分区可包含多个站点空间。“Payments”分区可能包含
```
Payments
```
（英文，Git同步）、
```
Payments (FR)
```
（法文，自动翻译）、
```
Payments (DE)
```
（德文，自动翻译）等。结构响应会列出所有这些空间；仅英文空间需要Git Sync操作指南。
localizedTitle
随处可见。分区、分区组、页眉链接、页脚链接以及站点标题本身都带有
```
localizedTitle: {de: "...", fr: "...", ...}
```
映射。读取自定义设置时，即使用户仅用英文设置，也可能看到翻译内容。除非被要求，否则不要删除这些内容。
自动翻译目前是UI-only功能。如果用户要在分区上启用，将其作为Git Sync操作指南的一部分：“配置Git Sync后，前往站点 → 分区 → Payments → 翻译，启用所需语言。”

当用户要求“支持五种语言的文档站点”时，解决方案是Git中的一套英文内容树，加上在UI中为每个分区启用自动翻译——而非五份Markdown副本。

Section groups

分区组

A site's structure has three possible levels of nesting in the navigation:

Site-spaces at the root (a flat site, no sections)
Sections containing site-spaces (the typical multi-space site)
Section groups containing sections containing site-spaces (used to bucket related sections, e.g. "Products" group containing Payments / Identity / Connect sections)

The site's structure response is recursive — a section-group's

sections

array can hold both sections and other section-groups. When designing the structure, use section-groups only when there are 3+ closely related sections that benefit from being visually grouped in the top nav. For a 2-section site, sections at the root level are clearer.

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

站点空间在根目录（扁平站点，无分区）
分区包含站点空间（典型的多空间站点）
分区组包含分区，分区包含站点空间（用于将相关分区分组，例如“产品”组包含Payments / Identity / Connect分区）

站点结构响应是递归的——分区组的

sections

数组可包含分区和其他分区组。设计结构时，仅当有3个以上密切相关的分区，且在顶部导航中视觉分组有益时，才使用分区组。对于2个分区的站点，根层级的分区更清晰。

Updating an existing site

更新现有站点

When asked to modify a site that already exists, always fetch the current state first:

Site metadata
Structure (sections + spaces)
Customization (site-level or per-site-space), for branding

Then make targeted changes rather than wholesale replacements. Don't replace whole customization payloads if you only mean to change one field — fetch the current settings, modify in memory, and write the full result back.

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

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

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

When to use content import vs. Git Sync

何时使用内容导入 vs. Git Sync

Content import is for ingesting external content (a website URL, a set of files) into a space. It's good for one-shot migrations from another doc tool.
Git Sync is for ongoing two-way sync between a Git repo and a space. This is what we're optimizing for in the standard flow.
If the user has already-good content sitting outside both Git and GitBook (e.g. a Notion export), import it, then optionally turn on Git Sync afterward.

内容导入用于将外部内容（网站URL、一组文件）导入到空间。适用于从其他文档工具进行一次性迁移。
Git Sync用于Git仓库与空间之间的持续双向同步。这是标准流程优化的目标。
如果用户已有优质内容，且不在Git和GitBook中（例如Notion导出），先导入，然后可选启用Git Sync。

Branding and customization

品牌化与自定义设置

The

SiteCustomizationSettings

schema is large. The bundled

references/example-site/customization.json

is a real export from a production-style demo and is the most useful reference — read it before composing any customization payload. It shows how all the nested fields fit together, how

localizedTitle

maps work, and how conditional header links are structured.

The full field listing, schema quirks (

styling.background

required-but-vestigial,

header.links[]

requiring

links: []

ContentRef

formats for header/footer links, and conditional link patterns are all in

references/customization-recipes.md

— see "Field cheatsheet" and Scenarios 4–5. Premium and Ultimate features (custom logos, custom fonts, semantic colors, footer logo, advanced customization) will be rejected on free sites — handle gracefully; on the REST path see

references/api-cheatsheet.md

for the exact error responses.

references/customization-recipes.md

has worked examples for: minimal brand pass (just colors + favicon), full brand with logos and fonts, dark-mode-only with toggle, and AI-assistant enabled with suggested prompts.

For a complete real-world payload to learn from,

references/example-site/customization.json

is the customization export of a production site bundled with this skill. Reading it is the fastest way to see how all the fields fit together in practice — much more useful than the abstract schema. Don't paste it wholesale into a new site; use it as a model for shape and field selection.

For a real example of the structure response (sections, section-groups, multi-language site-spaces), see

references/example-site/structure.json

alongside it.

SiteCustomizationSettings

架构很大。附带的

references/example-site/customization.json

是生产风格演示的真实导出，是最有用的参考——在编写任何自定义设置负载前阅读。它展示了所有嵌套字段如何组合、

localizedTitle

映射如何工作，以及条件页眉链接的结构。

完整字段列表、架构细节（

styling.background

是必填但遗留字段、

header.links[]

需要

links: []

）、页眉/页脚链接的

ContentRef

格式，以及条件链接模式，请参考

references/customization-recipes.md

——查看“字段速查表”和场景4–5。免费站点会拒绝高级和Ultimate功能（自定义Logo、自定义字体、语义颜色、页脚Logo、高级自定义）——请优雅处理；REST方式下，具体错误响应请参考

references/api-cheatsheet.md

。

references/customization-recipes.md

包含以下场景的示例：最小品牌化（仅颜色+网站图标）、完整品牌化（带Logo和字体）、仅暗色模式（可切换）、启用AI助手并带建议提示语。

要学习完整的真实负载，请参考

references/example-site/customization.json

，这是与本技能捆绑的生产站点的自定义设置导出。阅读它是了解所有字段实际组合方式的最快方法——比抽象架构更有用。不要将其直接粘贴到新站点；将其作为结构和字段选择的模型。

要查看结构响应（分区、分区组、多语言站点空间）的真实示例，请参考

references/example-site/structure.json

。

The Git Sync handoff

Git Sync操作指南

This is the part that has to feel polished. Once the repo is pushed and the site exists, generate a clear set of per-space instructions. For each space, the user needs:

The repo URL
The branch name (usually
```
main
```
)
The project directory for that space (e.g.
```
guides
```
,
```
api-reference
```
)
The initial sync direction — almost always GitHub → GitBook (or GitLab → GitBook), since the repo is the source of truth at this point

references/git-sync-handoff.md

has a template you can fill in and present to the user. Render it as a numbered list per space, not as one big wall of prose. After they finish, ask them to confirm — at that point you can check each space's sync state programmatically to verify.

这部分必须感觉流畅。仓库推送且站点创建后，为每个空间生成清晰的操作指南。对于每个空间，用户需要：

仓库URL
分支名称（通常是
```
main
```
）
该空间的项目目录（例如
```
guides
```
、
```
api-reference
```
）
初始同步方向——几乎总是GitHub → GitBook（或GitLab → GitBook），因为此时仓库是事实来源

references/git-sync-handoff.md

有一个模板，可填充后展示给用户。将其渲染为每个空间的编号列表，而非一大段文字。用户完成后，请他们确认——此时你可以通过程序化方式检查每个空间的同步状态以验证。

Common mistakes to avoid

需避免的常见错误

Don't put the PAT in any file Claude writes. Always read it from the environment.
Don't silently swap the content source. If the repo or folder the user named can't be read (remember: private repos return 404, same as nonexistent ones), stop and ask — never proceed with a lookalike public repo. See "Verify the content source before building."
Don't try to set up Git Sync programmatically. It's UI-only regardless of transport — always route through the UI handoff.
Don't paste an entire customization payload from memory. Fetch the current state, modify it, then write the full result back. Schemas evolve and you'll write fewer bugs this way.
Don't create a space for every section of content. A space is a heavy unit (it has its own URL slug, sync, settings). Pages and folders within a space are the right tool for sub-grouping.
Don't skip the structure-plan-and-confirm step, even when the user is in a hurry. Restructuring a published site is painful.
Don't over-format the SUMMARY.md. GitBook's parser is strict about it. Defer to the rules in
```
write-docs
```
.
Don't finish a change-request edit without both links. See "After a change-request push: two links are mandatory" — the CR diff link alone is an incomplete answer.

不要将PAT写入Claude编写的任何文件。始终从环境变量读取。
不要静默替换内容源。如果用户指定的仓库或文件夹无法读取（记住：私有仓库返回404，与不存在的仓库相同），停止并询问——切勿使用相似的公共仓库继续。请参考“构建前验证内容源”。
不要尝试通过程序化方式配置Git Sync。无论使用哪种传输方式，这都是UI-only操作——始终通过UI操作指南完成。
不要凭记忆粘贴整个自定义设置负载。先获取当前状态，修改后写回完整结果。架构会演进，这样做会减少错误。
不要为每个内容分区创建一个空间。空间是重量级单元（有自己的URL slug、同步、设置）。空间内的页面和文件夹是子分组的正确工具。
不要跳过结构计划和确认步骤，即使用户很匆忙。重构已发布的站点很痛苦。
不要过度格式化SUMMARY.md。GitBook的解析器对格式要求严格。请遵循
```
write-docs
```
中的规则。
不要在变更请求编辑完成后仅返回一个链接。请参考“变更请求推送后：必须返回两个链接”——仅返回CR差异链接是不完整的答案。

Reference files

参考文件

```
references/api-cheatsheet.md
```
— the complete set of API calls used by this skill, with curl-style request bodies and expected responses
```
references/site-structure-design.md
```
— heuristics and worked examples for going from raw inputs to a space/section/page plan
```
references/migration-from-other-platforms.md
```
— pre-flight, source-platform mappings (Mintlify, Docusaurus, GitBook v1, RTD), anchor-pages strategy, format-pass, internal-link sweep. Read this before any migration build, not after.
```
references/block-ecosystem.md
```
— which GitBook block to reach for in which content situation, with a decision table and worked examples (Updates, Mermaid, OpenAPI auto-gen, layout flags, card-tables, conditional content, includes, vars). Read this before generating any non-trivial page.
```
references/cross-space-links.md
```
— the sentinel-and-resolve workflow for cross-space links in markdown, with a working substitution script
```
references/git-sync-handoff.md
```
— the template for the user-facing Git Sync setup instructions
```
references/customization-recipes.md
```
— worked branding payloads for common scenarios
```
references/example-site/
```
— a pruned snapshot (~150 files) of a real production-style GitBook site repo (markdown,
```
SUMMARY.md
```
s,
```
.gitbook/
```
configs). Read
```
PRUNE-NOTES.md
```
inside it first — it explains what's kept, what's dropped, and lists high-signal files for specific patterns.
```
references/example-site/customization.json
```
— the customization export from that site, illustrating a complete real-world branding payload
```
references/example-site/structure.json
```
— the structure export, showing sections, section-groups, and multi-language site-spaces (English git-synced + auto-translated)

```
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自动生成、布局标志、卡片表格、条件内容、包含、变量）。生成任何非 trivial页面之前阅读。
```
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同步 + 自动翻译）