How to migrate from Notion to Outline

Move a Notion workspace to self-hosted Outline: what the Notion importer brings across, where each database goes, how access is rebuilt and how to cut over.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • Outline imports Notion through the Notion API: top-level pages become collections, nested pages become documents, and images and files are copied into Outline.
  • Notion databases arrive as documents without their properties, views, formulas or relations; tables of records a team still uses move to NocoDB from the CSV export.
  • Comments, page permissions and guests do not come across: access is rebuilt as Outline collections shared with groups, behind your identity provider.
  • Notion is set to read-only before the final import, and links that still lead to Notion are found and repointed before the subscription ends.
On this page (10)

Moving from Notion to Outline is an import for the pages and a decision for everything else. Outline reads your workspace through the Notion API and rebuilds the page tree as collections and documents, with their images and files. What it does not carry is the database layer, the comments and the sharing. So the work is sorting databases into pages and records, rebuilding access around your directory, and switching over without leaving links that still lead to Notion. This guide covers the order we do it in when we migrate a team.

Why teams move from Notion to Outline

Three reasons come up again and again.

  • Where the wiki lives. A company wiki ends up holding runbooks, incident notes, board papers and drafts: the record of how the organisation works. Self-hosted Outline keeps them in a PostgreSQL database and a storage bucket on your premises or in a region you choose.
  • Access that follows your directory. Outline keeps no passwords of its own. Everyone signs in through your identity provider, and collections are shared with groups, so a leaver disabled in the directory loses the wiki with everything else.
  • A wiki that stays a wiki. Outline does one job: documents in collections, edited together in real time, with fast search. Teams that used Notion mainly for documentation often find that is the part they needed.

What you give up is the rest of the workspace. Databases with views, relations and formulas have no place in a wiki, and they need another home or a decision to retire them. You also give up the fact that someone else runs the platform, which is the part Pilae takes on.

Step 1: map the workspace

Notion often holds a wiki, a few trackers and a small CRM in the same sidebar. List what is there before anything moves.

  1. Teamspaces and their top-level pages, with an owner for each. Each top-level page becomes an Outline collection on import, so this list is also the first draft of your collection structure.
  2. Every database, and what it is used for. Put each one in one of two groups. A list of pages keeps its value in the page bodies: meeting notes, specs, a handbook. A table of records keeps its value in the properties, views and formulas: a tracker, a CRM, an inventory. The second group decides whether NocoDB joins the move.
  3. Guests and outside sharing. People outside the organisation with access to pages, and pages published to the web. Each needs a decision, covered in step 5.
  4. Private pages worth keeping. Neither the workspace export nor the importer reads another member’s private pages. Ask people to move what they want to keep into a teamspace.
  5. The pages people open most, and on them any synced blocks, embeds and linked database views. These are the blocks most likely to change shape.
  6. Links into Notion from other tools: bookmarks, READMEs, tickets, chat channel topics. They all need a new target at cutover.

Agree now what is out of scope. Teamspaces nobody has opened in a year are usually archived from the export rather than imported.

Step 2: take the Notion exports

The import does not use an export file: Outline reads the workspace through the API in step 3. Take the exports anyway. They are the archive of the workspace as it stood, and they hold the database contents as CSV.

  1. A workspace owner opens Settings, then General under Workspace, and chooses Export all workspace content. This works on desktop or the web, not on mobile.
  2. Export twice. Once as Markdown & CSV, which writes databases as CSV files next to the pages. Once as HTML, with comments included: the HTML export carries page and block comments, resolved or not.
  3. Download promptly. Notion emails a download link when the export is ready. On a large workspace that can take up to 30 hours, and the link expires after seven days.

Two limits apply. A database exports one view, the current or the default one, not all of them. And on Enterprise, a workspace owner can switch exports off under Settings, Security, and a teamspace owner can do the same for one teamspace; if yours has done that, the owner turns it back on for the export. See Notion’s export guide for the details per format.

Step 3: connect Outline to Notion and import into staging

Outline’s Notion importer is part of every edition of Outline, the self-hosted one included. It needs a Notion connection registered for your Outline address.

  1. Register the connection. In Notion’s developer portal, create an OAuth integration that can be installed in your workspace, and set its redirect address to your Outline address followed by /api/notion.callback. Each Outline instance that runs an import, staging and production, needs its redirect address registered.
  2. Configure Outline. The integration’s client ID and secret go into Outline’s environment as NOTION_CLIENT_ID and NOTION_CLIENT_SECRET, and Outline is restarted. Outline documents the setup in its Notion import guide.
  3. Authorise the pages. An Outline admin opens Settings, Import, then Notion, and is sent to Notion’s consent screen. Notion’s page picker lists only pages the person has full access to, and access to a page includes the pages beneath it, so a workspace owner should authorise, and select the top-level pages of every teamspace in scope. On Enterprise, the workspace owner may first need to allow the connection.
  4. Choose the default permission. Each top-level page becomes a new collection with the default permission chosen here; leave it empty and the collections start private until step 5.
  5. Let it run. The import runs in the background, and its status shows under Settings, Import until it reads Completed.

Run this first import into a staging copy of Outline. Owners open their sections and check the structure, the images and the links. Nobody edits in staging: the final import in step 6 replaces it. Run the import from a named admin account rather than a person’s own, because the imported documents are created under the account that ran it.

What comes across

What the Outline Notion importer brings across

Imported

  • Pages and their nesting: top-level pages become collections, child pages nested documents
  • Headings, lists, to-dos, toggles, quotes, code, tables and equations
  • Callouts, as Outline notices
  • Images, uploaded videos, files and PDFs, copied into Outline’s storage
  • Page mentions and links to pages, as Outline mentions
  • Created and last-edited dates

Not imported

  • Database properties, views, formulas, relations and rollups
  • Linked database views, and databases that combine several data sources
  • Comments and page history
  • Page permissions, sharing and guests

A few blocks change shape on the way. A synced block is copied into each page that showed it and stops being synced, so the page that owns the content needs to be agreed. Column layouts are flattened into one column. Bookmarks become plain links and embeds keep their address. A database becomes a document of its own with one child document per row: the row’s page content comes across, its properties do not. A database placed inside a page becomes a link to that document.

Step 4: give every database a home

Outline is a wiki, not a database tool. Documents can hold tables, but nothing in Outline filters, relates or computes records. Take the database list from step 1 and give each one of three outcomes.

Three homes for a Notion database

Documents

A list of pages, such as meeting notes or specs. The importer already brings each row across as a document. A property that still matters, an owner or a decision date, goes into the document’s title or first line.

A table in a document

A short reference list nobody filters: offices, an on-call rota, a glossary. Rebuild it as a table inside the document it belongs to, from the CSV in the export.

NocoDB

A table of records people filter, sort and link: a tracker, a CRM, an inventory. Its CSV from the export becomes a NocoDB table, with views, links and formulas rebuilt.

NocoDB creates a table from a CSV file and imports every column as single-line text, so the field types are set after the import: dates, numbers, single and multiple selects. Relations between databases become NocoDB links, rebuilt once both tables exist, and formulas are rewritten in NocoDB’s formula language. Where a team only needs a shared table beside its files, Nextcloud Tables is the other option. And some databases turn out to be unused: keep their CSV in the archive and stop there.

Step 5: rebuild access with sign-in, collections and groups

Notion’s sharing does not come across, and copying it would carry over years of individual exceptions. Rebuild access from the teams instead.

Notion Outline
Workspace Workspace
Teamspace One or more collections
Top-level page A collection, with the page’s content as its overview
Nested page Nested document
Database A document with one child document per row
Teamspace members A group with access to the collection
Page shared with a person Document shared with a user or a group
Guest No guest role on the self-hosted community edition
Comments Start fresh in Outline; the HTML export keeps the old ones
  1. Connect sign-in first. Outline signs people in over OpenID Connect, through Keycloak or Microsoft Entra ID, and creates each account at first sign-in with the name from the directory. With Pilae, single sign-on comes from the Business plan, and our identity service sets up the connection.
  2. Create groups under Settings, Groups, named after the teams in your directory.
  3. Set each collection’s access. A collection has a default access for the whole workspace, view or edit. With no default access it is private, and only the people and groups added to it see it. Groups get read or edit permission on the collections they need.
  4. Share exceptions at document level. A single document can be shared with specific people or groups without opening the whole collection.
  5. Decide on guests. Outline’s guest role is not available in the self-hosted community edition; Outline’s paid self-hosted plans add it. People outside the organisation who had guest access in Notion need an account in your directory, or the pages they need sent another way. Outline as Pilae runs it answers on your private network, so a page that must stay public on the web needs a decision of its own.

The importer turns page mentions and links to pages into Outline mentions, which lead somewhere only when the target page was imported too. Ordinary hyperlinks that point at a Notion address stay as they were. After the final import, search Outline for notion.so, notion.com and notion.site and repoint each result. Links into Notion from other tools, the list from step 1, are repointed at cutover: nothing redirects them.

The cutover, in order

  1. Freeze: Set each teamspace’s default access to Can view, and check pages shared with people individually, because Notion grants the most permissive access a person has.
  2. Import: Run the final import into production, then remove the staging copy.
  3. Check: Owners open their collections against Notion, and the link search runs.
  4. Repoint: Bookmarks, READMEs, tickets and chat topics move to Outline addresses.
  5. Close: Notion stays read-only for an agreed period; then a last export goes to the archive, the connection is removed and the subscription ends.

The connection is removed in Notion under Settings, Connections. Like any access granted for a migration, it should not outlive the migration.

Running Outline in production

A wiki that the whole organisation reads needs more than one container.

  • PostgreSQL for documents, revisions, collections and permissions.
  • Redis for background jobs and for real-time editing between people on the same page.
  • S3-compatible storage for images and attachments, kept apart from the database and backed up with it.
  • An SMTP relay for sign-in links, invitations and notifications of mentions and comments.
  • Updates with a way back. Outline releases frequently, and each upgrade wants a test against a copy of your data.

Pilae operates Outline this way, on a dedicated machine on your premises or in Pilae Cloud, answering on your private network. Backups are daily, encrypted and stored at a second site in the same jurisdiction, and on Enterprise a restore test runs every month and is recorded in the console. Outline is source-available under the Business Source License 1.1; where the wiki has to be open source, BookStack is published under the MIT licence and Pilae runs it too. For the wider comparison, see our page on Notion alternatives.

Let Pilae run the move

Pilae runs Notion to Outline migrations at a fixed price: the workspace map, the exports, the import into staging, a home for every database, sign-in and collections, and the cutover. Then we operate Outline for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your workspace and we will scope it.

Questions

Does Outline need a Notion export file to import a workspace?

No. The Outline Notion importer reads the workspace through the Notion API once an Outline admin authorises it on Notion's consent screen. The workspace export is still worth taking: it is the archive of the workspace as it stood, the HTML export keeps the comments, and the Markdown and CSV export holds the database contents.

What happens to Notion databases in Outline?

Each database becomes a document with one child document per row. The page content of each row comes across; its properties, views, formulas, relations and rollups do not. Databases used as lists of pages fit that well. Databases used as tables of records move to NocoDB from the CSV export, or become a table inside a document.

Do comments and page permissions come across?

No. The importer brings page content, not comments, sharing or page history. Comments survive in the HTML export as an archive, and access is rebuilt in Outline as collections shared with groups from your directory, which is usually simpler than what Notion held.

Is Outline open source?

No. Outline is source-available under the Business Source License 1.1. You can read and run the code and use it in production, but not to provide a document service to others. Each release converts to Apache-2.0 on the change date in its licence. Pilae runs a dedicated instance for one organisation and sets out the licence position in the proposal. Where the wiki has to be open source, BookStack is published under the MIT licence.

How long does a Notion to Outline migration take?

The import runs in the background, so the page count matters less than the decisions: how many databases need a home outside the wiki, and how many teams have to agree their collections. The workspace map settles both. Pilae quotes the move as one fixed price once that map is done.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.