Migrate from Notion to Outline
Notes / wiki / docs · full migration guide
Notion → Outline is the cleanest of the wiki migrations because Outline ships a first-party Notion importer that accepts Notion's own Markdown + CSV export bundle. The wiki, handbook, and docs surface ports nearly losslessly; the part that hurts is Notion's databases, which Outline does not have an equivalent for and which collapse to plain tables on import. Plan this migration in two phases: a flag-day for the wiki content (a few hours of click-through), and a follow-on cleanup week to rebuild any database-driven workflows as plain pages or external tools.
Prerequisites
- Notion workspace owner permissions (only the workspace owner can run the full export).
- A self-hosted Outline instance — see /notion/ for the 15-minute docker-compose recipe and ~$5/mo VPS sizing.
- S3-compatible blob storage configured for Outline (MinIO works on the same VPS); the importer attaches images from the export bundle as Outline attachments.
- An hour of admin time on a quiet day for the actual export → import cutover.
- A list of Notion databases ahead of time so you know which pages will need rebuilding (export from Notion → Settings → Members shows database count).
Step 1 — Export from Notion
-
Open the Notion workspace export dialog
In Notion's left sidebar click your workspace name → Settings → Workspace → Settings. Scroll to the Export content section and click Export all workspace content. The dialog gives three format choices.
-
Choose Markdown & CSV with subpages and files included
Pick Export format: Markdown & CSV (not HTML — Outline's importer is tuned for Markdown). Toggle Include content: Everything. Toggle Include subpages: on. Toggle Create folders for subpages: on (this preserves the page hierarchy as a directory tree). Click Export.
-
Wait for the email and download the .zip
For workspaces over ~500 pages Notion processes the export in the background and emails a download link when ready (5-30 minutes typically). The .zip can be 100MB+ for handbook-sized workspaces. Download it to the same machine you'll run the Outline import from.
-
Inspect the .zip before importing
Unzip locally and skim the directory tree. Each top-level Notion page becomes a folder with an `Untitled.md` or named .md file inside; databases become CSV files plus a folder of one-page-per-row .md files. Note any all-database pages (no .md, only CSV) — these are the ones that won't import cleanly.
Step 2 — Import into Outline
-
Open Outline's Notion import
In Outline, click your avatar → Settings → Import. The Notion option uses the dedicated importer (not the generic Markdown one — pick the Notion tile).
-
Upload the original .zip (do not unzip first)
Drag the Notion export .zip directly into the importer dialog. Outline reads the structure from the .zip itself; uploading an unzipped folder loses the hierarchy detection.
-
Wait for the importer to finish
Outline imports asynchronously and emails you when done. For a 100MB workspace expect 10-30 minutes. The import surfaces a per-document summary if anything fails.
-
Verify hierarchy and re-share collections
Pages land in a single import collection by default. Move top-level Notion sections into their own Outline collections (Documentation, Engineering, etc.) so permissions can be set per collection. Re-share the collection with your team — share state does not transfer from Notion.
Field / concept mapping
| Notion | Outline | Notes |
|---|---|---|
| Notion page | Outline document | Hierarchy, headings, paragraphs, lists, code blocks, callouts, and toggles all transfer. Toggles render as a `Toggle` block. |
| Notion sub-page | Nested document | Sub-pages become nested documents under the parent — directory structure preserves. |
| Notion database | Markdown table or one-document-per-row | Importer collapses databases to tables in the parent doc. If the database has many rows it becomes a folder of per-row docs. Re-link manually if you want clickable references. |
| Notion formula / rollup | Plain text value at export time | Notion bakes the computed value into the Markdown — formulas do not persist. If you need live calculation, use an external tool (Outline does not compute on tables). |
| Notion linked database view | Empty placeholder | Linked database views drop on export. Recreate as Outline collections with manual links. |
| Notion image / file upload | Outline attachment | Images and files in the export attach to the destination document; Outline rehosts them to your configured S3 bucket. |
| Notion comment | Not migrated | Notion's comment threads do not export. Document the loss to the team before cutover. |
| Notion page permissions | Outline collection permissions | Re-set permissions per collection on the Outline side — there is no auto-translation. |
Downtime estimate
Two to three hours of write-freeze on the Notion side during the export → import → verify window for a typical 500-page workspace. Reads can stay on Notion until the Outline pages are verified. Database-heavy workspaces add a follow-on week of background cleanup (rebuilding views), but no further downtime.
Common gotchas
- Notion's export silently truncates very large pages (>2MB of Markdown). Check the largest 5 pages by hand after import.
- Outline's importer requires the .zip — uploading the unzipped folder loses the hierarchy and you get a flat list of documents.
- Database pages in Notion that depend on a roll-up are essentially dead on arrival — Outline has no relations. Plan to rebuild as plain wiki pages or move to a real database (Postgres, NocoDB).
- Image embeds via `paste image` work; image embeds via Notion's `external image` block do not — they import as broken links pointing at notion.so URLs.
- Outline's collection-level permissions are coarser than Notion's per-page permissions. Audit any Notion pages that were shared more or less broadly than their parent.
Rollback plan
Notion does not delete content on export, so the original workspace is intact. If Outline doesn't fit, point the team back to Notion and you've lost only the time spent. Keep the original export .zip for at least 30 days — it's the canonical migration artifact and lets you re-import to a different tool (AppFlowy, AFFiNE) without re-exporting.
Looking for setup time, monthly cost, and other alternatives? See Self-host Notion.