write-docs

name	write-docs
metadata	{"version":"1.0"}
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.

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

Need	Use	Why
Sequential, ordered instructions	{% stepper %}	Clear step progression
Alternative options (languages, platforms)	{% tabs %}	User chooses without page clutter
Optional or detailed information	<details>	Keeps page scannable
Important warnings or tips	{% hint %}	Colored callout (info/warning/danger/success)
Side-by-side comparisons	{% columns %}	Parallel layout (max 2 columns)
Timeline or changelog	{% updates %}	Dated entries with tag filtering
Visual navigation cards	<table data-view="cards">	Clickable card grid
Downloadable files	{% file %}	File with caption
Call-to-action links	<a class="button">	Primary or secondary button
Reusable content across pages	{% include %}	Single source of truth
Dynamic content	<code class="expression">	Renders variable values

Variable scope:

If variable is...	Define in...	Access with...
Used across multiple pages	/.gitbook/vars.yaml	space.vars.variableName
Specific to one page	Frontmatter vars:	page.vars.variableName

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.