Terminal
Terminal/Skill
Guides writing and formatting GitBook pages and SUMMARY.md files in Git-synced repos or any editor, including GitBook blocks.
By GitBook
Works with
npx skills add gitbookio/gitbook-skills --skill write-docsUse this skill when working with GitBook documentation through:
GitBook organizes content through pages, spaces, and collections:
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:
/.gitbook/vars.yamlvars:<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 contentLinks:
[text](https://example.com)[text](page.md), [text](../folder/page.md)[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.Key reminders:
| 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 |
Cross-space links:
/spaces/<spaceId>/pages/<pageId> — that's not a valid GitBook link form.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.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.XSPACE_<KEY> sentinels when space IDs aren't known yet (new space, not yet created).File organization:
# 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:
Custom blocks:
{% endtab %}, {% endhint %}, etc.)Frontmatter:
description: values containing :, #, or other YAML-significant characters — unquoted special characters cause silent Git Sync failures with no error message>-). Validate that frontmatter parses, not how it's written (references/git-sync-serialisation.md)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.
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.
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:
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.
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:
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.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./.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)..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.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:
urls.app on the change-request object, returned by create_change_request, updateChangeRequestContent, or getChangeRequestById.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):
invoke_operation("getSpaceById", {path:{spaceId}}) → .organization (skip if you already have the org ID).list_sites / get_site_structure, or check each site's site-spaces for a match on .space.id.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.
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.