Connecting GitBook as a knowledge source

If your team's documentation lives in GitBook, connect it to Ochre and your help center inherits everything. Edits flow through. The AI agent reads them. Your customers see the result.

How it works

You generate a personal access token in GitBook, paste it into Ochre, and pick the spaces you want to sync. Ochre walks the space on a schedule, fetches each page in markdown, and creates an article. The walker is bounded and retries once on rate limits or 5xx errors. It caps at 500 pages and 4 levels of depth per run.

GitBook's API is more structured than Notion's, so the sync is generally cleaner. Page hierarchies map directly to Ochre's category and article structure.

Setting it up

Connect during onboarding or later from Knowledge → Sources → Connect source.

1. Generate a personal access token

In GitBook: top-right avatar → Settings → Developer settings → Personal access tokens → Generate new token.

Give it a name like "Ochre Sync". GitBook will show the token once. Copy it. You cannot see it again later.

The token has the same access as the user who created it. If you want to limit which spaces Ochre can read, create the token from a user account that only has access to the spaces you want synced. Or use a service account if your GitBook plan supports them.

2. Paste the token into Ochre

Knowledge → Sources → Connect source → GitBook. Paste the token. Save.

Ochre validates the token by hitting /v1/user. If it works, you will see the accessible organizations and spaces.

3. Pick spaces to sync

Select one or more spaces. For each, choose which Ochre category to land the articles in. You can split one space across multiple Ochre categories using GitBook's group structure, or land everything in one category.

4. First sync

Click Sync now. The first run is the slowest. For a 200-page space, expect about a minute.

After it completes, articles appear in Ochre as drafts. Review them and bulk-publish, or move them through your normal review process.

Schedules

Subsequent syncs run roughly every 15 minutes. They only fetch pages that changed since the last run, so they are fast. You can also click Sync now for instant propagation.

If you publish a major rewrite in GitBook and want it live immediately, Sync now is the right move.

What gets synced

• Page title → article title.
• Page body (fetched as markdown via /spaces/{id}/content/page/{id}?format=markdown) → article body, with formatting preserved.
• Headings, lists, code blocks (with language), callouts, hint blocks, tables, embedded images, and links.
• Internal links between synced pages get rewritten to Ochre slugs.
• Group structure (folders/sections) maps to Ochre sub-categories.

What does not sync:

• Page customizations like custom layouts.
• Comments and review threads.
• Drafts (only published GitBook content syncs).
• Variant content (we sync the default variant).

Status mapping

GitBook published pages sync as Ochre drafts by default. Flip the source's "publish on sync" toggle if you want them published immediately.

If you unpublish or delete a GitBook page, the corresponding Ochre article moves to archived on the next sync. Restoring it in GitBook brings it back as draft.

Multiple spaces

You can sync multiple GitBook spaces to one Ochre help center. Each gets its own configuration: source category, status mapping, schedule. Useful if you have separate spaces for, say, end-user docs and admin docs and want them both in the help center under different categories.

Editing synced articles

Do not edit synced articles directly in Ochre. The next sync will overwrite. If you need to fork an article into Ochre-only territory, disable sync on that specific article from its sidebar.

Caps

Like Notion, the walker stops at 500 pages and 4 levels of depth per sync run. If you have a larger space:

• Sync only the subtree you actually want as a customer-facing help center.
• Spread across multiple connections.
• Contact support if you genuinely have more articles than that.

The depth cap is rarely an issue in GitBook because the structure is usually flatter than Notion.

Token rotation

If you rotate the GitBook token, paste the new token into Ochre's settings page and save. The old token stops working. Sync resumes within a minute.

If a token expires or is revoked while Ochre is using it, the sync fails. You will see an error banner on the Sources page. Generate a new token, paste, save.

Disconnecting

Knowledge → Sources → click the GitBook source → Disconnect. The token is removed from Ochre. Synced articles stay but stop updating. You can convert them to native Ochre articles or archive them.

In GitBook, you can also revoke the token from Developer settings → Personal access tokens → Revoke.

GitBook plans

Public spaces, internal spaces, and password-protected spaces all sync via the API. The plan you are on does not affect Ochre's sync as long as the user owning the token has read access.

Side-by-side with Notion (and other sources)

You can run GitBook, Notion, URL crawl, and Markdown upload sources at the same time. Articles from each land wherever you tell them to. Use Categories and sub-categories to keep things organized.

Confluence is not supported today. The practical workaround is to mirror the relevant Confluence pages into a GitBook space or a Notion subtree, then connect that.

Related

• Authoring articles for native Ochre editing.
• Connecting Notion for the Notion equivalent.
• Article visibility and gating for status mapping details.