updateChangeRequestContent

write-docs

references/api-cheatsheet.md

• GitBook MCP — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (a full site build, ongoing restructuring — not a one-off tweak), offer to set it up:

  claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp

  (then

  /mcp

  to complete OAuth sign-in — or append

  --header "Authorization: Bearer $GITBOOK_TOKEN"

  to skip the browser flow). Codex equivalent:

  codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp

  . Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
• REST API (

  https://api.gitbook.com/v1

  ) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs

  GITBOOK_TOKEN

  as a bearer header on every request.

[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"

GITBOOK_TOKEN

1. Tell them they need a GitBook personal access token. Direct them to https://app.gitbook.com/account/developer to create one.
2. Ask them to paste the token into the conversation. Immediately export it as an environment variable (

   export GITBOOK_TOKEN=<pasted value>

   ) and don't repeat it back in your response.
3. Do not proceed with any API calls until the token is confirmed present in the environment.

1. Claude scaffolds a Git repo locally (and, when tooling permits, the remote)
2. Claude creates the site, sections, and any empty spaces it can
3. The user does a short, well-scripted UI step in GitBook to wire each space to its directory in the repo
4. Claude applies branding/customization

references/git-sync-handoff.md

references/api-cheatsheet.md

• Organization — list the user's orgs and show the list to the user, then ask them to confirm which one is the target by name. Do this even if they have only one org — confirming once up front is cheap insurance against creating sites in the wrong place. Save the chosen

  organizationId

  for the rest of the session and refer to the org by its title (not its UUID) when narrating subsequent steps.
• Site plan and visibility — default to

  type: site

  on the Ultimate plan, public visibility, unless the user explicitly says otherwise. Most real customers want the Ultimate feature set (custom domain, AI Assistant, advanced customization, hidden GitBook trademark, custom fonts, custom logos). The free tier (

  type: basic

  ) is appropriate only for clearly low-stakes use cases like solo open-source side projects. If you're unsure, ask: "I'll set this up on the Ultimate plan unless you'd prefer the free tier — should I downgrade?" — Ultimate features that are silently absent on

  basic

  (no AI assistant, no custom fonts, no custom domain) are a much bigger user surprise than briefly confirming the plan.
• The content seed — what's the site being built from? Common shapes:
  • A folder of existing markdown — the cleanest starting point
  • A handful of notes plus a competitor's site as a reference
  • Just a description of what they want to document
  • An existing site they want to restructure (in which case fetch the site's current structure first)
  • A migration from another docs platform (Mintlify, Docusaurus, ReadTheDocs, GitBook v1) — see

    references/migration-from-other-platforms.md

    for the workflow. Migration is its own discipline; don't treat it as a glorified file copy.
• OpenAPI spec for the API reference — if the site has any API reference content, ask up front whether they have an OpenAPI spec (or whether one can be generated from their codebase). If yes, the API reference space is one

  builtin:openapi

  SUMMARY entry plus a one-paragraph overview README per resource — dramatically less work than hand-authored endpoint pages, and never drifts. See

  references/block-ecosystem.md

  and

  references/api-cheatsheet.md

  for the workflow. Don't default to hand-authored endpoint pages — they're almost always the wrong call.
• Branding — at minimum, primary color (hex). Optionally: logo URLs (light + dark), favicon, font choice (or one of GitBook's defaults), header links, footer text/links, theme preset (

  clean

  ,

  muted

  ,

  bold

  ,

  gradient

  ). For Ultimate sites, also consider AI-assistant starter prompts (3-5 short questions visitors are likely to ask).
• Site structure — sections, not site-spaces. If the site has more than one space, plan the section list with the user explicitly: each section has a title, a Font Awesome icon name, and a description. Section icons and descriptions are first-class navigation furniture — visitors see them — and gathering them up front saves a follow-up update per section later. Example:

  [{title: "Guides", icon: "book-open", description: "Concepts and tutorials"}, {title: "API Reference", icon: "code", description: "REST API and SDKs"}, {title: "Changelog", icon: "clock-rotate-left", description: "Updates and release notes"}]

  .
• Git remote preference — GitHub, GitLab, or local-only. Check whether

  gh

  or

  glab

  are installed before asking. If neither tool is available, say so explicitly and offer two paths: (1) commit locally and put the "create the remote and push" step at the top of the user's handoff, or (2) ask the user to install the tool. Don't quietly default to local-only without telling them — they'll have a repo with no remote and no instructions.
• Site shape — single space or multi-space. Multi-space sites use sections to group spaces in the navigation; this is the right choice when content has clearly distinct audiences (e.g. user docs + API reference + changelog). Use site-spaces directly only for translation variants — see

  references/api-cheatsheet.md

  .

1. Resolve and echo the source. State exactly what you're about to read (repo URL and branch, folder path, or site URL) and show the user its top-level contents — a short file or page list — so they can confirm it's the right one.
2. If you can't access it, stop and say so. Git hosts return 404 for private repositories — indistinguishable from "repository doesn't exist." Treat any 404 or clone failure on a user-named repo as possibly private: tell the user what failed, and ask them to either make the content reachable (local clone, archive, authenticated

   gh

   /

   glab

   , public mirror) or correct the URL. Check whether an authenticated

   gh

   /

   glab

   CLI is available before declaring the repo unreachable.
3. Never substitute a source. Do not search for, guess, or fall back to a similarly-named repository or site — even one that looks identical. Building a docs site from the wrong source is far worse than pausing to ask. Any change of source requires the user's explicit sign-off.

About to run, in org Acme Inc (

org_abc123

):

• Create site "Acme Platform Docs" (type: site, plan: ultimate, visibility: public)
• Create 3 empty spaces: Guides, API Reference, Changelog
• Add Guides as the default section; create sections for API Reference and Changelog

Proceed? (yes/no)

write-docs

updateChangeRequestContent

create_change_request

submit_or_merge_change_request

invoke_operation

1. The change request's diff/editor link (

   urls.app

   ) — the link to review the change in the GitBook app.
2. The site preview link — the rendered docs with the change applied. This takes a separate lookup: the site URL lives on the Site object (

   urls.published

   when the site is public, else

   urls.preview

   ), not the change-request object, and you must append

   /~/changes/<number>/

   to it, stripping the trailing slash the API returns. Without that segment the link renders the site's current content rather than this change request — it loads fine and shows the wrong thing.

write-docs

cr-create

getSpaceById

list_sites

get_site_structure

getSiteById

.urls.preview

GET

1. The space list — one space per coherent body of content. Keep it small (1–4 spaces is typical). A space is a unit of navigation and Git Sync, so don't split a single audience's content across spaces.
2. The section grouping (if multi-space) — sections are top-level partitions in the site nav, e.g. "Product" / "Developers" / "Resources". A section can hold one or more spaces.
3. The page tree per space — folders and pages, with one or two sentence summaries of each page. The depth should match the content; shallow trees (1–2 levels) are usually best.

references/site-structure-design.md

README.md

SUMMARY.md

.gitbook/

.gitbook.yaml

my-docs/
├── .gitignore
├── README.md                    # repo-level readme (not a space homepage)
├── guides/                      # space 1
│   ├── README.md                # space homepage
│   ├── SUMMARY.md
│   ├── .gitbook/
│   │   └── vars.yaml            # optional: space-level variables
│   ├── getting-started/
│   │   ├── installation.md
│   │   └── quickstart.md
│   └── concepts/
│       └── ...
├── api-reference/               # space 2
│   ├── README.md
│   ├── SUMMARY.md
│   └── endpoints/
│       └── ...
└── changelog/                   # space 3
    ├── README.md
    └── SUMMARY.md

• .gitbook.yaml

  is optional. GitBook works fine on the default convention of

  README.md

  +

  SUMMARY.md

  per space. Only add a

  .gitbook.yaml

  when you need to override the root, define redirects, or do something else non-default. The bundled example site (

  references/example-site/

  ) has zero

  .gitbook.yaml

  files and works perfectly.

• .gitbook/vars.yaml

  holds space-scoped variables that pages can reference inline (e.g.

  support_email: support@evolve.com

  referenced as

  {% vars.support_email %}

  ). Useful for any value that appears on many pages.

• .gitbook/includes/<name>.md

  holds reusable content blocks — a snippet you embed in many pages with

  {% include "...persona-switcher" %}

  . Use these instead of copy-pasting boilerplate.
• The space directory name (e.g.

  guides/

  ) is what the user enters into the "Project directory" field when wiring up Git Sync.

.gitbook.yaml

root: ./
structure:
  readme: README.md
  summary: SUMMARY.md

1. Gather the desired navigation from the user during structure design. Ask them — explicitly — to enumerate the top-level pages and the named groups for each space. This is the place where you make folder names match nav reality, and where the user can tell you "actually I want Authentication as a top-level page, not under Concepts."
2. Lay out folders to match the agreed nav, not the other way around. If the user wants three groups in a space — "Getting started", "Concepts", "Tutorials" — the space directory has three subfolders by those names (slugified), each with its own pages. Don't auto-extract a fourth group from a stray subfolder.
3. Write SUMMARY.md to the explicit shape the user agreed. The grammar that GitBook honors:
   markdown

   # Table of contents
   
   * [Space homepage](README.md)
   * [Top-level page A](top-level-a.md)
   * [Top-level page B](top-level-b.md)
   
   ## First group
   
   * [Page in group](first-group/page.md)
   * [Another page](first-group/another.md)
   
   ## Second group
   
   * [Page](second-group/page.md)

   Key shape rules:
   • README.md is on its own line at the very top, as a sibling, not a parent. Other top-level pages follow as siblings.

   • ## Group name

     headings introduce groups. Pages in a group are flat bullets directly under the heading — not indented under the README.
   • Avoid mechanical " README.md" + nested-everything-under-it.* That collapses the entire nav into one tree under the homepage and makes every page look like a sub-page of the homepage in the sidebar.
   • Group names come from the user, not the folder names. "concepts/" can be the folder slug, but the group heading might be "How it works" if that's clearer.
   • One bullet per page, no extra formatting. No bold, no descriptions in the SUMMARY — those live in the page frontmatter.
4. Special-case patterns that aren't plain bullets:
   • OpenAPI auto-generated endpoint pages use a fenced YAML block as the bullet content (

     type: builtin:openapi

     — see

     references/api-cheatsheet.md

     ).
   • External links are

     * [Title](https://...)

     and render as outbound links in the nav.
   • Cross-space links in SUMMARY.md use the same

     https://app.gitbook.com/s/<spaceId>/<path>

     form as in body content. Path has no

     .md

     suffix. During scaffolding write the sentinel form (

     XSPACE_<KEY>

     ); resolve after space creation. See

     references/cross-space-links.md

     .

README.md

SUMMARY.md

write-docs

• Frontmatter including the

  icon:

  field. Icons are Font Awesome names without the

  fa-

  prefix (e.g.

  book-open

  ,

  bolt

  ,

  house

  ,

  code

  ,

  puzzle-piece

  ,

  id-card

  ,

  circle-dollar-to-slot

  ). Don't invent names — pick from the Font Awesome catalogue. The example site uses these in nearly every page's frontmatter.
• Layout flags including

  layout: width: wide

  (use selectively — on marketing-style landing pages, on changelog pages with the Updates timeline, on pages with multi-column blocks or genuinely wide tables. Don't default to wide for every space homepage — the GitBook default width is right for documentation, including documentation landing pages with card-tables. Wide is for hero-style marketing layouts, not normal docs.),

  cover:

  images, and per-page visibility flags (

  title.visible

  ,

  tableOfContents.visible

  , etc.).

• SUMMARY.md

  grammar. Strict format — one bullet per page, optional

  ## Group name

  headings, no extra formatting. Plus the special

  type: builtin:openapi

  syntax for auto-generating endpoint pages from a spec.
• Rich blocks — tabs, hints, steppers, columns, card-tables, expandables, embeds, conditional content with

  {% if visitor.claims... %}

  , the OpenAPI block, the Updates block (changelog), reusable content includes.
• GitBook-flavoured markdown differences from CommonMark.

references/example-site/

• Changelogs →

  {% updates %}

  block with

  {% update date="..." tags="..." %}

  entries. Auto-generates RSS, supports tags (defined in

  .gitbook/tags.yaml

  ). Don't write

  ## YYYY-MM-DD

  headings — that's the wrong shape.
• API endpoint references → OpenAPI spec uploaded once, auto-generated pages via

  type: builtin:openapi

  in SUMMARY.md. Don't hand-author endpoint pages — they drift, and the spec is canonical anyway. If the user doesn't have a spec, offer to draft a minimal one rather than going prose-y.
• State machines, flows, sequences, simple architecture →

  ```mermaid

  fenced blocks. Don't draw boxes-and-arrows in ASCII; Mermaid is supported, renders cleanly, and is screen-reader friendly.
• Space homepages → use the GitBook default layout for normal docs landings (TOC visible, default width). Reach for

  layout: width: wide

  only when the page is genuinely marketing-style — a hero image, an unusually large card grid, a multi-column dashboard layout. The default is right for docs.
• "Choose your path" content → card-tables (

  <table data-view="cards">

  ). The HTML is verbose but the visual result beats any markdown alternative.
• Side-by-side intro patterns →

  {% columns %}

  block. Two columns at 50/50 is the standard.
• Repeated boilerplate (3+ places) →

  .gitbook/includes/<name>.md

  +

  {% include "..." %}

  .
• Repeated literals (env URLs, support email, version pin) →

  .gitbook/vars.yaml

  +

  <code class="expression">space.vars.<name></code>

  .
• Multi-language code samples →

  {% tabs %}

  block.
• Walkthroughs of 3+ ordered steps →

  {% stepper %}

  block.

references/block-ecosystem.md

For the conceptual side, see the [Authentication concept page](https://app.gitbook.com/s/<spaceId>/concepts/authentication).

https://app.gitbook.com/s/<spaceId>/<path>

ContentRefPage

ContentRefSpace

1. During scaffolding, write cross-space links using a sentinel space-ID prefixed with

   XSPACE_

   , one per planned space. Use the space slug from your structure plan as the suffix:
   markdown

   See the [Authentication concept page](https://app.gitbook.com/s/XSPACE_GUIDES/concepts/authentication).
   For the full reference, see the [API Reference](https://app.gitbook.com/s/XSPACE_API/).

   These are valid markdown links to non-existent GitBook spaces — they don't break the parser, they're easy to grep for, and they round-trip cleanly through Git.
2. After space creation, once you have each new space's real ID, walk every markdown file and substitute

   XSPACE_<KEY>

   with the real space ID:
   bash

   sed -i \
     -e "s|XSPACE_GUIDES|${GUIDES_SPACE_ID}|g" \
     -e "s|XSPACE_API|${API_SPACE_ID}|g" \
     -e "s|XSPACE_CHANGELOG|${CHANGELOG_SPACE_ID}|g" \
     $(find . -name '*.md' -not -path './.git/*')

3. Commit and push the resolution. GitBook will pick it up via Git Sync and the links will resolve on the next render.

cross-space-links.yaml

references/cross-space-links.md

app.gitbook.com/s/<id>/...

references/example-site/

connections/

references/example-site/PRUNE-NOTES.md

• The full structural backbone of every space is intact —

  README.md

  ,

  SUMMARY.md

  ,

  .gitbook/vars.yaml

  ,

  .gitbook/includes/

  .

• developers/v2/

  is kept in full as the canonical example.

  developers/v1/

  (legacy) and

  developers/v3/

  (beta) were dropped — they were structurally identical to v2 with version-specific content variations. The pattern of multi-version API docs is documented in PRUNE-NOTES.md and visible in

  structure.json

  .

• connections/

  — each subfolder (

  blog/

  ,

  community/

  ,

  youtube/

  ) keeps its

  index.html

  plus one representative article so the metadata patterns stay learnable.

• customization.json

  and

  structure.json

  are the complete API exports describing the entire original site, including spaces and pages that were pruned. SUMMARY.md files inside each space also describe the original tree — some links in them point to pruned pages, which is expected.

changelog/README.md

changelog/.gitbook/tags.yaml

builtin:openapi

developers/v2/SUMMARY.md

products/payments/concepts/payment-lifecycle.md

developers/v2/identity-api/README.md

width: wide

home/README.md

developers/v2/README.md

home/README.md

partners/README.md

{% if visitor.claims... %}

products/payments/accept-payments/take-a-payment.md

developers/v2/getting-started/quickstart.md

developers/v2/getting-started/authentication.md

developers/v2/webhooks/verifying-signatures.md

home/.gitbook/includes/persona-switcher.md

.gitbook/vars.yaml

.gitbook/vars.yaml

## Heading

SUMMARY.md

structure.json

cd my-docs
git init
git add .
git commit -m "Initial scaffold"

gh

glab

undefined

1. Verify access and find the org: confirm the authenticated user, then list the orgs.
2. Create the site with

   {title, type, visibility, spaces?}

   . Default to Ultimate (

   type: "site"

   ; the plan tier is set on the site after creation or via the org's billing). Use

   type: "basic"

   (free) only when the user explicitly opts in. Don't include

   spaces

   if no spaces exist yet — you can add them later.
3. Decide how spaces will come into being. Two paths:
   • Git-Sync-first (recommended): tell the user to create each space in the GitBook UI by clicking "Add new space" → "Sync to a GitHub or GitLab repository", picking the repo and the per-space project directory. This creates the space, sets up sync, and links it to the site in one action. The skill's job is to give exact, copyable instructions (one block per space). See

     references/git-sync-handoff.md

     .
   • Programmatic-first: create empty spaces directly, add them to the site as site-spaces, and use content import or template application to load content. The user will still need to wire Git Sync in the UI later if they want bidirectional sync.
4. Add sections (multi-space sites with grouped navigation): a section is created by associating a space with a title and optional icon.
5. Resolve cross-space link sentinels: if the scaffolded markdown contains

   XSPACE_<KEY>

   placeholders (which it should, for any link that crosses a space boundary), now is when you substitute them for the real space IDs returned by step 3 or 4. See

   references/cross-space-links.md

   for the substitution script. Commit and push the changes — the next Git Sync run picks them up.
6. Apply customization (branding) — the full schema is broad: theme preset, colors (each as a

   {light, dark}

   themed pair), favicon, header (logo, primaryLink, links), footer (groups of links, copyright), themes (default light/dark, toggleable), AI mode, PDF export, and more. Recipes for common branding scenarios are in

   references/customization-recipes.md

   . Only change the fields you mean to — fetch the current settings first, modify in memory, and write the full result back rather than guessing at a partial payload.
7. Verify: fetch the site's structure to confirm the final tree, and its customization to confirm settings.

site-space

language

gitSync

• Don't scaffold per-language directories in the repo. The Git repo has one space per topic, in English. The skill writes one set of markdown files per content area, full stop.
• Each section can hold many site-spaces. A "Payments" section might contain

  Payments

  (en, git-synced),

  Payments (FR)

  (fr, computed),

  Payments (DE)

  (de, computed), etc. The structure response will list all of them; only the English ones need a Git Sync handoff.

• localizedTitle

  shows up everywhere. Sections, section-groups, header links, footer links, and the site title itself all carry a

  localizedTitle: {de: "...", fr: "...", ...}

  map. When reading the customization, expect to see translations even for fields the user only set in English. Don't strip these out unless asked.
• Auto-translation is a UI-only feature today. If the user wants it enabled on a section, surface that as part of the Git Sync handoff: "After Git Sync is configured, go to Site → Sections → Payments → Translations and enable the languages you want."

1. Site-spaces at the root (a flat site, no sections)
2. Sections containing site-spaces (the typical multi-space site)
3. Section groups containing sections containing site-spaces (used to bucket related sections, e.g. "Products" group containing Payments / Identity / Connect sections)

sections

• Site metadata
• Structure (sections + spaces)
• Customization (site-level or per-site-space), for branding

• Content import is for ingesting external content (a website URL, a set of files) into a space. It's good for one-shot migrations from another doc tool.
• Git Sync is for ongoing two-way sync between a Git repo and a space. This is what we're optimizing for in the standard flow.
• If the user has already-good content sitting outside both Git and GitBook (e.g. a Notion export), import it, then optionally turn on Git Sync afterward.

1. The repo URL
2. The branch name (usually

   main

   )
3. The project directory for that space (e.g.

   guides

   ,

   api-reference

   )
4. The initial sync direction — almost always GitHub → GitBook (or GitLab → GitBook), since the repo is the source of truth at this point

references/git-sync-handoff.md

• Don't put the PAT in any file Claude writes. Always read it from the environment.
• Don't silently swap the content source. If the repo or folder the user named can't be read (remember: private repos return 404, same as nonexistent ones), stop and ask — never proceed with a lookalike public repo. See "Verify the content source before building."
• Don't try to set up Git Sync programmatically. It's UI-only regardless of transport — always route through the UI handoff.
• Don't paste an entire customization payload from memory. Fetch the current state, modify it, then write the full result back. Schemas evolve and you'll write fewer bugs this way.
• Don't create a space for every section of content. A space is a heavy unit (it has its own URL slug, sync, settings). Pages and folders within a space are the right tool for sub-grouping.
• Don't skip the structure-plan-and-confirm step, even when the user is in a hurry. Restructuring a published site is painful.
• Don't over-format the SUMMARY.md. GitBook's parser is strict about it. Defer to the rules in

  write-docs

  .
• Don't finish a change-request edit without both links. See "After a change-request push: two links are mandatory" — the CR diff link alone is an incomplete answer.

• references/api-cheatsheet.md

  — the complete set of API calls used by this skill, with curl-style request bodies and expected responses

• references/site-structure-design.md

  — heuristics and worked examples for going from raw inputs to a space/section/page plan

• references/migration-from-other-platforms.md

  — pre-flight, source-platform mappings (Mintlify, Docusaurus, GitBook v1, RTD), anchor-pages strategy, format-pass, internal-link sweep. Read this before any migration build, not after.

• references/block-ecosystem.md

  — which GitBook block to reach for in which content situation, with a decision table and worked examples (Updates, Mermaid, OpenAPI auto-gen, layout flags, card-tables, conditional content, includes, vars). Read this before generating any non-trivial page.

• references/cross-space-links.md

  — the sentinel-and-resolve workflow for cross-space links in markdown, with a working substitution script

• references/git-sync-handoff.md

  — the template for the user-facing Git Sync setup instructions

• references/customization-recipes.md

  — worked branding payloads for common scenarios

• references/example-site/

  — a pruned snapshot (~150 files) of a real production-style GitBook site repo (markdown,

  SUMMARY.md

  s,

  .gitbook/

  configs). Read

  PRUNE-NOTES.md

  inside it first — it explains what's kept, what's dropped, and lists high-signal files for specific patterns.

• references/example-site/customization.json

  — the customization export from that site, illustrating a complete real-world branding payload

• references/example-site/structure.json

  — the structure export, showing sections, section-groups, and multi-language site-spaces (English git-synced + auto-translated)