Connecting Notion as a knowledge source

If your team writes docs in Notion, you do not have to migrate to use Ochre. Connect your Notion workspace and Ochre will pull articles in on a schedule. Edits in Notion show up in Ochre. The AI agent uses them. Your help center serves them.

How it works

You generate an integration token in Notion, paste it into Ochre, and pick the pages or databases you want to sync. Ochre walks the tree on a schedule, fetches each page, renders the blocks to markdown, and turns it into an article.

Bounded concurrency keeps the walk gentle on Notion's API. Retries happen once on rate limits or transient server errors. Each sync stops at 500 pages and 4 levels of depth, which covers almost every team's docs.

Setting it up

You can connect during onboarding or any time later from Knowledge → Sources → Connect source.

1. Create a Notion integration

In Notion: Settings → Connections → Develop or manage integrations → New integration.

• Name it something like "Ochre Sync".
• Associate it with your workspace.
• Capabilities: read content. You do not need write access.
• Save and copy the integration token (it starts with secret_).

2. Share pages with the integration

In Notion, open the top-level page or database you want to sync. Click Share → invite the integration by name.

Sharing is recursive. The integration sees the shared page and every page under it. You do not need to share each child page individually.

If you want only part of your Notion workspace synced, share just that subtree.

3. Paste the token in Ochre

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

Ochre validates the token by listing accessible pages. If it works, you will see a list of top-level pages and databases.

4. Pick what to sync

Select the pages and databases you want as articles. You can pick all, or hand-pick a subset.

For each selection, Ochre asks which Ochre category to put the resulting articles in. You can split one Notion tree across multiple Ochre categories or land everything in one. We recommend mirroring your Notion structure if it already maps to logical product areas.

5. Run the first sync

Click Sync now. The first run is the slowest because Ochre is fetching every page. For a 100-page workspace, expect 30 to 90 seconds.

When it is done, your articles appear in the Knowledge index as drafts. Review and publish.

Schedules

After the first run, Ochre syncs on a schedule (about every 15 minutes for active sources). You can also click Sync now any time you want immediate propagation.

A sync only fetches pages that changed since the last run, so subsequent syncs are fast.

What gets synced

• Page title becomes article title.
• Page body becomes article body. Markdown-equivalent formatting.
• Headings, lists, code blocks, callouts, quotes, dividers, embedded images, and tables.
• Internal Notion links between synced pages get rewritten to Ochre slugs.
• Page properties (tags, status, etc.) are not currently synced as article metadata.

What does not sync:

• Synced blocks (we read them as static at sync time).
• Database views (we sync the underlying pages, not the view configuration).
• Comments and discussions.
• Page covers (use Ochre's cover image field manually).

Status mapping

By default, all Notion pages sync as draft articles in Ochre so you can review before publishing. You can change this default in the source's settings to "publish on sync" if you trust your Notion docs to be production-ready.

If you delete or unshare a Notion page, the corresponding Ochre article moves to archived on the next sync. It is not deleted; you can restore by re-sharing in Notion.

Editing synced articles

You should not edit synced articles directly in Ochre. The next sync will overwrite your edits with the Notion version.

If you need a one-off Ochre-only tweak, the right move is to disconnect that specific page from sync (toggle in the article sidebar) and edit freely in Ochre. The article keeps the content but stops getting updates from Notion.

Page caps

The walker stops at 500 pages and 4 levels of depth per sync run. If your Notion workspace is bigger:

• Share only a subtree to stay under the cap.
• Use multiple Notion connections, each pointing at a different subtree.
• Contact support if you genuinely have more than 500 unique help articles. We can raise the cap.

The depth cap of 4 means: top-level page → child → grandchild → great-grandchild. Deeper than that, the walker stops descending. This is rarely a problem in practice because docs usually live within 2 to 3 levels.

Disconnecting

Knowledge → Sources → click the Notion source → Disconnect. The token is invalidated. Synced articles stay in Ochre but stop receiving updates. You can convert them to native Ochre articles or archive them.

If you also revoke the integration in Notion (Settings → Connections), the token cannot be reused.

Multiple Notion workspaces

You can connect more than one Notion workspace if you have docs spread across them. Each gets its own token and its own page selection.

Confluence

Confluence is not a supported source today. If you have docs in Confluence, the practical workaround is to mirror the relevant pages into a Notion subtree and connect that.

Related

• Authoring articles for native Ochre editing.
• Connecting GitBook for GitBook teams.
• Categories and sub-categories for where synced articles land.