How to Migrate from Notion to Outline

Outline is the most mature open source Notion alternative for team wikis. It has a Notion-like editor, real-time collaboration, collections, and a comprehensive API. Here's how to migrate your Notion workspace.

What Transfers

Content	Status
✅ Pages and sub-pages	Native Notion import
✅ Text formatting	Full support
✅ Images	Imported with content
✅ Tables	Supported
✅ Code blocks	Supported
✅ Lists and toggles	Supported
⚠️ Databases	Import as tables (static)
❌ Database views/filters	Not supported
❌ Formulas and relations	Not supported
❌ Comments	Not preserved
❌ Page analytics	Not preserved

Step 1: Export from Notion

1. Go to Settings & Members → Settings
2. Click Export all workspace content
3. Choose Markdown & CSV format
4. Include sub-pages → Export
5. Download the ZIP file

Step 2: Deploy Outline

# Docker Compose
git clone https://github.com/outline/outline.git
cd outline/docker
cp .env.sample .env

# Edit .env — configure:
# - DATABASE_URL (PostgreSQL)
# - REDIS_URL
# - SECRET_KEY (generate with openssl rand -hex 32)
# - URL (your domain)
# - Authentication provider (Google, Slack, OIDC, SAML)

docker compose up -d

Requirements: PostgreSQL, Redis, S3-compatible storage (MinIO works), authentication provider (OIDC, Google, Slack, or SAML).

Step 3: Import into Outline

Outline has a native Notion import:

1. Open Outline → Settings → Import
2. Select Notion as the source
3. Upload your exported ZIP file
4. Outline maps Notion pages → Documents and sub-pages → Nested documents
5. Import completes in minutes

Alternative: Markdown import

1. Settings → Import → Markdown
2. Upload individual .md files or folders

Step 4: Organize Collections

Notion's workspace structure → Outline:

Notion	Outline
Team spaces	Collections
Top-level pages	Documents in collections
Sub-pages	Nested documents
Favorites	Stars
Shared pages	Public document sharing

Create collections to mirror your Notion team spaces, then move imported documents into the appropriate collections.

Step 5: Set Up Authentication

Outline requires an external auth provider:

Google OAuth (easiest):

1. Create OAuth credentials at console.cloud.google.com
2. Set authorized redirect: https://your-outline.com/auth/google.callback
3. Add GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to .env

OIDC (Keycloak, Authentik, etc.):

OIDC_CLIENT_ID=outline
OIDC_CLIENT_SECRET=your-secret
OIDC_AUTH_URI=https://auth.yourdomain.com/authorize
OIDC_TOKEN_URI=https://auth.yourdomain.com/token
OIDC_USERINFO_URI=https://auth.yourdomain.com/userinfo

Step 6: Set Up Integrations

Notion Feature	Outline Equivalent
Slack integration	✅ Slack plugin (search, share, notifications)
API	✅ Comprehensive REST API
Embed blocks	✅ Embeds (YouTube, Figma, etc.)
Webhooks	✅ Webhooks
Templates	✅ Document templates
Public sharing	✅ Public links with custom domains

What You'll Gain

• Self-hosted data — your docs on your server
• No per-user pricing — unlimited users
• Real-time collaboration — same as Notion
• API access — full REST API for automation
• Custom domains for public docs
• Faster editor — lightweight, focused on writing

Full Outline Deployment Walkthrough

The migration steps above cover the mechanics of getting data from Notion to Outline, but a production-grade Outline deployment requires additional configuration that the quick-start guide skips over. This section covers storage backends, reverse proxy setup, and the decisions that determine whether Outline feels fast and reliable or fragile.

Storage Backend

Outline requires an S3-compatible object store for file uploads and attachments. For teams already using AWS, S3 is the obvious choice. For self-hosters who want to keep everything on their own infrastructure, MinIO is the most widely tested option.

MinIO can run as an additional service alongside Outline in the same Docker Compose stack. Configure it with a dedicated bucket and generate access credentials using the MinIO admin console. In your Outline .env, set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET, and AWS_S3_UPLOAD_BUCKET_URL to point to your MinIO instance. The endpoint URL format matters — Outline expects a URL without a trailing slash and with the bucket name as a path component, not a subdomain.

Backblaze B2 is another popular choice for self-hosters who want off-server storage at low cost. B2 offers S3-compatible APIs. The configuration is identical to MinIO except the endpoint and region are set to Backblaze's values. The pricing is a fraction of AWS S3, which matters once your wiki accumulates screenshots, diagrams, and other binary attachments.

Reverse Proxy and HTTPS

Outline must be served over HTTPS — the application enforces this for security. The simplest path is Caddy, which handles certificate provisioning and renewal automatically:

wiki.yourdomain.com {
    reverse_proxy localhost:3000
}

Nginx works equally well but requires manual certificate renewal configuration using certbot or similar. Traefik is worth considering if you're already running it as a reverse proxy for other self-hosted services — its Docker label-based configuration keeps all routing configuration close to the service definition in Docker Compose.

Database and Performance

Outline's PostgreSQL database benefits from a few configuration adjustments for wikis that grow beyond a few thousand documents. Set shared_buffers to 25% of available RAM, enable pg_trgm extension for faster full-text search, and configure connection pooling with PgBouncer if you're running many concurrent users. Without connection pooling, Outline opens a new database connection for each request, which can exhaust PostgreSQL's connection limit on a moderately busy wiki.

For teams evaluating Outline alongside other open source wiki tools before committing to a migration, the AppFlowy vs Outline comparison and the Docmost vs Outline comparison provide useful context on how these tools differ in editing experience, database requirements, and collaboration features. Outline occupies the team wiki niche most directly, but AppFlowy and Docmost address slightly different use cases worth understanding before you invest in a full migration.

Security and Operational Hardening

Outline stores your team's institutional knowledge — architecture decisions, runbooks, customer data, and internal processes. Getting security right is not optional.

Authentication: Outline delegates authentication entirely to external providers, which is both a strength and a configuration burden. Because Outline never stores passwords itself, you don't have to worry about password storage security. But you do need a reliable identity provider. For teams already running Authentik or Keycloak for SSO, configuring Outline's OIDC integration gives you consistent login across your self-hosted stack with centralized session management and MFA enforcement. If you're choosing an identity provider for the first time, the Keycloak vs Authentik comparison walks through the tradeoffs for self-hosted teams.

Environment secrets: The SECRET_KEY in Outline's .env is used to sign sessions and encrypt sensitive data. Generate it once with openssl rand -hex 32, store it in a password manager or secrets vault, and never rotate it without a planned migration — rotating this key invalidates all existing sessions and may cause data loss.

Backups: Outline's data lives in three places: the PostgreSQL database (documents, users, collections), the object store (attachments and uploads), and your .env file (configuration and secrets). A complete backup strategy covers all three. For the database, daily pg_dump exports are a practical baseline. For object storage, replicate your MinIO bucket to a second destination using MinIO's built-in replication or rclone. Keep a copy of your .env in a separate secure location — losing it means losing the ability to decrypt data even if you have database backups.

Network exposure: Outline's web interface should be the only service exposed to the internet. PostgreSQL, Redis, and MinIO should be bound to localhost or the Docker internal network. Confirm this by running ss -tlpn and verifying that none of the database ports appear in the LISTEN state on your public IP.

Audit logging: Outline maintains an activity log of document creation, edits, and permission changes. For teams with compliance requirements, this audit trail is valuable — preserve it in your backup rotation.

What Doesn't Transfer and How to Handle It

The migration table at the top of this article flags several Notion features that don't transfer cleanly. Here's practical guidance on each.

Databases become static tables: Notion's relational databases — with their views, filters, formulas, and rollups — are one of Notion's most powerful differentiators. When exported and imported into Outline, they become static Markdown tables. For boards and task lists, this means rebuilding the tracking workflow elsewhere. Teams that used Notion databases primarily as tables of reference data (tech stack inventories, vendor lists, team directories) lose the least — the data is there, just not filterable. Teams that used Notion databases as project management tools need to move that workflow to a dedicated tool like Plane or Vikunja rather than trying to replicate it in Outline.

Comments are lost: Notion's inline and page-level comments don't survive export. If you have important discussion history embedded in comments, export and archive those separately before migration. Screenshot critical comment threads or copy them into the document body before exporting.

Page analytics: Notion's page analytics (view counts, recent visitors) don't transfer. Outline doesn't have equivalent built-in analytics. If page popularity data matters to your workflow, export and save that data before migrating.

The broader knowledge base ecosystem: Outline focuses on team wikis and documentation. If your Notion workspace also served as a project management tool, customer database, or content calendar, you'll need separate tools for those functions after migration. The best open source alternatives to Notion roundup covers the full landscape of tools that address Notion's different use cases, helping you assemble a suite that replaces Notion's breadth without the vendor lock-in.

Migration Timeline

Day	Task
Day 1	Deploy Outline, configure auth, import Notion export
Day 2	Organize collections, set up integrations
Day 3-5	Invite team, run both platforms
Week 2	Primary usage moves to Outline
Week 3	Sunset Notion, downgrade plan

Evaluating Outline vs Other Notion Alternatives

Outline is the most Notion-like open source wiki, but it's not the only option worth considering before committing to a migration. Understanding where Outline fits in the broader landscape prevents a second migration later.

Outline is built for team wikis: structured collections, real-time collaboration, and a clean editor optimized for writing documents rather than building databases. It handles the documentation and knowledge sharing use case Notion was originally designed for. What it doesn't do: project tracking, databases, or the hybrid document-database use case that Notion's power users relied on most.

If your Notion usage was primarily pages, sub-pages, and linked databases you used like a wiki, Outline is the right migration destination. If your Notion workspace was deeply reliant on filtered database views, rollup properties, and formula fields, you likely need a combination of tools after leaving Notion — Outline for documentation plus a dedicated project management tool for structured data.

AppFlowy is the other major open source Notion alternative worth knowing. It aims to be a full Notion replacement with both documents and databases. It's earlier in development than Outline and the self-hosted experience is less polished, but it addresses the database and grid view use cases that Outline deliberately omits. The AppFlowy vs Outline comparison covers these differences in detail.

For teams specifically choosing between Outline and another documentation-first tool, the Docmost vs Outline comparison examines the two most direct competitors in the open source team wiki space. Docmost is a newer project with a cleaner architecture and lower resource requirements; Outline is more mature with a larger community and more integrations. If you're starting a new installation rather than migrating from Notion, reading both comparisons before deciding saves significant migration effort later.

---

Compare wiki and knowledge base tools on OSSAlt — editing experience, collaboration, and self-hosting options side by side.

See open source alternatives to Notion on OSSAlt.