Skip to content

Documentation Setup

This documentation syncs to GitBook and Notion automatically.

Architecture

Doc push (Documentation/**)  → GitBook syncs automatically
                             → Notion syncs via GitHub Action

Docs are kept accurate manually: docs-sync commits alongside code changes, plus a weekly health-pass that sweeps CLAUDE.md and Documentation/ for drift.

GitBook Setup

GitBook syncs directly from this repo and keeps docs private.

  1. Go to gitbook.com → Create account/space
  2. Go to Space Settings → Git Sync
  3. Connect GitHub → Select this repository → Branch: main
  4. GitBook detects .gitbook.yaml and syncs /Documentation
  5. Invite team members to your GitBook organization

Notion Setup

Syncs documentation to a Notion page in your workspace.

1. Create Integration

  • Go to notion.so/my-integrations
  • Click "New integration"
  • Name: "Project Eternal Docs"
  • Copy the "Internal Integration Secret" (starts with ntn_)

2. Create Parent Page

  • Create a page in Notion called "Technical Documentation"
  • Copy link → Extract the 32-character page ID from URL

3. Share with Integration

  • On the parent page, click "Share"
  • Invite your integration by name

4. Add GitHub Secrets

Settings → Secrets and variables → Actions

NOTION_TOKEN: secret_...
NOTION_PARENT_PAGE_ID: abc123...

GitHub Secrets Reference

Secret Required For Description
NOTION_TOKEN Notion sync Integration token
NOTION_PARENT_PAGE_ID Notion sync Parent page ID

Troubleshooting

GitBook not syncing

  • Verify .gitbook.yaml exists in repo root
  • Check Git Sync is enabled in GitBook space settings

Notion sync failing

  • Verify integration has access to the parent page
  • Check NOTION_TOKEN is correct (starts with ntn_)
  • Ensure NOTION_PARENT_PAGE_ID is 32-char ID, not full URL