gitbook
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGitBook Skill
GitBook Skill
—
何时使用此Skill
Use when working with GitBook documentation platform, generated from official documentation (107 pages).
在以下场景中应触发此Skill：
- 创建或管理GitBook文档空间
- 设置Git同步（GitHub/GitLab）
- 使用自定义域名发布文档站点
- 操作GitBook的块编辑器
- 配置OpenAPI/API参考文档
- 管理团队协作与变更请求
- 将内容迁移至GitBook
- 自定义站点外观与品牌标识
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
| 概念 | 描述 |
|---|---|
| Space | 一个文档项目（类似书籍或维基） |
| Collection | 一组相关的Space |
| Site | 可通过URL访问的已发布文档 |
| Change Request | 发布前需审核的草稿变更 |
| Live Edits | 无需变更请求流程的直接修改 |
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 |
GitBook使用块编辑器。常见区块：
| 区块 | 快捷键 | 描述 |
|---|---|---|
| Paragraph | 直接输入 | 默认文本区块 |
| Heading | | 章节标题（H1、H2、H3） |
| Code Block | ``` or | 带语法高亮的代码块 |
| Quote | | 引用块 |
| List | | 无序列表/有序列表 |
| Task List | | 复选框项 |
| Table | | 数据表格 |
| Image | | 上传或嵌入图片 |
| Tabs | | 标签页内容 |
| Expandable | | 可折叠章节 |
| Cards | | 可视化链接卡片 |
| Hint | | 信息、警告、危险、成功提示框 |
| API Reference | | OpenAPI规范集成 |
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 | Syntax-highlighted code |
| Quote | | Blockquote |
| List | | Unordered/ordered lists |
| Task List | | Checkbox items |
| Table | | Data tables |
| Image | | Upload or embed images |
| Tabs | | Tabbed content |
| Expandable | | Collapsible sections |
| Cards | | Visual link cards |
| Hint | | Info, warning, danger, success boxes |
| API Reference | | OpenAPI spec integration |
在任意文本区块中按可访问：
/- 链接 - 相对（内部）或绝对（外部）链接
- 图片 - 行内图片
- 表情符号 - 使用语法
:emoji_name: - 数学公式 - LaTeX/KaTeX公式：
$$formula$$ - 注释 - 脚注式说明
Inline Content (/) Palette
常用模板
—
创建提示/标注框
Press in any text block to access:
/- Link - Relative (internal) or absolute (external) links
- Image - Inline images
- Emoji - syntax
:emoji_name: - Math - LaTeX/KaTeX formulas:
$$formula$$ - Annotation - Footnote-style explanations
markdown
{% 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 %}Common Patterns
创建标签页
Create a hint/callout box
—
markdown
{% 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 %}markdown
{% tabs %}
{% tab title="JavaScript" %}
console.log("Hello");
{% endtab %}
{% tab title="Python" %}
print("Hello")
{% endtab %}
{% endtabs %}Create tabs
创建可折叠章节
markdown
{% tabs %}
{% tab title="JavaScript" %}
console.log("Hello");
{% endtab %}
{% tab title="Python" %}
print("Hello")
{% endtab %}
{% endtabs %}markdown
{% expandable title="Click to expand" %}
Hidden content here
{% endexpandable %}Create expandable section
创建步骤指引（编号步骤）
markdown
{% expandable title="Click to expand" %}
Hidden content here
{% endexpandable %}markdown
{% stepper %}
{% step %}
First step content
{% endstep %}
{% step %}
Second step content
{% endstep %}
{% endstepper %}Create stepper (numbered steps)
创建卡片
markdown
{% stepper %}
{% step %}
First step content
{% endstep %}
{% step %}
Second step content
{% endstep %}
{% endstepper %}markdown
{% cards %}
{% card title="Card 1" href="/page1" %}
Description here
{% endcard %}
{% card title="Card 2" href="/page2" %}
Another description
{% endcard %}
{% endcards %}Create cards
Git同步配置
—
启用GitHub同步
markdown
{% cards %}
{% card title="Card 1" href="/page1" %}
Description here
{% endcard %}
{% card title="Card 2" href="/page2" %}
Another description
{% endcard %}
{% endcards %}- 进入Space设置 → Git同步
- 连接GitHub账户
- 选择仓库和分支
- 配置同步方向：
- GitBook → GitHub：GitBook为可信数据源
- GitHub → GitBook：Git仓库为可信数据源
- 双向：双向同步
Git Sync Configuration
Git目录结构
Enable GitHub Sync
—
- Go to space settings → Git Sync
- Connect GitHub account
- Select repository and branch
- Configure sync direction:
- GitBook → GitHub: GitBook is source of truth
- GitHub → GitBook: Git repo is source of truth
- Two-way: Bidirectional sync
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 filesDirectory structure for Git
SUMMARY.md结构
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 filesmarkdown
undefinedSUMMARY.md structure
Table of contents
markdown
undefined- Introduction
- Getting Started
Table of contents
Section Title
- Introduction
- Getting Started
- Page One
- Page Two
undefinedSection Title
.gitbook.yaml配置
- Page One
- Page Two
undefinedyaml
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.gitbook.yaml configuration
自定义域名设置
yaml
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- 进入站点设置 → 自定义域名
- 添加你的域名（例如）
docs.example.com - 配置DNS：
- CNAME记录：指向
hosting.gitbook.io - 或者对于 apex 域名使用A记录
- CNAME记录：指向
- 启用HTTPS（通过Let's Encrypt自动配置）
Custom Domain Setup
子目录发布（搭配Cloudflare/Vercel）
- Go to site settings → Custom domain
- Add your domain (e.g., )
docs.example.com - Configure DNS:
- CNAME record: Point to
hosting.gitbook.io - Or A record for apex domains
- CNAME record: Point to
- Enable HTTPS (automatic via Let's Encrypt)
example.com/docs → GitBook siteSubdirectory publishing (with Cloudflare/Vercel)
OpenAPI集成
—
添加OpenAPI规范
example.com/docs → GitBook site- 上传OpenAPI/Swagger文件（JSON或YAML格式）
- 或链接至托管的规范URL
- GitBook自动生成交互式API文档
OpenAPI Integration
自定义API参考
Add OpenAPI specification
—
- Upload OpenAPI/Swagger file (JSON or YAML)
- Or link to hosted spec URL
- GitBook auto-generates interactive API docs
markdown
{% openapi src="./api.yaml" /%}Customize API reference
发布选项
markdown
{% openapi src="./api.yaml" /%}| 类型 | 描述 |
|---|---|
| Public | 所有人可访问 |
| Unlisted | 不被搜索引擎收录，仅可通过URL访问 |
| Share links | 基于令牌的私有访问 |
| Authenticated | 需要SSO/登录验证 |
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
迁移至GitBook
—
从其他平台迁移
- Inline comments on any block
- @mention team members
- Resolve when addressed
- 导入面板：支持Confluence、Notion、Docusaurus、Markdown
- Git同步：连接现有的包含Markdown文件的Git仓库
- 手动方式：复制粘贴并保留格式
Migration to GitBook
通过Git同步导入
From other platforms
—
- Import panel: Confluence, Notion, Docusaurus, Markdown
- Git Sync: Connect existing Git repo with markdown files
- Manual: Copy/paste with formatting preserved
bash
undefinedImport via Git Sync
Prepare your repo
bash
undefinedmkdir docs
echo "# Welcome" > docs/README.md
echo "* Welcome" > docs/SUMMARY.md
git add . && git commit -m "Initial docs"
undefinedPrepare your repo
键盘快捷键
mkdir docs
echo "# Welcome" > docs/README.md
echo "* Welcome" > docs/SUMMARY.md
git add . && git commit -m "Initial docs"
undefined| 操作 | 快捷键 |
|---|---|
| 命令面板 | |
| 加粗 | |
| 斜体 | |
| 链接 | 选中内容后按 |
| 代码 | |
| 搜索 | |
Keyboard Shortcuts
参考文件
| Action | Shortcut |
|---|---|
| Command palette | |
| Bold | |
| Italic | |
| Link | |
| Code | |
| Search | |
此Skill在目录中包含完整文档：
references/- llms-txt.md - 完整GitBook文档（107页，456 KB）
- llms-full.md - 完整的llms.txt源文件
- llms.md - 精简版参考文档（95 KB）
当需要详细信息时，使用命令查看特定参考文件。
viewReference 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 to read specific reference files when detailed information is needed.
view参考文档涵盖以下类别：
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
- 站点与自定义域名
- 公开与私有发布
- 分享链接与身份验证
- 重定向与SEO
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
- Git同步（GitHub、GitLab）
- OpenAPI/API文档
- 翻译
- 扩展
Integration
配置
- Git Sync (GitHub, GitLab)
- OpenAPI/API documentation
- Translations
- Extensions
- 站点结构与主题
- 图标、颜色与品牌标识
- 内容配置
- 故障排除
Configuration
常见问题
—
Git同步失败
- Site structure and theming
- Icons, colors, and branding
- Content configuration
- Troubleshooting
- 检查仓库权限
- 验证分支是否存在
- 确保SUMMARY.md格式有效
- 检查是否存在合并冲突
Common Issues
自定义域名问题
Git Sync not working
—
- Check repository permissions
- Verify branch exists
- Ensure SUMMARY.md is valid
- Check for merge conflicts
- 验证DNS传播（可能需要24-48小时）
- 检查CNAME是否指向
hosting.gitbook.io - 确保无冲突记录
Custom domain issues
内容未更新
- Verify DNS propagation (can take 24-48 hours)
- Check CNAME points to
hosting.gitbook.io - Ensure no conflicting records
- 检查是否有待处理的变更请求
- 验证Git同步状态
- 清除浏览器缓存
- 检查是否存在合并冲突
Content not updating
注意事项
- Check for pending change requests
- Verify Git sync status
- Clear browser cache
- Check for merge conflicts
- 此Skill由官方GitBook文档通过llms.txt生成
- 参考文件包含107页完整文档
- 内容截至2026年1月为最新版本
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
—