Documentation Tool

GitBook

Overview

GitBook is a modern documentation platform. It integrates Git workflows, API documentation, and real-time collaboration features to optimize technical teams' documentation workflows.

Details

GitBook was founded in 2014 and has achieved rapid growth as a solution that bridges the gap between traditional documentation tools and software development workflows. The block-based WYSIWYG editor enables integrated management of text, code, images, and API specifications. Git sync functionality allows development teams to directly integrate with GitHub and GitLab repositories, automatically reflecting Markdown file changes in documentation. OpenAPI specification auto-import significantly streamlines API documentation. Branch-based workflows enable applying quality control processes similar to code reviews to documentation creation. Real-time collaborative editor supports simultaneous editing and commenting with team members. AI translation features streamline multilingual document creation and maintenance. As of 2025, it serves as a comprehensive documentation platform used across a wide range of applications including technical documentation, product guides, API references, and internal knowledge bases.

Advantages and Disadvantages

Advantages

• Git Integration Workflow: Complete integration with GitHub and GitLab for developer-friendly document management
• API Documentation Automation: Automatic generation of interactive documentation from OpenAPI specifications
• Real-time Collaboration: Team work efficiency through simultaneous editing, commenting, and review features
• Block-based Editor: Document creation with free combination of code, tables, and media
• AI Translation Features: Automation of multilingual document creation and maintenance
• Branch-based Workflow: Quality control processes similar to code reviews
• Rich Integration Capabilities: Integration with Slack, Figma, Notion, and others

Disadvantages

• Pricing Structure: Monthly cost burden for team usage
• Learning Curve: Technical knowledge required to leverage Git integration features
• Customization Limitations: Limited freedom in theme and design customization
• Offline Functionality: Many features require internet connection
• Export Constraints: Format limitations when migrating to other tools

Key Links

• GitBook Official Site
• GitBook Documentation
• API Documentation Solutions
• Git Sync Guide
• GitBook Developer API
• Template Gallery

Usage Examples

Basic Document Structure

# Project Documentation

## Overview
Basic description of this project

## API Reference

{% swagger method="get" path="/api/users" baseUrl="https://api.example.com" summary="Get User List" %}
{% swagger-description %}
Retrieve a list of registered users.
{% endswagger-description %}

{% swagger-parameter in="query" name="page" type="integer" %}
Page number (default: 1)
{% endswagger-parameter %}

{% swagger-response status="200: OK" description="Successfully retrieved user list" %}
```json
{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 100
  }
}

{% endswagger-response %} {% endswagger %}

Code Block

{% code title="app.js" overflow="wrap" lineNumbers="true" %}

const express = require('express');
const app = express();

app.get('/api/users', (req, res) => {
  const page = req.query.page || 1;
  // User list retrieval logic
  res.json({
    users: [], // Actual user data
    pagination: { page, total: 100 }
  });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

{% endcode %}

### Git Sync Configuration (.gitbook.yaml)
```yaml
# Project root setting
root: ./docs/

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

# URL redirect settings
redirects:
  old-api-docs: api/v2/reference.md
  legacy-guide: getting-started/new-guide.md

Navigation Structure with SUMMARY.md

# Summary

## Getting Started

* [Project Overview](README.md)
* [Quick Start](getting-started/quick-start.md)
  * [Installation](getting-started/installation.md)
  * [Basic Configuration](getting-started/configuration.md)

## API Reference

* [Authentication](api/authentication.md)
* [User Management](api/users.md)
  * [Create User](api/users/create.md)
  * [Update User](api/users/update.md)
* [Data Management](api/data.md)

## Development Guide

* [Architecture](development/architecture.md)
* [Contributing](development/contributing.md)

OpenAPI Specification Integration

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API specification for user management system

tags:
  - name: users
    description: User-related operations
    x-page-title: "User Management"
    x-page-description: "User account creation, update, and deletion features"

paths:
  /users:
    get:
      tags:
        - users
      summary: Get user list
      description: Retrieve a list of registered users
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      tags:
        - users
      summary: Create user
      x-codeSamples:
        - lang: JavaScript
          label: Node.js SDK
          source: |
            const client = new UserClient({ apiKey: 'your-api-key' });
            
            const newUser = await client.users.create({
              name: 'John Doe',
              email: '[email protected]'
            });
            
            console.log('Created user:', newUser);

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: User ID
        name:
          type: string
          description: User name
        email:
          type: string
          format: email
          description: Email address

Automation with GitBook API

// Team management using GitBook API
const GITBOOK_API_KEY = process.env.GITBOOK_API_KEY;
const ORG_ID = 'your-org-id';

// Invite user to team
async function inviteUser(email, role = 'read') {
  const response = await fetch("https://api.gitbook.com/v1/orgs/" + ORG_ID + "/invites", {
    method: 'POST',
    headers: {
      'Authorization': "Bearer " + GITBOOK_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      emails: [email],
      role: role,
      sso: true
    })
  });
  
  const result = await response.json();
  console.log('User invited:', result);
  return result;
}

// Update OpenAPI specification
async function updateAPISpec(specName, openApiFile) {
  const { exec } = require('child_process');
  
  return new Promise((resolve, reject) => {
    exec("export GITBOOK_TOKEN=" + GITBOOK_API_KEY + " && gitbook openapi publish --spec " + specName + " --organization " + ORG_ID + " " + openApiFile, 
      (error, stdout, stderr) => {
        if (error) {
          reject(error);
        } else {
          resolve(stdout);
        }
      }
    );
  });
}

// Usage examples
inviteUser('[email protected]', 'write');
updateAPISpec('main-api', './openapi.yaml');

Adaptive Content with Visitor Authentication

// Visitor authentication via JWT generation
import * as jose from 'jose';

const VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;

export async function generateVisitorToken(userInfo) {
  const claims = {
    firstName: userInfo.firstName,
    lastName: userInfo.lastName,
    role: userInfo.role,
    betaAccess: userInfo.betaAccess,
    products: userInfo.subscribedProducts
  };
  
  const jwt = await new jose.SignJWT(claims)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h')
    .sign(new TextEncoder().encode(VISITOR_SIGNING_KEY));
    
  return jwt;
}

// Authentication handling in Express.js
app.post('/login', async (req, res) => {
  const user = await authenticateUser(req.body);
  const visitorToken = await generateVisitorToken(user);
  
  // Redirect to GitBook
  const docsUrl = "https://docs.company.com/?jwt_token=" + visitorToken;
  res.redirect(docsUrl);
});

Slack Integration Features

<!-- Knowledge base search in Slack -->
/gitbook How to resolve authentication errors?

<!-- Save thread content to GitBook -->
@GitBook save

<!-- Public Q&A -->
@GitBook Tell me about API authentication methods