Overview
GitBook is a modern documentation platform that enables teams to create, edit, and publish beautiful documentation sites. It combines a web-based editor with Git synchronization, allowing technical and non-technical team members to collaborate using either the visual editor or Markdown files in a Git repository. GitBook handles hosting, search, and custom domains automatically.
GitBook supports rich content blocks, embedded API references, OpenAPI integration, custom branding, visitor authentication, and analytics. It is widely used for product documentation, internal knowledge bases, API references, and engineering handbooks.
Getting Started
Organization Structure
Organization
├── Spaces (individual doc sites)
│ ├── Product Docs
│ ├── API Reference
│ └── Internal Wiki
├── Collections (grouping of spaces)
│ └── Developer Portal
│ ├── Getting Started
│ └── SDK Guides
└── Members and Teams
Content Editing
Keyboard Shortcuts
| Shortcut | Action |
|---|
Ctrl+K | Quick find / command palette |
Ctrl+N | New page |
Ctrl+S | Save changes |
Ctrl+B | Bold text |
Ctrl+I | Italic text |
Ctrl+Shift+K | Insert link |
Ctrl+E | Inline code |
Ctrl+Shift+1 | Heading 1 |
Ctrl+Shift+2 | Heading 2 |
Ctrl+Shift+3 | Heading 3 |
/ | Slash command (insert block) |
Content Blocks
| Block | Description |
|---|
| Paragraph | Standard text |
| Heading | H1, H2, or H3 |
| Code block | Syntax-highlighted code |
| Hint | Info, warning, danger, success callouts |
| Table | Data table |
| Tabs | Tabbed content sections |
| Expandable | Collapsible content |
| API method | REST API endpoint documentation |
| OpenAPI | Import OpenAPI specification |
| Embed | URL embed (YouTube, Figma, etc.) |
| Drawing | Inline diagram tool |
| Math | LaTeX math equations |
| Image | Image upload or URL |
| File | Uploadable file |
Hint Blocks
{% hint style="info" %}
Informational hint.
{% endhint %}
{% hint style="warning" %}
Warning hint.
{% endhint %}
{% hint style="danger" %}
Danger callout.
{% endhint %}
{% hint style="success" %}
Success message.
{% endhint %}
Tabs
{% tabs %}
{% tab title="npm" %}
npm install my-package
{% endtab %}
{% tab title="yarn" %}
yarn add my-package
{% endtab %}
{% endtabs %}
Git Sync
File Structure in Git
docs/
├── README.md
├── SUMMARY.md
├── getting-started/
│ ├── README.md
│ ├── installation.md
│ └── configuration.md
├── api-reference/
│ ├── README.md
│ └── endpoints.md
└── .gitbook/
└── assets/
SUMMARY.md (Navigation)
# Table of contents
* [Welcome](README.md)
## Getting Started
* [Installation](getting-started/installation.md)
* [Configuration](getting-started/configuration.md)
## API Reference
* [Endpoints](api-reference/endpoints.md)
Change Requests
| Step | Description |
|---|
| Create | Start a change request from any page |
| Edit | Make changes in isolated branch |
| Review | Team members review and comment |
| Merge | Merge approved changes into main content |
Customization
| Setting | Options |
|---|
| Logo | Upload custom logo |
| Colors | Primary color, header, sidebar |
| Favicon | Custom browser tab icon |
| Custom domain | Map your own domain |
| Header links | Add navigation links |
Custom Domain Setup
- Go to Space settings then Custom domain
- Enter your domain (e.g., docs.example.com)
- Add CNAME record pointing to hosting.gitbook.io
- SSL certificate is provisioned automatically
API
# List spaces
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://api.gitbook.com/v1/orgs/ORG_ID/spaces
# Get page content
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://api.gitbook.com/v1/spaces/SPACE_ID/content
# Search content
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://api.gitbook.com/v1/spaces/SPACE_ID/search?query=authentication"
Integrations
| Integration | Features |
|---|
| GitHub | Bidirectional sync |
| GitLab | Bidirectional sync |
| Slack | Notifications for changes |
| Google Analytics | Track visitor behavior |
| Figma | Embed design files |
| Plausible | Privacy-friendly analytics |
Advanced Features
OpenAPI Integration
Import OpenAPI/Swagger specs to auto-generate interactive API documentation with request/response examples.
Visitor Authentication
| Method | Description |
|---|
| Public | Anyone can access |
| Unlisted | Only accessible via direct link |
| Share links | Password-protected share links |
| Visitor auth | SSO-based authentication |
Troubleshooting
| Issue | Solution |
|---|
| Git sync failing | Check repository permissions; verify branch exists |
| Changes not publishing | Ensure change request is merged |
| Custom domain SSL error | Verify CNAME record; wait up to 24 hours |
| Images not loading | Check file paths; re-upload assets |
| Search not finding content | Wait for indexing |
| SUMMARY.md not reflecting | Check Markdown syntax; check indentation |
| Merge conflicts | Resolve in Git; re-sync from repository |
| Slow page load | Optimize images; reduce embedded content |
