GitBook

collaborationdocumentationtechnical writingAPI docsreal-time editinggit integration

Collaboration Tool

GitBook

Overview

GitBook is a collaboration and documentation creation platform specialized for technical and API documentation. It provides developer-friendly Markdown editing, real-time collaboration, Git integration for version control, and automatic OpenAPI specification generation. Established as a standard for technical documentation creation in engineering teams, product teams, and startups. Enhanced in 2024-2025 with real-time collaboration, AI translation features, OpenAPI improvements, and review system upgrades, realizing modern documentation workflows.

Details

GitBook 2025 edition has evolved as the leading collaboration platform for technical documentation creation. Full support for WYSIWYG (What You See Is What You Get) editor and Markdown notation enables efficient documentation creation for both engineers and non-engineers. Real-time collaboration features allow multiple members to edit simultaneously, with colored cursors and avatar displays visualizing collaborative activity. Git integration (GitHub/GitLab) establishes branch-based workflows, change request systems, and advanced permission management for quality control and collaboration in large teams. Major 2024 updates include significant OpenAPI specification improvements, deprecation of editable API method blocks, AI translation automation for multilingual support, and "Try It" functionality enhancement powered by the Scalar engine. Developer API, external system integration, and custom feature extensions completely optimize technical organization documentation workflows.

Key Features

Real-time Collaboration: Simultaneous editing, colored cursors, avatar display
Git Integration Workflow: GitHub/GitLab integration, branch-based editing
OpenAPI Auto-generation: Automatic documentation generation and testing from specifications
Markdown + WYSIWYG: Developer-friendly editing experience
AI Translation Features: Automatic multilingual support and localization
Advanced Permission Management: Team-based access control and approval flows

Advantages and Disadvantages

Advantages

Optimized editing experience for both developers and product teams
Powerful version control and collaborative workflows through Git integration
Automatic API documentation generation and testing from OpenAPI specifications
Efficient team collaboration through real-time collaboration features
Automation of multilingual support through AI translation and reduced workload
Low learning cost due to intuitive UI/UX
Tiered pricing supporting startups to large enterprises
Rich integrations and external system connectivity

Disadvantages

Performance issues with complex document structures or large-scale documents
Technical knowledge required for advanced customization
Enterprise features require expensive paid plans
Limited offline editing functionality
Git integration unavailable in published spaces
Development work required for external system integration
Limited data export functionality during migration
Constraints in advanced Japanese search functionality

Reference Links

Usage Examples

Basic Setup and Workspace Creation

# GitBook basic setup
# 1. Create GitBook account: https://www.gitbook.com/
# 2. Create organization
# 3. Create space
# 4. Configure Git integration (GitHub/GitLab)
# 5. Invite team members and set permissions

# Basic space structure example
Technical Documentation Space/
├── Getting Started/
│   ├── Overview.md
│   ├── Installation.md
│   └── Quick Start.md
├── API Reference/
│   ├── Authentication.md
│   ├── Endpoints/
│   └── Error Handling.md
├── Guides/
│   ├── Best Practices/
│   ├── Tutorials/
│   └── FAQ.md
└── Changelog/
    ├── v2.0.0.md
    ├── v1.9.0.md
    └── Archive/

# Recommended folder structure (Git sync)
docs/
├── .gitbook.yaml
├── README.md
├── SUMMARY.md
├── getting-started/
├── api/
├── guides/
└── changelog/

GitBook API Basic Operations

// GitBook API basic configuration
const GITBOOK_API_BASE = 'https://api.gitbook.com/v1';
const GITBOOK_TOKEN = process.env.GITBOOK_TOKEN;

class GitBookAPI {
  constructor(token) {
    this.token = token;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    };
  }

  // Get organization information
  async getOrganization(orgId) {
    try {
      const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}`, {
        method: 'GET',
        headers: this.headers,
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      console.error('Organization retrieval error:', error);
      throw error;
    }
  }

  // Get spaces list
  async getSpaces(orgId) {
    try {
      const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/spaces`, {
        method: 'GET',
        headers: this.headers,
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      console.error('Spaces list retrieval error:', error);
      throw error;
    }
  }

  // Invite new users
  async inviteUsers(orgId, emails, role = 'read', sso = true) {
    try {
      const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/invites`, {
        method: 'POST',
        headers: this.headers,
        body: JSON.stringify({
          emails: emails,
          role: role,
          sso: sso,
        }),
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      console.error('User invitation error:', error);
      throw error;
    }
  }

  // Manage team members
  async manageTeamMembers(orgId, teamId, addEmails = [], removeEmails = []) {
    try {
      const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/teams/${teamId}/members`, {
        method: 'PUT',
        headers: this.headers,
        body: JSON.stringify({
          add: addEmails,
          remove: removeEmails,
        }),
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      console.error('Team member management error:', error);
      throw error;
    }
  }

  // Remove user
  async removeUser(orgId, userId) {
    try {
      const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/members/${userId}`, {
        method: 'DELETE',
        headers: this.headers,
      });

      if (!response.ok) {
        throw new Error(`HTTP Error: ${response.status}`);
      }

      return true;
    } catch (error) {
      console.error('User removal error:', error);
      throw error;
    }
  }
}

// Usage example
const gitbook = new GitBookAPI(GITBOOK_TOKEN);

// Organization team management example
async function manageOrganizationUsers() {
  try {
    const orgId = 'your-org-id';
    
    // Invite new users
    const inviteResult = await gitbook.inviteUsers(
      orgId,
      ['[email protected]', '[email protected]'],
      'write',
      true
    );
    console.log('Invitation completed:', inviteResult);

    // Add/remove team members
    const teamResult = await gitbook.manageTeamMembers(
      orgId,
      'team-id-123',
      ['[email protected]'],
      ['[email protected]']
    );
    console.log('Team updated:', teamResult);

  } catch (error) {
    console.error('Team management error:', error);
  }
}

Git Integration and .gitbook.yaml Configuration

# .gitbook.yaml - GitBook and Git repository integration configuration

# Root directory configuration
root: ./docs

# Document structure definition
structure:
  readme: README.md
  summary: SUMMARY.md

# Redirect configuration
redirects:
  help: support.md
  guide: getting-started.md

# Monorepo support example
# packages/
#   api/
#     .gitbook.yaml
#     README.md
#     SUMMARY.md
#   frontend/
#     .gitbook.yaml
#     README.md
#     SUMMARY.md

# Custom configuration example (multiple projects)
# Project A configuration
---
# packages/api/.gitbook.yaml
root: ./

structure:
  readme: README.md
  summary: SUMMARY.md

redirects:
  api-v1: legacy/api-v1.md
  
---
# packages/frontend/.gitbook.yaml  
root: ./

structure:
  readme: README.md
  summary: SUMMARY.md

redirects:
  old-guide: archive/old-guide.md

OpenAPI Integration and Automatic API Documentation Generation

# Upload OpenAPI specification using GitBook CLI
export GITBOOK_TOKEN=your-api-token

# Upload local file
gitbook openapi publish \
  --spec api_spec_name \
  --organization your_org_id \
  ./openapi.yaml

# Update from hosted URL
gitbook openapi publish \
  --spec api_spec_name \
  --organization your_org_id \
  https://api.example.com/openapi.yaml

# Force update specification (after new release, etc.)
gitbook openapi publish \
  --spec api_spec_name \
  --organization your_org_id \
  https://api.example.com/openapi.yaml \
  --force

# GitBook extension usage example in OpenAPI specification
openapi: '3.0.3'
info:
  title: Example API
  version: '1.0.0'
  description: GitBook integrated API specification example

# Page structure control
tags:
  - name: users
    x-page-title: "User Management"
    x-page-description: "Manage user accounts and profiles"
    x-page-icon: "user"
    description: |
      All user-related operations
      
      {% raw %}
      {% tabs %}
      {% tab title="Overview" %}
      User management API overview
      {% endtab %}
      {% tab title="Authentication" %}
      Authentication method details
      {% endtab %}
      {% endtabs %}
      {% endraw %}

  - name: admin
    x-parent: users  # Hierarchical organization

paths:
  /users:
    get:
      tags:
        - users
      summary: Get users list
      description: Retrieve list of users in the system
      x-stability: stable
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl -L \
            -H 'Authorization: Bearer <token>' \
            'https://api.example.com/users'
        - lang: 'JavaScript'
          label: 'Node.js SDK'
          source: |
            import { createAPIClient } from 'example-api-sdk';
            
            const client = createAPIClient({ apiKey: 'your-key' });
            const users = await client.users.list();
            console.log(users);
      responses:
        '200':
          description: Success

  /users/{id}:
    get:
      tags:
        - users
      summary: Get user details
      deprecated: true
      x-deprecated-sunset: 2025-12-31
      x-hideTryItPanel: true  # Hide test panel
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success

  /internal/admin:
    get:
      summary: Internal admin functionality
      x-internal: true  # Hide from documentation
      responses:
        '200':
          description: Success

components:
  schemas:
    UserStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - PENDING
      x-enumDescriptions:
        ACTIVE: Active user
        INACTIVE: Inactive user
        PENDING: User pending approval

Real-time Collaboration and Review Workflows

# Collaborative Editing and Review Process in GitBook

## Real-time Collaboration Features
- **Simultaneous editing**: Multiple users can edit simultaneously
- **Avatar display**: Avatars of editing users appear in the top right of the page
- **Colored cursors**: Other users' editing positions displayed in real-time
- **Limitations**: Not available in published spaces or when Git sync is enabled

## Change Request Workflow
1. **Create change request**
   - Create draft changes
   - Assign reviewers
   - Include change rationale and comments

2. **Review process**
   - Content review by reviewers
   - Comments and feedback
   - Approval or rejection

3. **Merge operation**
   - Execute merge after approval
   - Automatic history recording
   - Version management

## Git Integration Workflow
```bash
# Branch-based workflow example

# Create new feature development branch
git checkout -b feature/api-documentation
git push -u origin feature/api-documentation

# Editing in GitBook
# 1. Edit documents in GitBook editor
# 2. Automatically sync to branch
# 3. Commit history automatically recorded

# Review and merge
# 1. Create Pull Request in GitHub/GitLab
# 2. Code review and GitBook change verification
# 3. Merge after approval
git checkout main
git merge feature/api-documentation
git push origin main

# Production reflection in GitBook
# GitBook automatically updates after main branch merge

Advanced Features and Customization

// GitBook Adaptive Content configuration
// Dynamic content display through visitor authentication

import * as jose from 'jose';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/docs';

// GitBook adaptive content configuration after user authentication
export async function handleUserLogin(req, res) {
  // Get user information
  const userInfo = await getUserInfo(req.user.id);
  
  // Create GitBook claims
  const gitbookClaims = {
    firstName: userInfo.firstName,
    lastName: userInfo.lastName,
    role: userInfo.role,
    isBetaUser: userInfo.isBetaUser,
    products: userInfo.accessibleProducts,
    featureFlags: await getFeatureFlags(req.user.id),
  };

  // Generate and sign JWT
  const gitbookVisitorJWT = await new jose.SignJWT(gitbookClaims)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h')
    .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));

  // Set as session cookie (recommended)
  res.cookie('gitbook-visitor-token', gitbookVisitorJWT, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 2 * 60 * 60 * 1000, // 2 hours
    domain: '.example.com', // Wildcard setting
  });

  // Or direct redirect with URL parameter
  const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
  res.redirect(redirectURL);
}

// Adaptive content schema definition
const adaptiveContentSchema = {
  type: "object",
  properties: {
    isBetaUser: {
      type: "boolean",
      description: "Whether the user is a beta user"
    },
    role: {
      type: "string",
      enum: ["user", "admin", "developer"],
      description: "User role"
    },
    products: {
      type: "array",
      items: { type: "string" },
      description: "Accessible products"
    },
    featureFlags: {
      type: "object",
      additionalProperties: { type: "boolean" },
      description: "Feature flags"
    }
  },
  additionalProperties: false
};

// Multi-tenant support example
export async function handleMultiTenantAuth(req, res) {
  const tenantId = req.query.tenant;
  const tenantConfig = await getTenantConfig(tenantId);
  
  const gitbookVisitorJWT = await new jose.SignJWT({
    tenantId: tenantId,
    tenantName: tenantConfig.name,
    userRole: req.user.role,
  })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h')
    .sign(new TextEncoder().encode(tenantConfig.jwtSigningKey));
    
  const redirectURL = `${tenantConfig.gitbookUrl}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
  res.redirect(redirectURL);
}

AI Translation and Localization Automation

# Utilizing GitBook AI translation features
# Automatic translation feature added in 2024

# Basic multilingual setup
# 1. Enable "Languages" setting in GitBook space
# 2. Set source language (e.g., English) and target language (Japanese)
# 3. Configure automatic AI translation execution

# Translation workflow example
echo "Original update → AI automatic translation → Review → Publish"

# Manual translation execution (when needed)
# Click "Translate" button in GitBook UI
# Or automatic translation execution when changes detected

# Translation quality management
echo "Human review after AI translation recommended"
echo "Pre-setting glossary effective for improving translation quality"

<!-- GitBook adaptive content description example -->

# API Documentation

{% if visitor.isBetaUser %}
## Beta Features
You can try new API features.

{% openapi-schemas spec="beta-api" schemas="BetaEndpoint" %}
Beta version exclusive endpoints
{% endopenapi-schemas %}
{% endif %}

{% if "ENTERPRISE" in visitor.products %}
## Enterprise Features
You can use advanced security and scalability features.

- SSO integration
- Advanced analytics
- Premium support
{% endif %}

{% if visitor.role == "admin" %}
## Administrator Information
{% tabs %}
{% tab title="User Management" %}
User management feature details
{% endtab %}
{% tab title="System Settings" %}
System settings management methods
{% endtab %}
{% endtabs %}
{% endif %}

## Basic Features
Basic features available to all users.