GitBook Documentation

技能

A comprehensive 图形界面de for editing GitBook documentation in external 环境s like Cursor, Claude Code, or other text editors. This 技能 provides all the 格式化ting syntax, configuration options, and best practices needed to 创建 and mAIntAIn GitBook content outside the GitBook 网页 interface.

When to Use This 技能

Use this 技能 when working with GitBook documentation through:

Git-同步ed repositories (GitHub, GitLab) Local markdown editors IDE integrations Command-line 工具s Any 环境 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/ as设置s/ # 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 获取ting-启动ed/ # Section folder 安装ation.md quick启动.md API-reference/ authentication.md 端点s.md

Frontmatter fields:

---

description: Page description for SEO icon: book-open hidden: true vars: page_variable: value if: visitor.clAIms.un签名ed.condition layout: width: default # or 'wide' 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: space.vars.variableName

Most common custom blocks:

{% tabs %}...{% endtabs %} for alternatives {% hint style="..." %}...{% endhint %} for callouts {% stepper %}...{% endstepper %} for sequential steps

...... for expandable content

Links:

External: text Internal: Use relative paths like text or text

Key reminders:

Read SUMMARY.md first when working with existing content to understand structure Test in GitBook after editing locally Keep SUMMARY.md 同步hronized with your file structure Variables are defined in .gitbook/vars.yaml (space-level) or page frontmatter (page-level) OpenAPI specs must be 上传ed via API/命令行工具/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 %} 图形界面des users through multi-step processes with clear 进度ion Alternative options (languages, 平台s) {% tabs %} Lets users choose their relevant option without cluttering the page Optional or detAIled in格式化ion

(Expandable) Keeps page 扫描nable while providing depth for interested readers 导入ant 警告s or tips {% hint %} Draws attention with colored styling (信息, 警告, danger, 成功) Side-by-side comparisons {% columns %} Shows related in格式化ion in parallel (max 2 columns) Timeline or change记录 {% 更新s %} Displays dated entries in reverse chrono记录ical order Visual navigation cards 创建s 命令行工具ckable card grid for section navigation 下载able files {% file %} Provides files with captions and descriptions Call-to-action links Highlights primary or secondary actions Reusable content across pages {% include %} MAIntAIns consistency for repeated content blocks Dynamic content Displays variable values that 更新 automatically

Variable scope decision:

If variable is... Define it as... 访问 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 同步ed to Git, follow this 工作流 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. 检查 .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/as设置s/ - ContAIns all 上传ed images and files referenced in the documentation 检查 .gitbook/vars.yaml - ContAIns space-level variables if any are defined

This 应用roach ensures you understand the existing structure before making changes, helping you mAIntAI