write-gitbook

name	write-gitbook
description	A comprehensive guide for editing GitBook documentation in external environments like Cursor, Claude Code, or other text editors. This skill provides all the formatting syntax, configuration options, and best practices needed to create and maintain GitBook content outside the GitBook web interface.

When to Use This Skill

Use this skill when working with GitBook documentation through:

• Git-synced repositories (GitHub, GitLab)
• Local markdown editors
• IDE integrations
• Command-line tools
• 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/       # Section folder
    installation.md
    quickstart.md
  api-reference/
    authentication.md
    endpoints.md

Frontmatter fields:

---
description: Page description for SEO
icon: book-open
hidden: true
cover: .gitbook/assets/hero.png
coverY: 0
vars:
  page_variable: value
if: visitor.claims.unsigned.condition
layout:
  width: default  # or 'wide'
  cover:
    visible: true
    size: full      # or 'hero'
  title:
    visible: true
  description:
    visible: true
  tableOfContents:
    visible: true
  outline:
    visible: true
  pagination:
    visible: true
  metadata:
    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 %} for callouts
• {% stepper %}...{% endstepper %} for sequential steps
• <details>...<summary>...</details> for expandable content

Links:

• External: [text](https://example.com)
• Internal (same space): relative paths — [text](page.md), [text](../folder/page.md)
• Cross-space: relative paths don't work across space boundaries. Use https://app.gitbook.com/s/<spaceId>/<path>. If the space ID isn't known yet, use an XSPACE_<KEY> sentinel — e.g. [Auth](https://app.gitbook.com/s/XSPACE_API/authentication) — and let manage-gitbook-site resolve it after space creation.

Key reminders:

• Read SUMMARY.md first when working with existing content to understand structure
• Test in GitBook after editing locally
• Keep SUMMARY.md synchronized with your file structure
• Variables are defined in .gitbook/vars.yaml (space-level) or page frontmatter (page-level)
• OpenAPI specs must be uploaded via API/CLI/UI, not embedded in markdown

When to Use Which Block

Choose the right GitBook block for your content needs:

Need	Use	Why
Sequential, ordered instructions	{% stepper %}	Guides users through multi-step processes with clear progression
Alternative options (languages, platforms)	{% tabs %}	Lets users choose their relevant option without cluttering the page
Optional or detailed information	<details> (Expandable)	Keeps page scannable while providing depth for interested readers
Important warnings or tips	{% hint %}	Draws attention with colored styling (info, warning, danger, success)
Side-by-side comparisons	{% columns %}	Shows related information in parallel (max 2 columns)
Timeline or changelog	{% updates %}	Displays dated entries in reverse chronological order
Visual navigation cards	<table data-view="cards">	Creates clickable card grid for section navigation
Downloadable files	{% file %}	Provides files with captions and descriptions
Call-to-action links	<a class="button">	Highlights primary or secondary actions
Reusable content across pages	{% include %}	Maintains consistency for repeated content blocks
Dynamic content	<code class="expression">	Displays variable values that update automatically

Variable scope decision:

If variable is...	Define it as...	Access with...
Used across multiple pages	Space-level in /.gitbook/vars.yaml	space.vars.variableName
Specific to one page	Page-level in frontmatter vars:	page.vars.variableName

Working with Existing Content

When working with an existing GitBook space that's synced to Git, follow this workflow to understand the structure:

1. Read SUMMARY.md first - This file contains the complete table of contents and navigation structure. It shows you:
   • All pages and their hierarchy
   • Page groups and organization
   • The relative paths to each markdown file
2. If SUMMARY.md doesn't exist - GitBook has inferred the structure from your directory layout. Browse the directory structure to understand how pages are organized.
3. Check .gitbook.yaml - Review this file to understand:
   • Where the root documentation directory is located
   • Any custom paths for README.md or SUMMARY.md
   • Existing redirects
4. Explore .gitbook/assets/ - Contains all uploaded images and files referenced in the documentation
5. Check .gitbook/vars.yaml - Contains space-level variables if any are defined

This approach ensures you understand the existing structure before making changes, helping you maintain consistency and avoid breaking internal links.

Configuration Files

.gitbook.yaml

The .gitbook.yaml file configures your GitBook space. It should be placed at the root of your documentation directory (or in a subdirectory if using monorepos).

Basic structure:

root: ./

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

redirects:
  old-page: new-page.md
  help: support.md

Configuration options:

• root: The root directory for your documentation (default: ./)
• structure.readme: Path to your homepage (default: ./README.md)
• structure.summary: Path to your table of contents (default: ./SUMMARY.md)
• redirects: Key-value pairs mapping old URLs to new page paths

Monorepo support:

For repositories with multiple documentation projects:

/
  packages/
    docs/
      .gitbook.yaml
      README.md
      SUMMARY.md
    api/
      .gitbook.yaml
      README.md
      SUMMARY.md

When setting up Git Sync, configure the "Project directory" to point to the subdirectory containing the .gitbook.yaml file.

Important notes:

• Paths in .gitbook.yaml are relative to the root option
• Redirects defined here are space-specific (apply only to this space)
• For site-wide redirects across multiple spaces, use the GitBook UI instead
• When using Git Sync, manage the README file only through your repository to avoid conflicts

The .gitbook Directory

When using Git Sync, GitBook creates a .gitbook directory in your repository to store assets, variables, and generated content.

Directory structure:

.gitbook/
  assets/          # Uploaded images and files
  includes/        # Reusable content blocks (exported as individual .md files)
  vars.yaml        # Space-level variables

Important notes about .gitbook:

• Assets: Images and files uploaded through the GitBook UI are stored in .gitbook/assets/
• Reusable content: Each reusable content block is exported as a separate markdown file in .gitbook/includes/
• Variables: Space-level variables are stored in .gitbook/vars.yaml as key-value pairs
• References: Pages reference reusable content using {% include "/reusable-content/rc12345" %}
• Images: Markdown pages reference images like ![alt](../.gitbook/assets/image-name.svg)
• Table of contents: The .gitbook/includes folder and its files may appear in your space's table of contents. You may need to manually hide them from the TOC if this happens.
• Location: In monorepos, the .gitbook directory is created in the root of each synced space (not necessarily the repository root)

SUMMARY.md

The SUMMARY.md file defines your table of contents and navigation structure. It's a markdown file with a specific format that mirrors the sidebar navigation in GitBook.

Basic structure:

# Summary

## Use headings to create page groups like this one

* [First page's title](page1/README.md)
    * [Some child page](page1/page1-1.md)
    * [Some other child page](page1/page1-2.md)
* [Second page's title](page2/README.md)
    * [Some child page](page2/page2-1.md)
    * [Some other child page](page2/page2-2.md)

## A second page group

* [Another page](another-page.md)

Key rules:

• Use # for the main title (commonly "Table of contents" or "Summary")
• Use ## headings to create page groups (section headers in the sidebar)
• Use * for unordered lists to define pages and subpages
• Indent with spaces (not tabs) to create nested/child pages
• Each list item should be a markdown link: [Link text](path/to/file.md)
• Paths are relative to the location specified in .gitbook.yaml (typically the root)

Page link titles (optional):

You can define a different title for the sidebar navigation versus the page itself:

# Summary

* [Page main title](page.md "Page link title")

The text in quotes ("Page link title") will be used in:

• The table of contents sidebar
• Pagination buttons at the bottom of pages
• Any relative links to that page

Important notes:

• SUMMARY.md is optional. If not provided, GitBook infers structure from your folder hierarchy
• You cannot reference the same markdown file twice in SUMMARY.md (each page has only one URL)
• GitBook updates SUMMARY.md automatically when you edit through the GitBook UI
• The file structure reflects exactly what users see in the navigation sidebar

Markdown Formatting

GitBook uses GitHub Flavored Markdown with custom extensions.

Standard markdown:

# Heading 1
## Heading 2
### Heading 3

**bold text**
*italic text*
`inline code`

- Bullet list item
- Another item
  - Nested item

1. Numbered list
2. Second item

[Link text](https://example.com)
[Internal link](getting-started.md)

Code blocks:

```javascript
const foo = 'bar';
console.log(foo);
```

Code blocks with titles:

{% code title="index.js" %}
```javascript
const foo = 'bar';
console.log(foo);
```
{% endcode %}

Inline links:

• External links: [text](https://example.com)
• Internal pages: Use relative file paths like [text](page.md), [text](../folder/page.md), or [text](subfolder/page.md)
• Email: [text](mailto:[e-mail])

Math/TeX:

Inline formula: $$E = mc^2$$

Block formula:

$$
E = mc^2
$$

Mermaid diagrams:

Any fenced code block with mermaid as the language renders as a diagram. Use Mermaid any time you'd otherwise reach for ASCII art or describe a relationship in prose where a picture would help.

```mermaid
flowchart LR
    Pending --> Authorized --> Captured
    Pending -.->|declined| Failed
    Authorized -.->|voided| Voided
    Captured -.->|refund| Refunded
```

```mermaid
sequenceDiagram
    Client->>Auth: POST /token
    Auth-->>Client: access_token
```

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Published
    Review --> Draft
```

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
```