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

Common types: flowchart LR/TD (flows, decision trees), sequenceDiagram (request/response, multi-actor), stateDiagram-v2 (formal state machines), erDiagram (data models), gantt (timelines). Standard Mermaid syntax — no GitBook-specific extensions.

SVG handling:

Two pitfalls affect SVGs referenced via <img> or <picture>:

• currentColor doesn't resolve in referenced SVGs. currentColor only works when SVG markup is inlined directly into the page. Via <img src="..."> the SVG renders standalone and currentColor falls back to black regardless of theme. For theme-aware icons, either inline the SVG or ship two variants and swap with <picture>:

  <picture>
    <source srcset=".gitbook/assets/icon-dark.svg" media="(prefers-color-scheme: dark)"/>
    <img src=".gitbook/assets/icon-light.svg" alt="" data-size="line"/>
  </picture>
  

• Keep xmlns on standalone SVG files. Some tools strip xmlns="http://www.w3.org/2000/svg" because it's redundant when SVG is inlined into HTML. But when the file is referenced via <img> or <picture>, a missing xmlns causes the browser to parse it as plain XML and render nothing. The xmlns is only safely removable when SVGs are inlined. Keep it by default.

Page Frontmatter

GitBook supports YAML frontmatter at the top of markdown files to configure page-specific settings. Frontmatter must be placed at the very beginning of the file, before any content.

Available frontmatter fields:

---
description: Page description used for SEO and page previews
icon: book-open
hidden: true
vars:
  page_variable: value
  another_var: another value
if: visitor.claims.unsigned.isPremium
layout:
  width: default
  title:
    visible: true
  description:
    visible: true
  tableOfContents:
    visible: true
  outline:
    visible: true
  pagination:
    visible: true
  metadata:
    visible: true
---

Field descriptions:

• description: - Page description text. Supports multiline with >- syntax:

  description: >-
    This is a longer description
    that spans multiple lines
  

• icon: - Icon name from Font Awesome (e.g., book-open, bolt, stars, icons, brackets-curly)

• hidden: true - Hides the page from the table of contents in published documentation

• vars: - Page-level variables (key-value pairs) that can be referenced in expressions:

  vars:
    version: v1.2.3
    api_key: example_key
  

• if: - Adaptive content visibility condition. Controls when the page is visible based on visitor attributes:

  if: visitor.claims.unsigned.isPremium
  

  Note: While adaptive content conditions can be set in frontmatter, it's recommended to configure them through the GitBook UI for better maintainability and team visibility.

• layout: - Controls page layout and which elements are visible. This maps to the "Page Options" settings in the GitBook UI:

  • width: - Page content width
    • default - Standard content width
    • wide - Wider content area (automatically widens full-width blocks like tables and code)
  • title.visible: - Show/hide the page title (boolean: true or false)
  • description.visible: - Show/hide the page description (boolean: true or false)
  • tableOfContents.visible: - Show/hide the left sidebar table of contents (boolean: true or false)
  • outline.visible: - Show/hide the right sidebar page outline/headings (boolean: true or false)
  • pagination.visible: - Show/hide next/previous page navigation links (boolean: true or false)
  • metadata.visible: - Show/hide page metadata section (boolean: true or false)

  Example for a landing page with minimal chrome:

  layout:
    width: wide
    title:
      visible: true
    description:
      visible: true
    tableOfContents:
      visible: false
    outline:
      visible: false
    pagination:
      visible: false
  

• cover: - Path to a hero/banner image displayed at the top of the page. Typically a .gitbook/assets/ path:

  cover: .gitbook/assets/home-cover.png
  

  Requires layout.cover.visible: true to render. Accepts external URLs too.

• coverY: - Vertical crop offset for the cover image (integer; 0 = centered, positive moves the focal point down, negative up). Useful when the image is taller than the cover band:

  coverY: -72
  

• layout.cover.visible: / layout.cover.size: - Control cover rendering. size is either full (full-bleed hero) or hero (smaller banner):

  layout:
    cover:
      visible: true
      size: full
  

YAML quoting in frontmatter:

Always quote description: and any other string values that contain YAML-significant characters. Characters that require quoting: : (most common), #, [, ], {, }, &, *, !, |, >, ', ", %, @, ` (especially at the start of a value). The safe default is to quote any value containing punctuation:

# Wrong — breaks YAML silently
description: Authentication: how it works

# Right — quoted
description: "Authentication: how it works"

Unquoted special characters cause silent failures in Git Sync — the page imports without a title or description with no error message. When generating frontmatter programmatically from migrated content, quote all string values by default.

Example complete frontmatter:

---
description: "Create reusable variables that can be referenced in pages and spaces"
icon: icons
cover: .gitbook/assets/hero.png
coverY: -40
vars:
  latest_version: v3.0.4
  support_email: [e-mail]
layout:
  width: wide
  cover:
    visible: true
    size: full
  title:
    visible: true
  description:
    visible: true
  tableOfContents:
    visible: true
  outline:
    visible: true
  pagination:
    visible: true
---

# Your Page Title

Page content starts here...

Variables and Expressions

GitBook supports variables that can be dynamically displayed in your content using expressions. Variables can be defined at the space level or page level.

Variable Storage

Space-level variables are stored in /.gitbook/vars.yaml at the root of your documentation:

# .gitbook/vars.yaml
food: apple
latest_version: v3.0.4
company_name: Acme Corp

Page-level variables are stored in the page's frontmatter under vars::

---
vars:
  page_food: orange
  page_version: v2.1.0
---

Using Variables with Expressions

Expressions allow you to reference and display variable values dynamically in your content. Expressions use JavaScript syntax and are wrapped in <code class="expression"> tags.

Syntax:

<code class="expression">JavaScript expression here</code>

Examples:

<!-- Simple expression -->
<code class="expression">1 + 1</code>

<!-- Reference a space-level variable -->
<code class="expression">space.vars.latest_version</code>

<!-- String concatenation with variable -->
<code class="expression">"My favorite food is " + space.vars.food</code>

<!-- Reference a page-level variable -->
<code class="expression">page.vars.page_food</code>

<!-- Conditional logic -->
<code class="expression">space.vars.latest_version === "v3.0.4" ? "Latest" : "Outdated"</code>

Variable references:

• space.vars.variableName - Access space-level variables defined in /.gitbook/vars.yaml
• page.vars.variableName - Access page-level variables defined in the page's frontmatter

Important notes:

• Variable definitions (the actual variable storage) are managed through:
  • /.gitbook/vars.yaml for space-level variables
  • Page frontmatter vars: for page-level variables
• Expressions can contain any valid JavaScript code and are evaluated when the page is rendered
• When editing locally, you can create space variables by editing /.gitbook/vars.yaml and page variables by adding them to frontmatter
• The GitBook UI provides a visual editor for managing variables, but they are fully editable in markdown files

GitBook Custom Blocks

GitBook extends standard markdown with custom block syntax using tags like {% tabs %}, {% hint %}, etc. These blocks enable rich, interactive documentation features.

Tabs

Use tabs to present alternative content like different programming languages or platform-specific instructions.

When to use: Comparing alternatives (code in different languages, platform-specific commands, configuration options).

Syntax:

{% tabs %}
{% tab title="JavaScript" %}
```javascript
const greeting = 'Hello World';
console.log(greeting);
```
{% endtab %}

{% tab title="Python" %}
```python
greeting = "Hello World"
print(greeting)
```
{% endtab %}
{% endtabs %}

Stepper

Use steppers for sequential, multi-step processes where order matters.

When to use: Tutorials, installation guides, how-to guides, onboarding checklists, any sequential process.

Syntax:

{% stepper %}
{% step %}
## First step

Complete the initial setup by installing the required dependencies.
{% endstep %}

{% step %}
## Second step

Configure your environment variables in the `.env` file.
{% endstep %}

{% step %}
## Third step

Run the application with `npm start`.
{% endstep %}
{% endstepper %}

Hints

Use hints to highlight important information without disrupting flow. Supported styles: info, warning, danger, success.

When to use: Supplementary information, call-outs, best practices, warnings, troubleshooting tips.

Syntax:

{% hint style="info" %}
This is an informational hint with helpful context.
{% endhint %}

{% hint style="warning" %}
Be careful when running this command in production.
{% endhint %}

{% hint style="danger" %}
This action cannot be undone. Make sure you have backups.
{% endhint %}

{% hint style="success" %}
Your configuration has been saved successfully!
{% endhint %}

Expandable

Use expandable sections for optional content that doesn't need to be visible by default.

When to use: Optional deep-dives, advanced explanations, lengthy logs, FAQ answers, content that would clutter the page.

Syntax:

<details>
<summary>Advanced Configuration Options</summary>

Here you can find detailed information about advanced settings that most users won't need.

```yaml
advanced:
  option1: value1
  option2: value2
```
</details>

Columns

Use columns to present content side-by-side (2 columns maximum).

When to use: Side-by-side comparisons (pros vs cons), before/after examples, parallel instructions.

Syntax:

{% columns %}
{% column %}
### Before

Old implementation that was inefficient.
{% endcolumn %}

{% column %}
### After

New optimized approach with better performance.
{% endcolumn %}
{% endcolumns %}

Updates

Use updates blocks for product updates, release notes, or changelogs.

When to use: Changelog pages, release notes, version updates, product announcements.

Syntax:

{% updates format="full" %}
{% update date="2024-01-15" %}
# Version 2.0 Released

We've added new features including dark mode and improved search.
{% endupdate %}

{% update date="2024-01-01" %}
# Bug Fixes

Fixed several issues reported by the community.
{% endupdate %}
{% endupdates %}

Tags parameter:

Individual {% update %} entries can carry one or more tags via tags="" (comma-separated). Tags are rendered as filter chips in the published timeline and GitBook generates an RSS feed for the space automatically.

{% updates format="full" %}
{% update date="2026-04-22" tags="api,beta" %}
## AI topic auto-classification (beta)

New endpoint for automatic topic tagging.
{% endupdate %}

{% update date="2026-03-10" tags="security" %}
## OAuth 2.0 Support

Added OAuth 2.0 authentication flow.
{% endupdate %}
{% endupdates %}

Defining tags in .gitbook/tags.yaml:

Tags must be declared before they can be used. Create .gitbook/tags.yaml at the root of the space. Tag slugs must exactly match the values used in tags="":

# .gitbook/tags.yaml
- tag: api
  label: API
  icon: code
- tag: security
  label: Security
  icon: shield-halved
- tag: beta
  label: Beta
  icon: flask
- tag: breaking
  label: Breaking Change
  icon: triangle-exclamation

Each entry: tag (slug, no spaces), label (display text), icon (Font Awesome name without fa- prefix).

Cards

Use cards to create visual, clickable navigation elements. Cards are HTML tables with special attributes.

When to use: Dashboards, feature overviews, linking to related pages, showcasing multiple resources.

Canonical pattern — full-row clickable card with hidden target column:

The cleanest card-table uses data-hidden on the link column so the entire card tile becomes clickable, rather than showing a visible "Read more" link column which clutters the layout:

<table data-view="cards">
  <thead>
    <tr>
      <th></th>
      <th></th>
      <th data-hidden data-card-target data-type="content-ref"></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Getting Started</strong></td>
      <td>Install and send your first event in five minutes.</td>
      <td><a href="getting-started/quickstart.md">quickstart</a></td>
    </tr>
    <tr>
      <td><strong>API Reference</strong></td>
      <td>Full endpoint and schema documentation.</td>
      <td><a href="api-reference/overview.md">overview</a></td>
    </tr>
  </tbody>
</table>

data-hidden makes the column invisible to readers. data-card-target marks it as the link target — the whole row becomes a link.

Cards with icons:

Prefer Font Awesome icons via <i class="fa-..."> — they inherit theme colors and require no asset files. Use <img> only when you need a specific branded icon that Font Awesome doesn't cover.

Font Awesome icon (preferred):

<table data-view="cards">
  <thead>
    <tr>
      <th width="48"></th>
      <th></th>
      <th></th>
      <th data-hidden data-card-target data-type="content-ref"></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><i class="fa-bolt"></i></td>
      <td><strong>Quickstart</strong></td>
      <td>Send your first event in five minutes.</td>
      <td><a href="getting-started/quickstart.md">quickstart</a></td>
    </tr>
  </tbody>
</table>

Inline <img> for custom branded icons (fallback):

<table data-view="cards">
  <thead>
    <tr>
      <th width="48"></th>
      <th></th>
      <th></th>
      <th data-hidden data-card-target data-type="content-ref"></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><img src=".gitbook/assets/quickstart.svg" alt="" data-size="line"/></td>
      <td><strong>Quickstart</strong></td>
      <td>Send your first event in five minutes.</td>
      <td><a href="getting-started/quickstart.md">quickstart</a></td>
    </tr>
  </tbody>
</table>

In both cases <th width="48"></th> keeps the icon column narrow. For <img>, data-size="line" constrains it to text-line height. Both <i class="fa-..."> and <img> work anywhere else in markdown too — not just inside card-tables.

Embeds

Use embeds to include external content like videos, interactive demos, or social media.

When to use: Demonstration videos, interactive code sandboxes, tweets, external rich media.

Syntax:

{% embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" %}

{% embed url="https://codepen.io/username/pen/example" %}

Files

Use file blocks to provide downloadable files with captions.

Syntax:

{% file src="https://example.com/document.pdf" %}
Complete documentation in PDF format.
{% endfile %}

Buttons

Use buttons for clear call-to-action links. Supported styles: primary and secondary.

When to use: Download links, "Try it now" actions, external resource navigation.

Syntax:

<a href="https://example.com/download" class="button primary">Download Now</a>

<a href="https://docs.example.com" class="button secondary">View Documentation</a>

Buttons with icons:

<a href="https://github.com/user/repo" class="button primary" data-icon="github">View on GitHub</a>

Icons use Font Awesome names (without the fa- prefix).

Icons

Inline icons from Font Awesome can enhance text readability.

When to use: Visual indicators, status icons, improving scannability.

Syntax:

<i class="fa-check">check</i> Feature enabled
<i class="fa-warning">warning</i> Requires configuration
<i class="fa-info-circle">info</i> Learn more

Reusable Content

Reusable content blocks let you sync content across multiple pages.

When to use: Call-to-actions, disclaimers, repeated instructions, any content that needs to stay consistent across pages.

Syntax:

{% include "/reusable-content/rc12345" %}

Note: Reusable content blocks are different from pages. They're created through the GitBook UI and given unique IDs.

OpenAPI Specifications

OpenAPI specifications enable interactive, testable API documentation in GitBook. However, OpenAPI specs cannot be added directly to markdown files.

How to add OpenAPI specs:

OpenAPI specifications must be uploaded through one of these methods:

1. GitBook API - Use the OpenAPI endpoints to programmatically upload specs
2. GitBook CLI - Use the gitbook openapi command
3. GitBook UI - Upload specs through the web interface

Once uploaded, you can reference individual API methods in prose pages using the OpenAPI block:

{% openapi src="https://api.example.com/openapi.json" path="/users" method="get" %}
[https://api.example.com/openapi.json](https://api.example.com/openapi.json)
{% endopenapi %}

Auto-generating the full endpoint page tree (builtin:openapi):

For an API reference space, instead of hand-authoring one page per endpoint, use the builtin:openapi pattern in SUMMARY.md to auto-generate the entire page tree from a registered spec. The entry is a fenced YAML block as the bullet content:

# Table of contents

* [Overview](README.md)

## Feedback API

* [Overview](feedback/README.md)
* ```yaml
  type: builtin:openapi
  props:
    models: false
    downloadLink: true
  dependencies:
    spec:
      ref:
        kind: openapi
        spec: my-api-v1

`spec: my-api-v1` is the slug of a spec registered with the GitBook organization (configured separately via the GitBook API or UI — the SUMMARY entry just references it). The generated operation pages are virtual and don't correspond to files in the repo; only the parent `README.md` files need to exist as real files. Pair each resource section with a brief prose README covering base URL, version policy, and what the resource is for.

**Important notes:**

* You cannot embed OpenAPI spec content directly in markdown files
* The `src` URL in inline `{% openapi %}` blocks must point to an already-uploaded specification
* The `builtin:openapi` page-tree pattern only works in `SUMMARY.md`, not inside regular pages
* For more information, see the [GitBook OpenAPI documentation](https://docs.gitbook.com/api-references/openapi)

### Nested Markdown in Custom Blocks

Markdown formatting works inside custom block tags. Maintain standard markdown syntax within custom blocks:

````markdown
{% tabs %}
{% tab title="Example" %}
This tab contains markdown:

- Bullet points work
  - Nested bullets too
- **Bold text** and *italic text*
- `inline code`

```javascript
// Code blocks work too
const example = true;

{% endtab %} {% endtabs %}

### Common Pitfalls

**Cross-space links:**

* Don't use relative paths to link to a page in a different space — they won't resolve. Use `https://app.gitbook.com/s/<spaceId>/<path>` instead.
* If the space ID isn't known yet, use an `XSPACE_<KEY>` sentinel placeholder. `manage-gitbook-site` replaces these with real IDs after space creation.

**File organization:**

* Don't reference the same markdown file twice in SUMMARY.md
* Keep file paths consistent between SUMMARY.md and actual file locations
* Use relative paths consistently (within a space only — cross-space links require full URLs)

**Configuration conflicts:**

* When using Git Sync, manage README.md only through your repository
* Keep .gitbook.yaml at the correct root level for your project
* Test redirects after moving or renaming files

**Markdown formatting:**

* Tables and columns are discouraged (use custom blocks instead)
* Avoid excessive nested lists (keep hierarchy simple)
* Don't mix tab/space indentation in SUMMARY.md

**Custom blocks:**

* Always close blocks properly (`{% endtab %}`, `{% endhint %}`, etc.)
* Match opening and closing tags exactly
* Test custom blocks in GitBook after editing locally

### Working with Git Sync

When GitBook is synced with Git:

1. Changes in Git automatically update GitBook
2. Changes in GitBook automatically commit to Git
3. GitBook maintains SUMMARY.md based on UI edits
4. Merge conflicts should be resolved in Git

**Best practices:**

* Make structural changes (navigation) through SUMMARY.md in Git
* Make content changes either in Git or GitBook UI (be consistent)
* Review auto-generated commits from GitBook
* Use branch-based workflows for significant updates
* Test changes in a preview before merging to main

### Example Complete Page

Here's a complete example showing multiple GitBook features:

# API Authentication Guide

Learn how to authenticate with our API using API keys or OAuth 2.0.

{% hint style="info" %}
All API requests require authentication. Choose the method that best fits your use case.
{% endhint %}

## Authentication Methods

{% tabs %}
{% tab title="API Key" %}
The simplest authentication method. Include your API key in the request header:
```bash
curl -H "X-API-Key: your-api-key" https://api.example.com/v1/users

{% hint style="warning" %} Never commit API keys to version control. Use environment variables instead. {% endhint %} {% endtab %}

{% tab title="OAuth 2.0" %} More secure for user-facing applications:

{% stepper %} {% step %}

Register your application

Get your client ID and secret from the developer dashboard. {% endstep %}

{% step %}

Request authorization

Redirect users to our OAuth endpoint. {% endstep %}

{% step %} Exchange code for token

Use the authorization code to get an access token. {% endstep %} {% endstepper %} {% endtab %} {% endtabs %}

Rate Limits

{% columns %} {% column %}

Free Tier

1,000 requests/hour 10,000 requests/day {% endcolumn %}

{% column %}

Pro Tier

10,000 requests/hour 100,000 requests/day {% endcolumn %} {% endcolumns %}

Need higher limits?

Contact our sales team to discuss enterprise plans with custom rate limits and SLAs.

Get Started

---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/skill.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.