gitbook-notion

name	gitbook-notion
description	Integration with hosted documentation platforms GitBook and Notion. Manage spaces, synchronize content with Git, export/import between formats, configure webhooks, and retrieve analytics.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-011
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:docs-as-code","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]}

GitBook/Notion Integration Skill

Integration with hosted documentation platforms.

Capabilities

• GitBook space management
• Notion database integration for docs
• Content synchronization with Git
• Export/import between formats
• Embed and block management
• API documentation hosting
• Analytics retrieval
• Webhook configuration

Usage

Invoke this skill when you need to:

• Sync documentation to GitBook or Notion
• Manage hosted documentation spaces
• Export content for migration
• Configure publishing workflows
• Retrieve documentation analytics

Inputs

Parameter	Type	Required	Description
platform	string	Yes	gitbook, notion
action	string	Yes	sync, export, import, analytics
spaceId	string	No	GitBook space or Notion database ID
sourcePath	string	No	Path to source content
outputPath	string	No	Path for exported content

Input Example

{
  "platform": "gitbook",
  "action": "sync",
  "spaceId": "abc123",
  "sourcePath": "./docs"
}

GitBook Integration

GitBook Configuration

# .gitbook.yaml
root: ./docs

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

redirects:
  /old-page: /new-page
  /api/v1: /api/v2

SUMMARY.md Structure

# Summary

## Getting Started

* [Introduction](README.md)
* [Installation](getting-started/installation.md)
* [Quick Start](getting-started/quickstart.md)

## User Guide

* [Configuration](user-guide/configuration.md)
* [Features](user-guide/features.md)
  * [Authentication](user-guide/features/auth.md)
  * [Data Management](user-guide/features/data.md)

## API Reference

* [Overview](api/README.md)
* [Authentication](api/authentication.md)
* [Endpoints](api/endpoints/README.md)
  * [Users](api/endpoints/users.md)
  * [Projects](api/endpoints/projects.md)

## Resources

* [FAQ](resources/faq.md)
* [Changelog](CHANGELOG.md)

GitBook API Integration

const GitBook = require('gitbook-api');

class GitBookManager {
  constructor(token) {
    this.client = new GitBook({ token });
  }

  // List spaces
  async listSpaces(organizationId) {
    return await this.client.spaces.list({
      organizationId
    });
  }

  // Get space content
  async getContent(spaceId) {
    const pages = await this.client.spaces.listPages(spaceId);
    return pages;
  }

  // Update page
  async updatePage(spaceId, pageId, content) {
    return await this.client.pages.update(spaceId, pageId, {
      document: {
        markdown: content
      }
    });
  }

  // Create page
  async createPage(spaceId, title, content, parentId = null) {
      ...(spaceId, {
      title,
      : parentId,
      : {
        : content
      }
    });
  }

  
   () {
      ...(spaceId, {
      : ,
      : repoUrl,
      branch
    });
  }

  
   () {
      ...(spaceId, {
      period
    });
  }
}

GitBook CI/CD Sync

# .github/workflows/gitbook-sync.yml
name: Sync to GitBook

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync to GitBook
        uses: gitbook/github-action-sync@v1
        with:
          token: ${{ secrets.GITBOOK_TOKEN }}
          space: ${{ secrets.GITBOOK_SPACE_ID }}

Notion Integration

Notion Database Schema

const notionSchema = {
  database_id: 'abc123',
  properties: {
    'Title': {
      type: 'title',
      title: {}
    },
    'Slug': {
      type: 'rich_text',
      rich_text: {}
    },
    'Category': {
      type: 'select',
      select: {
        options: [
          { name: 'Guide', color: 'blue' },
          { name: 'Reference', color: 'green' },
          { name: 'Tutorial', color: 'purple' }
        ]
      }
    },
    'Status': {
      type: 'status',
      status: {
        options: [
          { name: 'Draft', color: 'gray' },
          { name: 'Review', color: 'yellow' },
          { name: 'Published', color: 'green' }
        ]
      }
    },
    'Last Updated': {
      type: 'last_edited_time',
      last_edited_time: {}
    },
    'Author': {
      type: ,
      : {}
    },
    : {
      : ,
      : {
        : []
      }
    }
  }
};

Notion API Integration

const { Client } = require('@notionhq/client');

class NotionDocsManager {
  constructor(token) {
    this.notion = new Client({ auth: token });
  }

  // Query documentation pages
  async queryDocs(databaseId, filter = {}) {
    const response = await this.notion.databases.query({
      database_id: databaseId,
      filter: {
        and: [
          { property: 'Status', status: { equals: 'Published' } },
          ...Object.entries(filter).map(([prop, value]) => ({
            property: prop,
            [typeof value === 'string' ? 'rich_text' : 'select']: {
              equals: value
            }
          }))
        ]
      },
      sorts: [
        { property: 'Last Updated', direction: 'descending' }
      ]
    });

    return response.results;
  }

  
   () {
     blocks =  ....({
      : pageId
    });

     .(blocks.);
  }

  
   () {
     blocks = .(content);

      ...({
      : { : databaseId },
      : {
        : {
          : [{ : { : title } }]
        },
        : {
          : [{ : { : .(title) } }]
        },
        : {
          : { :  }
        },
        ...properties
      },
      : blocks
    });
  }

  
   () {
    
     existing =  ....({
      : pageId
    });

     ( block  existing.) {
       ...({ : block. });
    }

    
     blocks = .(content);
     ....({
      : pageId,
      : blocks
    });
  }

  
  () {
     markdown = ;

     ( block  blocks) {
       (block.) {
         :
          markdown += .(block..) + ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + block.. + ;
          markdown += .(block..);
          markdown += ;
          ;
         :
          markdown +=  + .(block..) + ;
          ;
         :
          markdown +=  + block..?. + ;
          markdown += .(block..) + ;
          ;
      }
    }

     markdown;
  }

  
  () {
     blocks = [];
     lines = markdown.();

     i = ;
     (i < lines.) {
       line = lines[i];

       (line.()) {
        blocks.({
          : ,
          : { : [{ : { : line.() } }] }
        });
      }   (line.()) {
        blocks.({
          : ,
          : { : [{ : { : line.() } }] }
        });
      }   (line.()) {
        blocks.({
          : ,
          : { : [{ : { : line.() } }] }
        });
      }   (line.()) {
         lang = line.();
         code = ;
        i++;
         (i < lines. && !lines[i].()) {
          code += lines[i] + ;
          i++;
        }
        blocks.({
          : ,
          : {
            : lang || ,
            : [{ : { : code.() } }]
          }
        });
      }   (line.()) {
        blocks.({
          : ,
          : {
            : [{ : { : line.() } }]
          }
        });
      }   (.(line)) {
        blocks.({
          : ,
          : {
            : [{ : { : line.(, ) } }]
          }
        });
      }   (line.()) {
        blocks.({
          : ,
          : { : [{ : { : line } }] }
        });
      }

      i++;
    }

     blocks;
  }
}

Notion Export Script

async function exportNotionToMarkdown(databaseId, outputDir) {
  const manager = new NotionDocsManager(process.env.NOTION_TOKEN);
  const pages = await manager.queryDocs(databaseId);

  for (const page of pages) {
    const title = page.properties.Title.title[0].plain_text;
    const slug = page.properties.Slug.rich_text[0]?.plain_text || slugify(title);
    const category = page.properties.Category.select?.name || 'uncategorized';

    const content = await manager.getPageContent(page.id);

    const frontMatter = `---
title: ${title}
notion_id: ${page.id}
last_updated: ${page.last_edited_time}
---

`;

    const filePath = path.join(outputDir, category, `${slug}.md`);
    await fs.mkdir(path.dirname(filePath), { :  });
     fs.(filePath, frontMatter + content);
  }
}

Analytics

GitBook Analytics

async function getGitBookAnalytics(spaceId) {
  const analytics = await gitbook.getAnalytics(spaceId, '30d');

  return {
    pageViews: analytics.pageViews,
    uniqueVisitors: analytics.uniqueVisitors,
    topPages: analytics.topPages.map(p => ({
      path: p.path,
      views: p.views
    })),
    searchQueries: analytics.searches.map(s => ({
      query: s.query,
      count: s.count,
      noResults: s.noResults
    }))
  };
}

Workflow

1. Configure - Set up API credentials
2. Connect - Link Git repository or Notion database
3. Sync - Push/pull content changes
4. Publish - Deploy to hosted platform
5. Monitor - Track analytics and usage

Dependencies

{
  "devDependencies": {
    "@notionhq/client": "^2.2.0",
    "gitbook-api": "^0.8.0",
    "gray-matter": "^4.0.0"
  }
}

CLI Commands

# Export from Notion
node scripts/notion-export.js --database abc123 --output ./docs

# Sync to GitBook
gitbook sync ./docs --space abc123

# Import to Notion
node scripts/notion-import.js --input ./docs --database abc123

Best Practices Applied

• Keep source of truth in Git
• Sync on merge to main
• Use consistent slug patterns
• Track page analytics
• Set up webhooks for automation
• Handle rate limits gracefully

References

• GitBook API: https://developer.gitbook.com/
• Notion API: https://developers.notion.com/
• GitBook Sync: https://docs.gitbook.com/integrations/git-sync

Target Processes

• knowledge-base-setup.js
• docs-versioning.js
• content-strategy.js