Update to GitBook

{
  "name": "write-docs",
  "description": "Write, author, edit, and format GitBook documentation pages in Git-synced repos, IDEs, or any text editor. Use whenever a task involves creating or editing a GitBook markdown page, writing or updating a README.md or SUMMARY.md, inserting a hint, tab, stepper, card, or other GitBook block, configuring page frontmatter or layout options, setting up variables or expressions, or formatting content for GitBook outside the GitBook UI.",
  "included_files": [
    {
      "relative_path": "references/blocks.md",
      "size_in_bytes": 13034
    },
    {
      "relative_path": "references/configuration.md",
      "size_in_bytes": 4434
    },
    {
      "relative_path": "references/frontmatter.md",
      "size_in_bytes": 6752
    },
    {
      "relative_path": "references/markdown.md",
      "size_in_bytes": 5077
    }
  ],
  "skill_md_contents": "---\nname: write-docs\nmetadata:\n  version: \"1.0\"\ndescription: \"Write, author, edit, and format GitBook documentation pages in Git-synced repos, IDEs, or any text editor. Use whenever a task involves creating or editing a GitBook markdown page, writing or updating a README.md or SUMMARY.md, inserting a hint, tab, stepper, card, or other GitBook block, configuring page frontmatter or layout options, setting up variables or expressions, or formatting content for GitBook outside the GitBook UI.\"\n---\n\n### When to Use This Skill\n\nUse this skill when working with GitBook documentation through:\n\n* Git-synced repositories (GitHub, GitLab)\n* Local markdown editors\n* IDE integrations\n* Any environment where you're editing GitBook content as files rather than through the GitBook UI\n\n### Quick Reference\n\n#### GitBook Content Structure\n\nGitBook organizes content through pages, spaces, and collections:\n\n* **Pages** are individual markdown files that make up your documentation\n* **Spaces** are collections of pages organized into a documentation site\n* **Collections** are groups of spaces\n\n**File structure:**\n\n```\n/\n  .gitbook/\n    assets/              # GitBook-managed images and files\n    includes/            # Reusable content blocks\n    vars.yaml            # Space-level variables\n  .gitbook.yaml          # Configuration\n  README.md              # Homepage\n  SUMMARY.md             # Table of contents\n  getting-started/\n    installation.md\n    quickstart.md\n  api-reference/\n    authentication.md\n    endpoints.md\n```\n\n**Frontmatter fields (quick form):**\n\n```markdown\n---\ndescription: \"Page description for SEO\"\nicon: book-open\nhidden: true\nvars:\n  page_variable: value\nlayout:\n  width: default  # or 'wide'\n  tableOfContents:\n    visible: true\n  pagination:\n    visible: true\n---\n```\n\n**Variables and expressions:**\n\n* Space variables: `/.gitbook/vars.yaml`\n* Page variables: Frontmatter `vars:`\n* Expression syntax: `<code class=\"expression\">space.vars.variableName</code>`\n\n**Most common custom blocks:**\n\n* `{% tabs %}...{% endtabs %}` — for alternatives\n* `{% hint style=\"...\" %}...{% endhint %}` — callouts (info/warning/danger/success)\n* `{% stepper %}...{% endstepper %}` — sequential steps\n* `<details>...<summary>...</details>` — expandable content\n\n**Links:**\n\n* External: `[text](https://example.com)`\n* Relative (same space): `[text](page.md)`, `[text](../folder/page.md)`\n* Cross-space (different space): `[text](https://app.gitbook.com/s/<spaceId>/<path>)` — relative paths never cross space boundaries, and this is the only correct URL form (not `/spaces/<id>/pages/<id>`). 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`.\n* Moved/renamed pages keep working — GitBook auto-creates a redirect from the old path.\n\n**Key reminders:**\n\n* Read SUMMARY.md first when working with existing content\n* Test in GitBook after editing locally\n* Keep SUMMARY.md synchronized with your file structure\n* OpenAPI specs must be uploaded via the UI, API, MCP, or CLI, not embedded in markdown\n\n### When to Use Which Block\n\n| Need | Use | Why |\n|---|---|---|\n| Sequential, ordered instructions | `{% stepper %}` | Clear step progression |\n| Alternative options (languages, platforms) | `{% tabs %}` | User chooses without page clutter |\n| Optional or detailed information | `<details>` | Keeps page scannable |\n| Important warnings or tips | `{% hint %}` | Colored callout (info/warning/danger/success) |\n| Side-by-side comparisons | `{% columns %}` | Parallel layout (max 2 columns) |\n| Timeline or changelog | `{% updates %}` | Dated entries with tag filtering |\n| Visual navigation cards | `<table data-view=\"cards\">` | Clickable card grid |\n| Downloadable files | `{% file %}` | File with caption |\n| Call-to-action links | `<a class=\"button\">` | Primary or secondary button |\n| Reusable content across pages | `{% include %}` | Single source of truth |\n| Dynamic content | `<code class=\"expression\">` | Renders variable values |\n\n**Variable scope:**\n\n| If variable is... | Define in... | Access with... |\n|---|---|---|\n| Used across multiple pages | `/.gitbook/vars.yaml` | `space.vars.variableName` |\n| Specific to one page | Frontmatter `vars:` | `page.vars.variableName` |\n\n### Working with Existing Content\n\n1. **Read SUMMARY.md first** — complete table of contents and file hierarchy\n2. **If no SUMMARY.md** — browse the directory structure directly\n3. **Check .gitbook.yaml** — root path, custom README/SUMMARY locations, redirects\n4. **Check .gitbook/assets/** — uploaded images and files\n5. **Check .gitbook/vars.yaml** — space-level variables\n\n### Common Pitfalls\n\n**Cross-space links:**\n\n* Don't use relative paths to link to a page in a different space — they won't resolve.\n* Don't use `/spaces/<spaceId>/pages/<pageId>` — that's not a valid GitBook link form.\n* 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.\n* Use `XSPACE_<KEY>` sentinels when space IDs aren't known yet (new space, not yet created).\n\n**File organization:**\n\n* Don't reference the same markdown file twice in SUMMARY.md\n* Keep file paths consistent between SUMMARY.md and actual file locations\n\n**Configuration:**\n\n* When using Git Sync, manage README.md only through your repository\n* Test redirects after moving or renaming files\n\n**Custom blocks:**\n\n* Always close blocks properly (`{% endtab %}`, `{% endhint %}`, etc.)\n* Match opening and closing tags exactly\n\n**Frontmatter:**\n\n* Always quote `description:` values containing `:`, `#`, or other YAML-significant characters — unquoted special characters cause silent Git Sync failures with no error message\n* Frontmatter must be at the very top of the file\n\n### Working with Git Sync\n\nWhen 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.\n\n**Best practices:** make structural changes via SUMMARY.md in Git; use branch-based workflows for significant updates; review auto-generated commits from GitBook.\n\n#### Choosing Git Sync vs. a change-request content push\n\nWhen 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.\n\nReach 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:\n\n- the space has no Git Sync configured yet (e.g. a brand-new space still mid-setup),\n- there's no local Git checkout available in the current environment (no filesystem access to the synced repo), or\n- 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.\n\nFor 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.\n\nWhichever path pushes the change, surface the CR's rendered site preview link (not just the editor/diff link) before wrapping up — see the `cr-create` skill's \"Surfacing the preview link.\" It isn't part of the change-request response itself, so it's easy to forget.\n\n### Reference files\n\nLoad these on demand when the task requires deeper detail:\n\n- `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.**\n- `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.**\n- `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.**\n- `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.**\n"
}