Editing GitBook documentation in this Git-synced repo (RealmJoin docs). Use whenever creating or modifying GitBook content as markdown files — pages, SUMMARY.md navigation, .gitbook.yaml config, frontmatter, variables, and GitBook custom blocks (hints, tabs, steppers, cards, columns, etc.). Covers all GitBook formatting syntax and best practices needed to produce valid content (and pull requests) outside the GitBook web UI.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Editing GitBook documentation in this Git-synced repo (RealmJoin docs). Use whenever creating or modifying GitBook content as markdown files — pages, SUMMARY.md navigation, .gitbook.yaml config, frontmatter, variables, and GitBook custom blocks (hints, tabs, steppers, cards, columns, etc.). Covers all GitBook formatting syntax and best practices needed to produce valid content (and pull requests) outside the GitBook web UI.
GitBook Documentation Editing
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
{% hint style="..." %}...{% endhint %} for callouts
{% stepper %}...{% endstepper %} for sequential steps
<details>...<summary>...</details> for expandable content
Links:
External: [text](https://example.com)
Internal: Use relative paths like [text](page.md) or [text](../folder/page.md)
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:
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
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.
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
Explore .gitbook/assets/ - Contains all uploaded images and files referenced in the documentation
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).
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 
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)
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.3api_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)
---
description: Create reusable variables that can be referenced in pages and spaces
icon: icons
vars:
latest_version: v3.0.4
support_email: help@example.com
layout:
width: wide
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:
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.
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).
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 %}
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.
Test custom blocks in GitBook after editing locally
Working with Git Sync
When GitBook is synced with Git:
Changes in Git automatically update GitBook
Changes in GitBook automatically commit to Git
GitBook maintains SUMMARY.md based on UI edits
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 %}
<details><summary>Need higher limits?</summary>
Contact our sales team to discuss enterprise plans with custom rate limits and SLAs.
</details><ahref="https://example.com/signup"class="button primary"data-icon="rocket">Get Started</a>
