GitBook Skill

Use when working with GitBook documentation platform, generated from official documentation (107 pages).

When to Use This Skill

This skill should be triggered when:

• Creating or managing GitBook documentation spaces
• Setting up Git synchronization (GitHub/GitLab)
• Publishing documentation sites with custom domains
• Working with GitBook's block-based editor
• Configuring OpenAPI/API reference documentation
• Managing team collaboration and change requests
• Migrating content to GitBook
• Customizing site appearance and branding

Quick Reference

Core Concepts

Concept	Description
Space	A documentation project (like a book or wiki)
Collection	A group of related spaces
Site	Published documentation accessible via URL
Change Request	Draft changes for review before publishing
Live Edits	Direct changes without change request workflow

Content Blocks

GitBook uses a block-based editor. Common blocks:

Block	Shortcut	Description
Paragraph	Just type	Default text block
Heading	#, ##, ###	Section headers (H1, H2, H3)
Code Block	``` or /code	Syntax-highlighted code
Quote	> or /quote	Blockquote
List	-, 1.	Unordered/ordered lists
Task List	- [ ]	Checkbox items
Table	/table	Data tables
Image	/image	Upload or embed images
Tabs	/tabs	Tabbed content
Expandable	/expandable	Collapsible sections
Cards	/cards	Visual link cards
Hint	/hint	Info, warning, danger, success boxes
API Reference	/openapi	OpenAPI spec integration

Inline Content (/) Palette

Press / in any text block to access:

• Link - Relative (internal) or absolute (external) links
• Image - Inline images
• Emoji - :emoji_name: syntax
• Math - LaTeX/KaTeX formulas: $$formula$$
• Annotation - Footnote-style explanations

Common Patterns

Create a hint/callout box

{% hint style="info" %}
This is an info hint
{% endhint %}

{% hint style="warning" %}
This is a warning
{% endhint %}

{% hint style="danger" %}
This is a danger/error hint
{% endhint %}

{% hint style="success" %}
This is a success hint
{% endhint %}

Create tabs

{% tabs %}
{% tab title="JavaScript" %}
console.log("Hello");
{% endtab %}
{% tab title="Python" %}
print("Hello")
{% endtab %}
{% endtabs %}

Create expandable section

{% expandable title="Click to expand" %}
Hidden content here
{% endexpandable %}

Create stepper (numbered steps)

{% stepper %}
{% step %}
First step content
{% endstep %}
{% step %}
Second step content
{% endstep %}
{% endstepper %}

Create cards

{% cards %}
{% card title="Card 1" href="/page1" %}
Description here
{% endcard %}
{% card title="Card 2" href="/page2" %}
Another description
{% endcard %}
{% endcards %}

Git Sync Configuration

Enable GitHub Sync

1. Go to space settings → Git Sync
2. Connect GitHub account
3. Select repository and branch
4. Configure sync direction:
   • GitBook → GitHub: GitBook is source of truth
   • GitHub → GitBook: Git repo is source of truth
   • Two-way: Bidirectional sync

Directory structure for Git

docs/
├── README.md          # Space landing page
├── SUMMARY.md         # Table of contents
├── .gitbook.yaml      # GitBook configuration
├── page-one.md
├── group/
│   ├── README.md      # Group landing page
│   └── nested-page.md
└── .gitbook/
    └── assets/        # Images and files

SUMMARY.md structure

# Table of contents

* [Introduction](README.md)
* [Getting Started](getting-started.md)

## Section Title

* [Page One](section/page-one.md)
* [Page Two](section/page-two.md)

.gitbook.yaml configuration

root: ./docs/          # Documentation root directory

structure:
  readme: README.md    # Landing page file
  summary: SUMMARY.md  # Table of contents file

redirects:
  old-path: new-path   # URL redirects

Custom Domain Setup

1. Go to site settings → Custom domain
2. Add your domain (e.g., docs.example.com)
3. Configure DNS:
   • CNAME record: Point to hosting.gitbook.io
   • Or A record for apex domains
4. Enable HTTPS (automatic via Let's Encrypt)

Subdirectory publishing (with Cloudflare/Vercel)

example.com/docs → GitBook site

OpenAPI Integration

Add OpenAPI specification

1. Upload OpenAPI/Swagger file (JSON or YAML)
2. Or link to hosted spec URL
3. GitBook auto-generates interactive API docs

Customize API reference

{% openapi src="./api.yaml" /%}

Publishing Options

Type	Description
Public	Accessible to everyone
Unlisted	No search indexing, URL access only
Share links	Private with token-based access
Authenticated	SSO/login required

Collaboration

Change Requests

• Create a change request for non-breaking changes
• Request reviews from team members
• Merge when approved
• Automatic conflict detection

Live Edits

• Direct editing for quick fixes
• No approval workflow
• Immediate publishing

Comments

• Inline comments on any block
• @mention team members
• Resolve when addressed

Migration to GitBook

From other platforms

1. Import panel: Confluence, Notion, Docusaurus, Markdown
2. Git Sync: Connect existing Git repo with markdown files
3. Manual: Copy/paste with formatting preserved

Import via Git Sync

# Prepare your repo
mkdir docs
echo "# Welcome" > docs/README.md
echo "* [Welcome](README.md)" > docs/SUMMARY.md
git add . && git commit -m "Initial docs"

Keyboard Shortcuts

Action	Shortcut
Command palette	⌘/Ctrl + K
Bold	⌘/Ctrl + B
Italic	⌘/Ctrl + I
Link	⌘/Ctrl + K (with selection)
Code	⌘/Ctrl + E
Search	⌘/Ctrl + /

Reference Files

This skill includes comprehensive documentation in references/:

• llms-txt.md - Full GitBook documentation (107 pages, 456 KB)
• llms-full.md - Complete llms.txt source
• llms.md - Condensed reference (95 KB)

Use view to read specific reference files when detailed information is needed.

Content Categories

The reference documentation covers:

Creating Content

• Blocks (code, tables, images, tabs, cards, etc.)
• Inline content (links, emojis, math, annotations)
• Formatting and layout
• Page structure and navigation

Publishing

• Sites and custom domains
• Public vs private publishing
• Share links and authentication
• Redirects and SEO

Collaboration

• Change requests and live edits
• Comments and reviews
• Team management
• Merge rules

Integration

• Git Sync (GitHub, GitLab)
• OpenAPI/API documentation
• Translations
• Extensions

Configuration

• Site structure and theming
• Icons, colors, and branding
• Content configuration
• Troubleshooting

Common Issues

Git Sync not working

• Check repository permissions
• Verify branch exists
• Ensure SUMMARY.md is valid
• Check for merge conflicts

Custom domain issues

• Verify DNS propagation (can take 24-48 hours)
• Check CNAME points to hosting.gitbook.io
• Ensure no conflicting records

Content not updating

• Check for pending change requests
• Verify Git sync status
• Clear browser cache
• Check for merge conflicts

Notes

• This skill was generated from official GitBook documentation via llms.txt
• Reference files contain 107 pages of comprehensive documentation
• Content is current as of January 2026

Resources

• GitBook Documentation
• GitBook Status
• GitBook Community