SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场write-docs

write-docs

写作与研究

查看项目

更新于 10-15 17:15

技能介绍

用途

write-docs 用于在 Git 同步仓库（GitHub、GitLab）、本地 Markdown 编辑器、IDE 集成，或任何以文件方式编辑 GitBook 内容（而非通过 GitBook UI）的环境中，编写、创作、编辑和格式化 GitBook 文档页面。

主要能力

内容结构

GitBook 通过页面、空间和集合组织内容：页面是构成文档的单个 Markdown 文件；空间是组织为文档站点的页面集合；集合是空间的组合。典型文件结构包含 .gitbook/ 目录（assets 图片与文件、includes 可复用内容块、vars.yaml 空间级变量）、.gitbook.yaml 配置、README.md 首页、SUMMARY.md 目录，以及按主题划分的文件夹。

Frontmatter 与变量

支持 description、icon、hidden、vars、layout（width、tableOfContents、pagination）等字段。变量分为空间变量（定义于 /.gitbook/vars.yaml，通过 space.vars.variableName 访问）和页面变量（定义于 frontmatter vars，通过 page.vars.variableName 访问），表达式语法为 <code class="expression">…</code>。

常用自定义块

  • {% tabs %}…{% endtabs %}：用于并列选项（语言、平台）
  • {% hint style="..." %}…{% endhint %}：提示框（info/warning/danger/success）
  • {% stepper %}…{% endstepper %}：顺序步骤
  • <details>…<summary>…</details>：可展开内容
  • {% columns %}：并排对比（最多 2 列）
  • {% updates %}：时间线或更新日志
  • <table data-view="cards">：可视化导航卡片
  • {% file %}：可下载文件
  • <a class="button">：行动号召链接
  • {% include %}：跨页面复用内容

链接

外部链接使用 text；同空间相对链接使用 text 或 text；跨空间链接必须使用 https://app.gitbook.com/s/<spaceId>/<path>，相对路径无法跨空间解析，/spaces/<id>/pages/<id> 不是有效形式。组织限定别名 https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> 同样有效，不应改写或对其做 lint。页面移动或重命名后 GitBook 会自动创建重定向。

使用方式

处理已有内容时，先阅读 SUMMARY.md 获取完整目录与文件层级；若无 SUMMARY.md 则直接浏览目录结构。检查 .gitbook.yaml（根路径、自定义 README/SUMMARY 位置、重定向）、.gitbook/assets/（已上传图片与文件）、.gitbook/vars.yaml（空间级变量）。本地编辑后需在 GitBook 中测试，并保持 SUMMARY.md 与文件结构、页面标题同步。OpenAPI 规范必须通过 UI、API、MCP 或 CLI 上传，不能嵌入 Markdown。

Git Sync

GitBook 与 Git 同步时变更双向流动，合并冲突在 Git 中解决。建议通过 Git 中的 SUMMARY.md 做结构性变更，重大更新使用基于分支的工作流，并审查 GitBook 自动生成的提交。推送分支后，可通过提交状态获取渲染站点的预览链接（修订 id 在导入时生成，每次推送都会更新，不应自行拼接 URL）。

Git Sync 与变更请求内容推送的选择

当空间已配置 Git Sync 且能获取同步仓库的本地检出时，优先直接编辑文件并提交/推送。仅在以下情况使用变更请求内容推送路径：空间尚未配置 Git Sync；当前环境无本地 Git 检出；变更很小且针对性强（如错别字、一段文字、一个字段）。对于新页面树、多页重写、迁移等较大变更，优先使用 Git Sync。

锁定空间

当空间 API 显示 editMode: "locked" 且已配置/激活 gitSync 时，Git 是该空间的真实来源。已有检出时优先 git push；无检出时小范围编辑仍可用变更请求。Git Sync 已配置时不要调用 POST /spaces/{spaceId}/git/import 或 …/git/export（会返回 400）。git push 后需轮询空间 Git Sync 状态等待 webhook 导入完成。空间变量位于 /.gitbook/vars.yaml，不能通过变更请求内容操作设置。已发布的 .md 保留表达式源码而不内联解析值，需通过已发布 HTML、站点预览或 GitBook UI 验证渲染结果。

变更请求的两个链接

若编辑经过变更请求，必须同时报告：变更请求的 diff/编辑器链接（urls.app），以及站点预览链接（Site 对象的 urls.published 或 urls.preview 加上 /~/changes/<number>/）。预览链接不在变更请求响应中，需单独查询。若空间未关联任何已发布站点，应明确说明并只提供 diff 链接。

适用场景

适用于以文件方式维护 GitBook 文档的各类工作流，包括 Git 同步仓库中的文档编辑、本地 Markdown 编辑、IDE 集成，以及通过 MCP 或 REST 进行的内容推送。

限制与注意事项

  • 跨空间链接不能使用相对路径，也不能使用 /spaces/<spaceId>/pages/<pageId> 形式
  • 不要在 SUMMARY.md 中重复引用同一 Markdown 文件
  • 重命名页面标题时需同步更新 SUMMARY.md 的链接文本（除非有意使用引号链接标题覆盖）
  • 自定义块必须正确闭合，开闭标签需完全匹配
  • frontmatter 中含 :、# 等 YAML 特殊字符的 description 值必须加引号，否则会导致 Git Sync 静默失败；但不应要求导出时也保持引号形式，应验证 frontmatter 可解析而非书写形式
  • frontmatter 必须位于文件最顶部
  • 使用 Git Sync 时，README.md 仅通过仓库管理
  • 移动或重命名文件后需测试重定向

参考文件

可按需加载：references/blocks.md（全部块类型语法与示例）、references/frontmatter.md（全部 frontmatter 字段、YAML 引号规则、封面图、条件内容、变量与表达式）、references/markdown.md（标准 Markdown、带标题代码块、数学/TeX、Mermaid 图表、SVG 处理）、references/configuration.md（.gitbook.yaml 选项、.gitbook/ 目录结构、SUMMARY.md 语法）、references/git-sync-serialisation.md（GitBook 导出时重写的内容）、references/git-sync-previews.md（通过 Git Sync 推送分支的预览链接获取）。