Write Docs

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 /spaces/<id>/pages/<id> is not a valid link form. The org-qualified alias https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> resolves the same way — write the short form, but don't rewrite or lint against either (references/git-sync-serialisation.md). 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 and page titles
• 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.
• Don't "fix" the org-qualified form https://app.gitbook.com/o/<orgId>/s/<spaceId>/<path> when you find it — it's a valid alias, and normalising between the two forms churns against Git Sync.
• 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
• When you rename a page's title (its # heading or title frontmatter), also update SUMMARY.md's link text for that page — it drives the sidebar nav, pagination, and relative link text, and won't update itself. Skip this only if the SUMMARY.md entry intentionally uses the quoted link-title override ([Page main title](page.md "Page link title")) to show something different on purpose.

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
• But don't require quotes on the way back out: GitBook re-emits descriptions in whatever YAML scalar style its serialiser picks, including folded blocks (>-). Validate that frontmatter parses, not how it's written (references/git-sync-serialisation.md)
• 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.

Previewing a pushed branch

The two-link rule below covers content pushed through a change request. When you push through Git instead, the equivalent is the commit status: opening a pull/merge request — or pushing to a branch that already has one — makes GitBook import that branch and post a status linking a preview of the rendered site. Give the user that link whenever you push docs changes, without being asked. Read it off the commit status rather than building a URL: the revision id is minted at import time and can't be derived from the branch or the PR, and every push mints a new one, so an earlier link goes stale. See references/git-sync-previews.md for the GitHub and GitLab commands and what to do while the import is still running.

Choosing Git Sync vs. a change-request content push