gitbook

What this skill does

# GitBook Documentation Skill

Master GitBook for publishing professional documentation and books with spaces, collections, content variants, Git synchronization, team collaboration, and API integration. Build beautiful, searchable documentation sites with powerful collaboration features.

## When to Use This Skill

### USE GitBook when:
- **Team documentation** - Collaborative docs with multiple editors
- **Product documentation** - User guides, API docs, tutorials
- **Knowledge bases** - Internal wikis and knowledge management
- **Multi-version docs** - Maintain docs for different product versions
- **Git-based workflow** - Sync docs with GitHub/GitLab
- **Custom branding** - Need custom domains and styling
- **Access control** - Restrict docs to authenticated users
- **Quick setup** - Need docs fast without build systems

### DON'T USE GitBook when:
- **Complex code docs** - Use Sphinx for Python API docs
- **Static site control** - Use MkDocs or Docusaurus
- **Offline-first** - GitBook is primarily cloud-hosted
- **Self-hosted required** - GitBook is SaaS (legacy self-hosted deprecated)
- **Free unlimited** - Free tier has limitations

## Prerequisites

### GitBook Account Setup

```bash
# 1. Sign up at https://www.gitbook.com/
# 2. Create an organization (or use personal space)
# 3. Generate API token at:
#    https://app.gitbook.com/account/developer

# Set environment variable
export GITBOOK_API_TOKEN="gb_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Verify authentication
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "https://api.gitbook.com/v1/user" | jq '.id, .displayName'
```

### Git Sync Setup

```bash
# In your GitBook space settings:
# 1. Go to Integrations > Git Sync
# 2. Connect GitHub/GitLab account
# 3. Select repository and branch

# Repository structure
docs-repo/
├── README.md           # Main page (or SUMMARY.md)
├── SUMMARY.md          # Table of contents
├── chapter-1/
│   ├── README.md       # Chapter intro
│   ├── page-1.md
│   └── page-2.md
├── chapter-2/
│   └── ...
└── .gitbook.yaml       # GitBook config (optional)
```

### Python Setup

```bash
# Install dependencies
pip install requests python-dateutil

# Using uv
uv pip install requests python-dateutil

# Verify
python -c "import requests; print('Ready for GitBook integration!')"
```

## Core Capabilities

### 1. API Authentication

**REST API Basics:**
```bash
# GitBook API base URL
API_BASE="https://api.gitbook.com/v1"

# Get current user
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/user" | jq

# List organizations
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/orgs" | jq

# Get organization details
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/orgs/ORG_ID" | jq
```

**Python API Client:**
```python
import requests
from datetime import datetime
import os

class GitBookClient:
    """GitBook API client."""

    BASE_URL = "https://api.gitbook.com/v1"

    def __init__(self, api_token=None):
        self.api_token = api_token or os.environ.get("GITBOOK_API_TOKEN")
        self.headers = {
            "Authorization": f"Bearer {self.api_token}",
            "Content-Type": "application/json"
        }

    def _request(self, method, endpoint, data=None, params=None):
        """Make API request."""
        url = f"{self.BASE_URL}{endpoint}"
        response = requests.request(
            method,
            url,
            headers=self.headers,
            json=data,
            params=params
        )
        response.raise_for_status()
        return response.json() if response.text else None

    def get_user(self):
        """Get current user."""
        return self._request("GET", "/user")

    def list_organizations(self):
        """List all organizations."""
        return self._request("GET", "/orgs")

    def get_organization(self, org_id):
        """Get organization details."""
        return self._request("GET", f"/orgs/{org_id}")


# Example usage
if __name__ == "__main__":
    client = GitBookClient()

    user = client.get_user()
    print(f"User: {user['displayName']}")

    orgs = client.list_organizations()
    for org in orgs.get("items", []):
        print(f"Org: {org['title']}")
```

### 2. Spaces Management

**REST API - Spaces:**
```bash
# List spaces in organization
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/orgs/ORG_ID/spaces" | jq

# Get space details
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID" | jq

# Create space
curl -s -X POST -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    -H "Content-Type: application/json" \
    "$API_BASE/orgs/ORG_ID/spaces" \
    -d '{
        "title": "API Documentation",
        "visibility": "public"
    }' | jq

# Update space
curl -s -X PATCH -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    -H "Content-Type: application/json" \
    "$API_BASE/spaces/SPACE_ID" \
    -d '{
        "title": "Updated API Documentation",
        "visibility": "private"
    }' | jq

# Delete space
curl -s -X DELETE -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID"

# Get space content (pages)
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID/content" | jq
```

**Python - Spaces:**
```python
class GitBookClient:
    # ... previous methods ...

    def list_spaces(self, org_id):
        """List all spaces in organization."""
        return self._request("GET", f"/orgs/{org_id}/spaces")

    def get_space(self, space_id):
        """Get space details."""
        return self._request("GET", f"/spaces/{space_id}")

    def create_space(self, org_id, title, visibility="public"):
        """Create a new space."""
        return self._request(
            "POST",
            f"/orgs/{org_id}/spaces",
            data={"title": title, "visibility": visibility}
        )

    def update_space(self, space_id, **kwargs):
        """Update space settings."""
        return self._request(
            "PATCH",
            f"/spaces/{space_id}",
            data=kwargs
        )

    def delete_space(self, space_id):
        """Delete a space."""
        return self._request("DELETE", f"/spaces/{space_id}")

    def get_space_content(self, space_id):
        """Get space content structure."""
        return self._request("GET", f"/spaces/{space_id}/content")


# Example usage
spaces = client.list_spaces("org_xxxxx")
for space in spaces.get("items", []):
    print(f"Space: {space['title']} ({space['visibility']})")

# Create new space
new_space = client.create_space(
    org_id="org_xxxxx",
    title="Developer Guide",
    visibility="public"
)
print(f"Created: {new_space['id']}")
```

### 3. Content Management

**REST API - Content:**
```bash
# Get page content
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID/content/page/PAGE_ID" | jq

# List pages in space
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID/content" | jq '.pages'

# Import content from Git
curl -s -X POST -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    -H "Content-Type: application/json" \
    "$API_BASE/spaces/SPACE_ID/content/import/git" \
    -d '{
        "url": "https://github.com/user/docs-repo",
        "ref": "main"
    }' | jq

# Export content
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID/content/export" \
    -o content-export.zip

# Search content
curl -s -H "Authorization: Bearer $GITBOOK_API_TOKEN" \
    "$API_BASE/spaces/SPACE_ID/search?query=installation" | jq
```

**Python - Content:**
```python
class GitBookClient:
    # ... previous methods ...

    def get_page(self, space_id, page_id):
        """Get page content."""
        return self._request(
            "GET",
            f"/spaces/{space_id}/content/page/{page_id}"
        )

    def list_pages(self, space_id):
        """List all pages in space."""
        c