configure-site — скилл для Claude Code: сайты GitBook под ключ

---
name: configure-site
metadata:
  version: "1.0"
description: "Create and maintain GitBook documentation sites end-to-end — design structure from source content, scaffold a Git monorepo, set up the GitHub/GitLab remote, drive the GitBook API (REST or MCP) to create the site/sections/spaces, apply branding, and hand off the one UI step (Git Sync) that GitBook does not expose programmatically. Prefer site-level Git Sync (gitbook-docs.yaml mapping every space) over per-space sync unless a space needs its own repo or branch. Use when spinning up a new docs site, restructuring or extending one, linking a site or spaces to Git, changing branding (logo, colors, fonts, header/footer), or programmatically managing spaces, sections, or site-spaces. Defers page authoring to the companion `write-docs` skill."
---

# Configure GitBook Site

A skill for creating and maintaining entire GitBook documentation sites. Where `write-docs` covers what goes inside a single page, this skill covers everything around the pages: structure design, repo scaffolding, the GitBook API, and branding. Use the two skills together — this one calls into `write-docs` whenever it needs to generate or edit page content.

## How you can talk to GitBook

There's more than one way to drive GitBook — GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer **MCP first**: if GitBook MCP tools are already connected, use them for anything they cover (creating/configuring sites, opening change requests, drafting and editing content, restructuring docs) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

**"MCP first" is about transport, not about bypassing Git Sync for content.** MCP exposes a change-request content-push tool (`updateChangeRequestContent`) that's tempting to reach for anytime it's connected — but for spaces that already have Git Sync configured, pushing content by editing files in the local repo and letting Git Sync carry it to GitBook is still the preferred path for anything beyond a small, targeted edit. Use the change-request push (MCP or REST) instead when the space isn't Git-synced, there's no local checkout available in the environment, or the edit is small enough that opening a CR is proportionate. See `write-docs`'s "Choosing Git Sync vs. a change-request content push" for the full rule — it applies here too.

The steps in this skill are described as outcomes ("list the orgs", "create the site", "add a section") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints, request bodies, and expected responses for each step are in `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.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer token for both. MCP additionally supports OAuth as a friendlier alternative to pasting a token.

**If you end up needing a token** (REST API path, or MCP without OAuth), check for it at the start of the session:

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

If `GITBOOK_TOKEN` is not set, ask the user directly:
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.

Never write the token to a file, never echo it back in a response, never commit it.

## The fundamental constraint

The most important thing to internalize before doing anything: **GitBook can do almost everything except set up Git Sync, regardless of transport**. Authorizing GitHub/GitLab, picking the repository, choosing the branch, and choosing the initial sync direction are all UI-only operations — both the REST API and MCP (which wraps it) only let you *read* the resulting Git Sync state, never set it up. There's an API operation, `installGitSyncProviderOnTarget`, that targets either a site or a space, but the account-connection (OAuth) step still has to happen in the app, and it isn't yet exposed through GitBook's MCP server — treat it as not-yet-usable rather than building a flow around it.

**Git Sync now configures at the site level, and that's the default to reach for.** One connection (one repo, one branch) covers the whole site; `gitbook-docs.yaml` maps each space to its own directory, which is the same shape this skill already scaffolds a monorepo into. Per-space Git Sync still exists, but it's now the exception — reach for it only when a specific space needs an independent repo or branch (e.g. a private space that can't live in the public docs repo).

That means the cleanest end-to-end flow is always:

1. Claude scaffolds a Git repo locally as a monorepo (one directory per space), ideally with `gitbook-docs.yaml` pre-authored mapping each space to its directory, and pushes the remote when tooling permits
2. Claude creates the site, sections, and any empty spaces it can
3. **The user does one short, well-scripted UI step in GitBook: connect the site to the repo/branch and confirm the space-to-directory mapping** — not one step per space
4. Claude applies branding/customization

The user's role in step 3 is unavoidable but should never be a surprise — generate clear, copy-paste-ready instructions for them. Reference: `references/git-sync-handoff.md`.

If the user explicitly does not want Git Sync, fall back to the content-import path (content import and template application) — covered briefly below and in `references/api-cheatsheet.md`.

## Inputs you should gather up front

Don't start scaffolding until these are known. If something is missing, ask once with a focused question rather than guessing. (Auth is handled separately — see "How you can talk to GitBook" above.)

- **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: "ultimate"`** (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`.

## Verify the content source before building

Once the user names a content seed — a repo, folder, or docs-site URL — verify you can actually read it **before** designing structure or scaffolding anything:

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.

## Confirmation gates for state-changing operations

Site creation, space creation, adding sections, attaching site-spaces, and customization changes all create or modify objects that are **immediately visible to everyone in the org** and that take real effort to clean up. Treat them as heavy operations.

The rule: **never make a state-changing change without first showing the user a one-screen preview of exactly what's about to happen and getting an explicit "yes".**

A good preview is short and concrete:

> About to run, in org **Acme Inc** (`org_abc123`):
> - Create site **"Acme Platform Docs"** (type: 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)

Bad previews are vague ("I'll create the site now") or buried in a wall of explanation. Keep it scannable.

The same rule applies to destructive operations — deleting a site, space, section, or customization override — only with even less ambiguity ("This will delete site **Acme Platform Docs** along with its 3 spaces. Spaces and sites are recoverable for 7 days, then permanent. Confirm?").

When the user has already confirmed a multi-step plan in the structure-design step, you don't need to ask again for each individual operation inside that plan — but if anything in the plan changes (an extra space, a different visibility), re-confirm.

For read-only operations (fetching or listing), no confirmation is needed.

## After a change-request push: two links are mandatory

Whenever this skill (or `write-docs`, which it delegates page authoring to) pushes content through a change request — via MCP's `updateChangeRequestContent`/`create_change_request`/`submit_or_merge_change_request` curated tools, `invoke_operation`, or the REST equivalents — the edit is **not finished** until both of the following have been reported back to the user, every time:

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.

This is a hard rule, on the same footing as the confirmation gates above — not a nicety to add if there's time. See `write-docs`'s "Two links are mandatory whenever a change request is involved" and the `cr-create` skill's "Surfacing the preview link" for the exact resolution steps (MCP: `getSpaceById` → find the site via `list_sites`/`get_site_structure` or each site's site-spaces → `getSiteById` for `.urls.preview`; REST: the equivalent chained `GET` calls). If the space isn't attached to a published site, say so plainly rather than only giving the diff link with no explanation.

## Designing the site structure

Before writing any files or creating anything in GitBook, decide on the structure and run it past the user. A weak structure is the single biggest reason docs sites fail to land.

The output of this step is a small plan, ideally three pieces:

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.

The full set of heuristics for going from raw inputs to a structure plan is in `references/site-structure-design.md` — read it the first time you do this for a non-trivial site. **Always show the plan to the user and get explicit sign-off before scaffolding files.** Restructuring later is cheap inside Git but expensive once a site is published and indexed.

A note on confirmation when the user gives one collapsed instruction: prompts like *"plan the structure and then scaffold it"* tempt you to skip the gate. Don't. Present the plan as a clear, scannable block, then either wait for a "yes" or — if you've already started scaffolding because the prompt was that explicit — surface what you decided in the plan and offer one easy chance to redirect ("if any of this is off, tell me and I'll redo before going further"). The point is that the user sees the plan **before** they're staring at twenty generated files, while a redo is still cheap.

## Scaffolding the repository

Once the structure is agreed, lay out the repo as a monorepo — even for single-space sites, this is consistent and future-proof. Each space is a directory containing its own `README.md` (homepage) and `SUMMARY.md` (table of contents). Optionally a `.gitbook/` folder for per-space variables and reusable content blocks, and optionally a `.gitbook.yaml` for advanced sync configuration.

Example layout for a three-space site:

```
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
```

A few notes about this layout that often trip people up:

- **`.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 with expression syntax (e.g. `support_email: [email protected]` referenced as `<code class="expression">space.vars.support_email</code>`). Useful for any value that appears on many pages. See `write-docs` / `references/frontmatter.md` — do **not** use `{% vars.… %}`.
- **`.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 maps that space to under **Content mapping** when wiring up site-wide Git Sync — not the site's "Project directory" field, which only points at where `gitbook-docs.yaml` itself lives (the repo root, in this layout). Don't conflate the two; see `references/git-sync-handoff.md`.
- Consider pre-authoring a `gitbook-docs.yaml` at the repo root that maps every space to its directory (see `references/git-sync-handoff.md` for the shape). GitBook reads it on first sync, so the user has less to fill in by hand during setup.

A minimal `.gitbook.yaml`, when you do need one, looks like:

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

### The repo-level README and .gitignore

The repo-level `README.md` (top of the repo, not inside a space) should explain what the folder is and how it relates to the published site — not duplicate the docs themselves. A short paragraph is enough:

```markdown
# my-docs

Source for the [My Product docs site](https://docs.example.com). Each top-level folder
is a separate GitBook space; edits flow in both directions via Git Sync once configured.
```

A `.gitignore` should keep OS junk and editor settings out of the repo. Reasonable default:

```
.DS_Store
Thumbs.db
*.swp
*.swo
.idea/
.vscode/
```

If the team has additional generated artifacts (e.g. an OpenAPI spec built from source elsewhere), add those.

### Generating SUMMARY.md — gather the nav, don't infer it from folders

The most common scaffolding mistake is to walk the file tree and emit a SUMMARY.md from it: README at the top, every other file as a child indented under the README. This produces dispiriting nav — every page is a "child of the homepage", folder names become group titles whether or not they're meaningful to a reader, and the IA mirrors the file system instead of the user's mental model.

**The right pattern, in order:**

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`.

If your scaffolding helper auto-generates a SUMMARY.md by walking folders, **make it idempotent and skip files that already exist**. A user-edited SUMMARY.md should never be silently clobbered — that's how hand-tuned navigation gets lost.

### Per-page markdown — defer to write-docs, but reach for the rich blocks

**For all markdown files** — `README.md`, `SUMMARY.md`, every page — follow the `write-docs` skill. It is the authoritative reference for:

- **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.

Don't reinvent any of that here. The bundled `references/example-site/` is the best practical reference for what idiomatic content looks like.

### Choosing the right block — actively, not by default

A common failure mode: Claude generates docs that *work* but use plain markdown for everything, missing the rich blocks that make GitBook sites feel like a real product. **The skill should actively reach for specialized blocks**, not fall back to bare prose-and-bullets. Concrete patterns to internalize:

- **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.

The full block-by-block guide, with example invocations and a smell-vs-fix decision table, is in `references/block-ecosystem.md`. **Read it before generating any non-trivial page**, and walk the decision table for each content area being scaffolded — ask "is there a specialized block for this?" before defaulting to plain markdown.

### Cross-space links

Multi-space sites *want* cross-space links — they're how a site feels like one connected product, not a bunch of separate manuals. **Don't duplicate content to avoid them, and don't drop them.** They're a first-class GitBook feature; the only twist is that they need real space IDs to render correctly, and IDs only exist after the site is created.

The pattern in markdown is just a regular link to the GitBook URL of the target space:

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

GitBook resolves `https://app.gitbook.com/s/<spaceId>/<path>` at render time, regardless of your custom domain. Internally these are `ContentRefPage` or `ContentRefSpace` content references with the space ID set; in markdown they just appear as URLs.

**The scaffolding flow:**

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.

For a clean implementation, keep a `cross-space-links.ya...