Write Docs

GitBook Documentation Writing

When to Use This 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

Quick Reference

GitBook Content Structure

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

---
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 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.
• 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
• OpenAPI specs must be uploaded via the UI, API, MCP, or CLI, not embedded in markdown

When to Use Which Block

Variable scope:

Working with Existing Content

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

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

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
• Frontmatter must be at the very top of the file

Working with 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.

Choosing Git Sync vs. a change-request content push

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.

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

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.