编辑 GitBook 文档时用 Git…

在 Git 同步的 GitBook 仓库、IDE 或文本编辑器中创建/编辑 GitBook Markdown 页面时，按 GitBook 语法和 Git Sync 规则写入并回报预览链接。

适用场景

解决思路

1. 在 Git 同步仓库（GitHub/GitLab）、本地 markdown 编辑器、IDE 集成或任何以文件而非 GitBook UI 编辑 GitBook 内容的环境中，按本流程操作。
2. 识别 GitBook 内容层级：pages 是组成文档的单个 markdown 文件，spaces 是页面集合构成文档站，collections 是 spaces 的分组。
3. 按标准目录结构组织内容：.gitbook/assets/ 放 GitBook 管理的图片和文件，.gitbook/includes/ 放可复用内容块，.gitbook/vars.yaml 放空间级变量，.gitbook.yaml 放配置，README.md 为首页，SUMMARY.md 为目录，其他页面放各子目录。
4. 在页面顶部写 frontmatter；可用字段包括 description、icon、hidden、vars、layout.width（default 或 wide）、layout.tableOfContents.visible、layout.pagination.visible。
5. frontmatter 必须位于文件最顶部。
6. 定义变量：跨多页变量写在 /.gitbook/vars.yaml，用 space.vars.variableName 访问；单页变量写在 frontmatter 的 vars: 中，用 page.vars.variableName 访问。
7. 渲染变量使用表达式语法：<code class='expression'>space.vars.variableName</code>。
8. 按需求选择常见自定义块：tabs 用于 alternatives，hint 用于 callouts（info/warning/danger/success），stepper 用于 sequential steps，details/summary 用于可展开内容。
9. 根据场景选择块：顺序操作步骤用 {% stepper %}；语言/平台等备选方案用 {% tabs %}；可选或详细信息用 <details>；重要警告或提示用 {% hint %}；并排比较用 {% columns %}（最多 2 列）；时间线/变更日志用 {% updates %}；可视导航卡片用 <table data-view='cards'>；可下载文件用 {% file %}；行动号召链接用 <a class='button'>；跨页面复用内容用 {% include %}；动态内容用 <code class='expression'>。
10. 书写自定义块时始终正确闭合，例如 {% endtab %}、{% endhint %} 等，并确保开闭标签完全匹配。
11. 链接写法：外链用 [text](https://example.com)；同一 space 内相对链接用 [text](page.md) 或 [text](../folder/page.md)。
12. 跨 space 链接必须用 https://app.gitbook.com/s/<spaceId>/<path>；不要用相对路径跨 space，不要用 /spaces/<spaceId>/pages/<pageId> 这种无效形式。
13. 获取跨 space 链接参数：<spaceId> 从 GET /orgs/{orgId}/spaces 获取；<path> 从 GET /spaces/{spaceId}/content/pages 返回页面的 path 字段获取，而不是 page ID。
14. 遇到 org 限定形式 https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> 时不要修正；它是有效别名；不要在两种形式之间重写或 lint。
15. 新建站点且目标 space 尚不存在时，链接中使用 XSPACE_<KEY> 哨兵；之后由 configure-site 在创建后解析。
16. 页面移动或重命名后，GitBook 会自动从旧路径创建重定向；移动/重命名后测试重定向。
17. 处理已有内容时，先读 SUMMARY.md 获取完整目录和文件层级。
18. 若没有 SUMMARY.md，直接浏览目录结构。
19. 检查 .gitbook.yaml，确认 root path、自定义 README/SUMMARY 位置和 redirects。
20. 检查 .gitbook/assets/ 中的已上传图片和文件。
21. 检查 .gitbook/vars.yaml 中的空间级变量。
22. 关键提醒：处理已有内容先读 SUMMARY.md；本地编辑后在 GitBook 中测试；保持 SUMMARY.md 与文件结构和页面标题同步；OpenAPI specs 必须通过 UI、API、MCP 或 CLI 上传，不能嵌入 markdown。
23. 文件组织：不要在 SUMMARY.md 中重复引用同一个 markdown 文件；保持 SUMMARY.md 中的路径与实际文件位置一致。
24. 当重命名页面的标题（其 # 标题或 frontmatter 的 title）时，也要更新 SUMMARY.md 中该页面的链接文字；它驱动侧边栏导航、分页和相对链接文字，不会自动更新。仅当 SUMMARY.md 条目故意使用带引号的 link-title 覆盖（[Page main title](page.md 'Page link title')）时可跳过。
25. 配置：使用 Git Sync 时，只通过仓库管理 README.md。
26. frontmatter 中 description 含 :、# 或其他 YAML 特殊字符时，始终加引号；未加引号的特殊字符会导致 Git Sync 静默失败且无错误信息。
27. 不要要求回写时也加引号：GitBook 会按其序列化器选择的 YAML scalar style 重新输出 description，包括 folded blocks（>-）；校验 frontmatter 能否解析，而不是它怎么写。
28. Git Sync 下改动双向流动：Git 改动更新 GitBook，GitBook UI 改动提交回 Git；合并冲突在 Git 中解决。
29. Git Sync 最佳实践：结构性改动通过 Git 中的 SUMMARY.md 做；重大更新使用基于分支的工作流；审查 GitBook 自动生成的提交。
30. 通过 Git 推送分支时，打开 pull/merge request 或向已有 PR 的分支推送会让 GitBook 导入该分支并发布 commit status，链接到渲染站点的预览；每次推送 docs 改动都要主动把该链接给用户，无需用户询问。
31. 预览链接要从 commit status 读取，不要自行拼 URL；revision id 在导入时生成，无法从分支或 PR 推导，且每次推送都会生成新的，旧链接会失效。GitHub/GitLab 的命令和导入进行中处理见 references/git-sync-previews.md。
32. 当 space 已配置 Git Sync 且你有或能获得同步仓库的本地 checkout 时，优先直接编辑文件并 commit/push，由 Git Sync 把改动传播到 GitBook。
33. 即使 MCP 会话中可用 change-request 内容推送工具（如 updateChangeRequestContent）且已连接，也不要只因工具触手可及就绕过 Git 作为 source of truth；发现能直接推入 CR 的 agent 也应先检查 Git Sync 是否已配置且可达。
34. 仅在以下情况改用 change-request 内容推送路径（MCP 的 updateChangeRequestContent 或类似，或 REST 的 POST .../change-requests/<cr>/content，见 cr-create skill）：space 尚未配置 Git Sync（如仍在 setup 的新 space）；当前环境没有本地 Git checkout（无法访问同步仓库文件系统）；改动小且局部（错字、一段、一个字段），开 CR 更合适，完整 clone/commit/push 不值得。
35. 对于更大改动（新页面树、多页重写、迁移），即使需要暂停先确认仓库已在本地 clone，也优先 Git Sync；不要因为 change-request 工具先跑通就默认用它。
36. 只要本次编辑任何部分走了 change request（create_change_request / updateChangeRequestContent 或 REST 等价物），必须每次回报两个链接才算完成：1) CR diff/editor 链接，即 change-request 对象上的 urls.app，由 create_change_request、updateChangeRequestContent 或 getChangeRequestById 返回；2) 站点预览链接，即 Site 对象的站点 URL（公开站用 urls.published，否则 urls.preview）追加 /~/changes/<number>/。
37. 站点预览链接永远不在 change-request 响应里，必须单独查询；这是最容易被忘记的一步，每次都要解析。
38. 没有 ~/changes/ 段就不是该 change request 的预览，会渲染站点当前内容，看起来合理但错误。
39. 两个链接的要求适用于任何推送内容的 skill（本 skill 或 configure-site）以及任何传输方式（MCP 或 REST）；完整说明见 cr-create skill 的 Surfacing the preview link。
40. MCP 下没有单一现成预览链接调用；解析步骤：1) 解析 space 所属 organization：调用 getSpaceById，传入 path.spaceId，取 .organization（已有 org ID 可跳过）；2) 找 space 属于哪个 site：用 list_sites / get_site_structure，或检查每个 site 的 site-spaces 是否匹配 .space.id；3) 调用 getSiteById，传入 organizationId 和 siteId，取 .urls.published（站点已上线）否则 .urls.preview；追加 /~/changes/<number>/，并去掉 API 返回的尾部斜杠。
41. 如果 space 未挂到任何已发布 site，明确说明，并只给 diff 链接；不要不解释就悄悄省略 preview 行。
42. 该流程曾静默失败：一次编辑推送并合并后只回报了 diff 链接，preview 链接直到有人直接询问才出现；把两链接 checklist 当作字面规则执行。
43. 按需加载 references/blocks.md：用于全部 GitBook 块类型语法和示例（tabs、steppers、hints、expandable、columns、updates、cards、embeds、files、buttons、icons、reusable content、OpenAPI blocks），在编写非平凡页面或快速参考不足时加载。
44. 按需加载 references/frontmatter.md：用于全部 frontmatter 字段、YAML 引号规则、cover images、adaptive content（if:）、变量/表达式深入，在配置页面布局、封面、条件可见性或变量时加载。
45. 按需加载 references/markdown.md：用于标准 markdown、带标题代码块、math/TeX、Mermaid 图表类型和示例、SVG 处理怪癖，在处理图表、数学或 SVG 资源时加载。
46. 按需加载 references/configuration.md：用于 .gitbook.yaml 选项、.gitbook/ 目录结构（assets、includes、vars、tags）、SUMMARY.md 语法规则全文，在设置 space、添加 redirects 或编写/编辑 SUMMARY.md 时加载。
47. 按需加载 references/git-sync-serialisation.md：用于 GitBook 导出 space 回仓库时重写的内容：description: scalar style、跨 space 链接 URL 形式、块重新序列化，以及校验有效性而非形式的规则；在 Git Sync diff 包含非手改内容时，或编写任何校验 docs frontmatter 或 links 的检查/构建步骤前加载。
48. 按需加载 references/git-sync-previews.md：用于通过 Git Sync 推送分支后获取预览链接：在 GitHub 和 GitLab 读取 GitBook commit status、区分站点预览与编辑器 diff、处理仍在运行的导入；只要向带 PR/MR 的分支推送 docs 改动就加载。

适用边界 · 注意事项

• 不涉及 GitBook Markdown 页面、README.md、SUMMARY.md、GitBook 块、frontmatter、变量/表达式或 Git Sync 的任务不要套用。
• 空间未配置 Git Sync 且当前环境没有本地 Git checkout 时，不要强行走 Git 编辑/提交/推送；改用 change-request 内容推送或 REST API。
• 改动小且局部（错字、一段、一个字段）且 change-request 路径可用时，不必强行完整 clone/commit/push。