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

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.

Locked Git Sync spaces

When the space API shows editMode: "locked" and gitSync is configured/active, the GitBook UI treats Git as the source of truth for that space. Before editing, read those fields (GET /spaces/{spaceId} or equivalent) so you pick the right path.

Rules for locked + synced spaces:

• Prefer git push for content and structure when you have a checkout of the synced repo (same preference as above). Change requests still work for small targeted edits when a checkout is unavailable.
• Do not call POST /spaces/{spaceId}/git/import or …/git/export when Git Sync is already configured — those endpoints return 400 (Cannot use git API when space has a git sync configured). The managed sync webhook handles import/export.
• After git push, wait for the webhook import to finish. Poll space Git Sync status (e.g. GET /spaces/{spaceId}/git/info → operation.state / direction) rather than assuming the published site updated instantly. See references/git-sync-previews.md for branch-preview timing.
• Space variables live in /.gitbook/vars.yaml (or the Library UI). They are not settable via change-request content ops (updateChangeRequestContent has no variables change). Push vars.yaml through Git Sync (or edit in the UI).
• Expressions: published .md keeps <code class="expression">…</code> as source and does not inline resolved values. To verify variables/expressions rendered, check published HTML, the site preview, or the GitBook UI — not the .md export alone.
• Bidirectional sync: merging a change request can export back to the GitHub/GitLab repo. Pull (or keep a clean working tree) before more local commits so Git Sync export does not clobber WIP.

Two links are mandatory whenever a change request is involved

If any part of this edit went through a change request (create_change_request / updateChangeRequestContent, or the REST equivalents), the edit is not done until both of the following have been reported back, every single time — this is a hard rule, not a reminder to skim past:

1. The CR diff/editor link — urls.app on the change-request object, returned by create_change_request, updateChangeRequestContent, or getChangeRequestById.
2. The site preview link — the site URL from the Site object (urls.published when the site is public, else urls.preview) with /~/changes/<number>/ appended. This is never part of the change-request response — it requires a separate lookup — which is exactly why it's the one that gets forgotten. Resolve it every time, not just when it comes to mind. Without the ~/changes/ segment the link is not a preview of the change request — it renders the site's current content, so it will look plausible and be wrong.

This applies no matter which skill pushed the content (this skill or configure-site) and no matter the transport (MCP or REST). See the cr-create skill's "Surfacing the preview link" for the full write-up and the REST resolution steps. MCP equivalent (GitBook MCP has no single ready-made "give me the preview link" call):

1. Resolve the space's organization — invoke_operation("getSpaceById", {path:{spaceId}}) → .organization (skip if you already have the org ID).
2. Find which site the space belongs to — list_sites / get_site_structure, or check each site's site-spaces for a match on .space.id.
3. invoke_operation("getSiteById", {path:{organizationId, siteId}}) → .urls.published (once the site is live), else .urls.preview. Append /~/changes/<number>/, stripping the trailing slash the API returns.

If the space isn't attached to any published site, say so plainly and give only the diff link — don't quietly drop the preview line without explanation.

This has already failed silently in practice: an edit was pushed and merged with only the diff link reported, and the preview link only surfaced when a person asked for it directly. Treat the two-link checklist above as literal.

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.
• references/git-sync-serialisation.md — what GitBook rewrites when it exports a space back to the repo: description: scalar style, cross-space link URL form, block re-serialisation, and the rule that you lint for validity rather than for form. Load when a Git Sync diff contains changes nobody made by hand, or before writing any check or build step that validates docs frontmatter or links.
• references/git-sync-previews.md — getting a preview link for a branch pushed through Git Sync: reading the GitBook commit status on GitHub and GitLab, telling the site preview from the editor diff, and handling an import that's still running. Load whenever you push docs changes to a branch with a pull/merge request open.