Notion's importer caps at 30GB and degrades most macros. Internal links all break. Enterprise migrations need managed pipelines for macro mapping, link preservation, and zero downtime.
Notion has a native Confluence importer — both a ZIP-file path (up to 5 GB) and an API importer (up to 30 GB / ~50k pages) — but for enterprise documentation with nested macros, complex page hierarchies, thousands of internal links, or attachment-heavy content, the importer's limits hit fast and content degrades silently. Confluence is a wiki built on XHTML-based storage format with embedded macros, deep parent-child page trees, and granular space-level and page-level permissions. Notion is a block-based document platform where content is composed of typed blocks — text, toggles, callouts, databases — with a flat teamspace permission model. Macros are the fundamental gap: Notion has no macro system, so every Confluence macro degrades to the nearest block type or is dropped entirely. Every migration must handle the 30 GB API ceiling, broken internal links (Notion does not remap Confluence page IDs), unreferenced attachments silently dropped during import, and the complete loss of Confluence's permission model. For large documentation sets, internal link remediation alone is the most time-consuming post-migration task.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Confluence Server/DC difference
The HTML export from Server and Data Center uses a different folder structure for attachments than Cloud exports. Attachment paths may not resolve correctly if you mix export formats or manually restructure the archive before uploading to Notion.
Notion only supports user-scoped API tokens (not scoped tokens)
Use the personal API token option when authenticating. Atlassian now applies token expiration by default. If your security team has standardized on scoped tokens or short token lifetimes, validate the auth model before scheduling the migration window. (notion.so)
If your migration scope includes Confluence Databases, page export is not enough
Export each database intentionally, land the raw rows in Notion, then rebuild relations, rollups, and formulas as part of the target design.
If an API import fails mid-way through a 20GB workspace, there's no "resume from where it
If an API import fails mid-way through a 20GB workspace, there's no "resume from where it left off." You restart the entire space. For organizations with 10+ spaces averaging 5GB each, this can turn a planned weekend migration into a week-long project.
Open-source tool maintenance warning
Both startmatter/confluence2notion and hmartiro/confluence_to_notion are community-maintained projects. Before relying on either, check the last commit date and open issues on GitHub. The hmartiro script uses the unofficial Notion API (token_v2 browser cookie), which is undocumented and can break without warning from Notion. If the repo hasn't been updated recently, assume it may not work with the current Notion API surface.
XML exports are space-by-space
There is no native "export all spaces" button. For a 200-space DC instance, this means 200 separate export operations — each of which queues behind any other running export job.
The math on a 200K-page migration
At 3 requests/second, you get ~10,800 API calls per hour. Each page requires at minimum: 1 call to create the page + 1–3 calls to append body content + 1 call per attachment. A conservative estimate of 5 calls per page × 200,000 pages = 1,000,000 API calls. At 10,800/hour, that's ~93 hours of continuous API throughput — assuming zero errors, zero retries, and no attachment uploads. In practice, expect 2–4 weeks for a large DC migration using a single integration token.
Audit before you migrate
Archive inactive spaces. Merge overlapping spaces. The migration is your chance to clean up years of organic sprawl — don't replicate a messy structure into a new platform.
If your Confluence DC deployment exists for regulatory compliance reasons, confirm with
If your Confluence DC deployment exists for regulatory compliance reasons, confirm with your legal and security teams that Notion satisfies those specific frameworks before beginning any technical migration work. Notion EU residency ≠ ITAR compliance. Notion audit logs ≠ SOC 2 Type II for document management.
Built-in importer and public API are different tools
If you bypass the built-in importer and build directly against Notion's public API, you gain full control over structure and edge cases, but you also own block chunking, retries, attachment handling, and permission remapping. The built-in importer handles much of this automatically — within its documented limits.
This section summarizes the key decisions and checks to complete before any technical work begins
The details behind each point are covered in the sections above.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Decide what content deserves to move before you plan how to move it.
Objective A content inventory with a keep/rewrite/retire decision on every article and an agreed URL strategy.
Keep these open
-
Inventory all content in Confluence
Count articles, categories, attachments, images and embedded media, and pull page views and last-updated dates for each article. Usage data is what makes the next decision defensible rather than political.
Data Profiler Get real record counts instead of estimating from memory -
Make a keep, rewrite or retire call on every article
Most knowledge bases are half stale. Migrating everything imports the staleness and doubles the work; use views and last-updated to triage, and get the owning team to confirm. This usually removes 30-50% of scope.
Migrating stale content is the most common knowledge-base migration mistake — it costs effort and actively degrades the new site.
-
Agree the URL and redirect strategy
Decide the Notion URL structure and whether you can serve 301 redirects from the old paths. Public help centres carry real search traffic and inbound links; losing it is a measurable commercial impact.
Without 301 redirects from old article URLs you lose accumulated search ranking and every external link and bookmark breaks.
-
Map the information architecture
Document the current category tree and design the target one, checking whether Notion supports your nesting depth. Deeply nested hierarchies frequently have to be flattened, which changes navigation for everyone.
-
Confirm permissions, audiences and localisation scope
Establish which content is public, internal or restricted, and how Notion models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
-
Map your hierarchy on paper
Decide which spaces become teamspaces, which become top-level pages, and where permissions will be simplified rather than copied exactly. Get stakeholder sign-off before page one lands — restructuring after migration is painful.
COI & ROI Calculator Build the 36-month business case you will need for sign-off
Confluence → Notion specifics
- Address compliance first
- If your DC deployment exists for data sovereignty reasons, confirm that Notion's data residency options satisfy your requirements before starting the technical work. See the compliance gap section above.
- Accept the losses
- Page history, inline restrictions, watch subscriptions, and comments (unless using Notion's API importer) will not survive. Communicate this to your teams early.
Don't move on until
- Full content inventory with page views and last-updated dates
- Keep / rewrite / retire decision recorded per article
- URL and redirect strategy agreed with whoever owns SEO
02 Data Audit Audit the markup, the links and the assets — that is where KB migrations break.
Objective A content export with markup, internal links and every embedded asset accounted for.
Keep these open
-
Export content and assess markup fidelity
Export articles in the richest format available and inspect what survived: tables, code blocks, callouts, nested lists, anchors and embedded video. Rich formatting is where fidelity is lost, and it is lost quietly.
HTML-to-Markdown conversion routinely mangles nested lists, tables and code blocks. Inspect the output rather than trusting the converter.
Data Profiler Profile the Confluence export for nulls, outliers and type drift -
Inventory every internal link and cross-reference
Extract all internal links, anchor links and article cross-references. These break by default: the target URL structure differs, so every internal link needs rewriting as part of the load, not afterwards.
Internal links left pointing at old URLs turn the new knowledge base into a maze of 404s on day one.
-
Inventory images, attachments and embedded media
List every asset with its URL, size and type, and confirm each still resolves. Assets hosted on the old platform's CDN will 404 the moment you decommission it, so they must be rehosted, not referenced.
Images referenced from the source platform's CDN break when the old account closes. Download and rehost every asset.
-
Find and fix broken links and orphans
Crawl for existing broken internal and external links, and find articles no category links to. Fix them before migrating — a migration is a bad time to discover pre-existing rot.
-
Check for PII and internal information in public content
Scan for customer names, internal hostnames, credentials in code samples and screenshots containing real data. Republishing these on a public help centre is a disclosure, and screenshots are the usual culprit.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Normalise metadata
Standardise authors, tags, timestamps to UTC, and locale codes. Author mapping needs a decision for people who have left — attribution to a deleted user usually fails the import.
-
Batch block creation
always fill each append request to the 100-block maximum.
-
Audit your macros
Run a macro usage report across all spaces. If more than 20% of your pages use dynamic macros (Jira issues, draw.io, page includes), budget significant time for pre-migration resolution.
Confluence → Notion specifics
- Needs pre-migration conversion
- LaTeX blocks → inline LaTeX, Gliffy → exported PNG/SVG
- Page-level restrictions are permission-dependent
- If a site admin runs the export, all content is included — even restricted pages. If a space admin runs it, restricted content the admin can't view is silently excluded with no error message.
- Large spaces with many attachments
- can fail on certain file systems. Confluence copies attachments to a temp directory during export, and file systems like ext3 have subdirectory limits that large spaces can exceed — Atlassian's KB cites failures when a space has more than 32,000 pages with attachments on ext3, producing a cryptic "Error creating temp file in folder" failure. (support.atlassian.com)
- Rate limiting is admin-configurable
- and uses a token bucket model. Admins set a requests-per-interval limit (e.g., 100 requests per hour) that applies per node in a clustered deployment. If rate limiting is enabled, your extraction scripts will hit HTTP 429 responses. The retry-after header tells you how long to wait. (confluence.atlassian.com)
- Rate limiting targets external REST API requests only
- Requests from within the Confluence UI are not throttled. But the classification logic checks for specific headers and cookies — reverse proxy misconfiguration (e.g., Nginx stripping the Referer header) can cause internal UI requests to be misclassified as external, triggering rate limits on regular users.
Don't move on until
- Content exported with markup fidelity assessed
- Every internal link and asset reference inventoried
- Broken links and missing assets fixed or logged
03 Field Mapping Map structure, metadata, permissions and — above all — URLs.
Objective A mapping covering article fields, taxonomy, permissions and a complete old-to-new URL map.
Keep these open
-
Map the article schema
Map title, body, excerpt, author, dates, status, tags, SEO metadata and any custom properties. Confirm which fields Notion lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Confluence → Notion field pair -
Map the taxonomy and hierarchy
Map categories, sections and tags to the target structure, resolving any nesting-depth limit explicitly. If you must flatten, decide how the lost level is preserved — usually as a tag or a title prefix.
JSON to CSV Converter Flatten nested API responses into a reviewable sheet -
Map permissions and audience segmentation
Map public, logged-in, and role-restricted visibility to Notion's model. Verify the mapping deliberately: internal content accidentally published publicly is the highest-severity failure in this whole category.
Permission mapping errors publish internal documentation to the open web. Verify visibility on every restricted article after load.
-
Build the complete old-to-new URL map
Produce a row per article mapping the old URL to the new one, then confirm exactly where the 301s will be served — Notion, a CDN, or your own web layer. Without this artifact the redirect step cannot be executed at all.
-
Define the markup conversion and link-rewrite rules
Specify how each markup construct converts and how internal links are rewritten using the URL map. Write it as a repeatable transform, not manual edits — you will run it more than once.
Data Format Converter Reshape the export into the format Notion's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Notion, then version and sign off the mapping spec.
Don't move on until
- Article schema and taxonomy mapped
- Permission and audience model mapped to target equivalents
- Complete URL map produced and redirect method confirmed
04 Test Migration Pilot the hardest articles, then read them.
Objective A pilot load whose formatting, links, assets and search all hold up under human review.
Keep these open
-
Configure Notion with the agreed structure
Create the category tree, permission groups, locales and branding before loading. Articles loaded before their categories exist land uncategorised and have to be moved by hand.
-
Pick the most difficult articles as the pilot
Choose 20-50 articles for difficulty: the longest, the most heavily formatted, ones with tables and code blocks, deep internal linking, many images, embedded video, restricted visibility, and non-Latin scripts. Easy articles prove nothing.
-
Run the conversion and load with link rewriting
Apply the markup conversion, rewrite internal links from the URL map, upload and re-reference assets, then load. Log every conversion warning rather than suppressing it.
-
Read every pilot article side by side
Open source and target together and compare rendering. This step is manual on purpose: no automated check catches a table that collapsed into a paragraph or a code block that lost its indentation.
-
Click every link and load every asset
Verify each internal link resolves, each image loads from the new host, each attachment downloads and each embed plays. Assets still served from the old CDN are the defect that surfaces only after decommissioning.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Test search and permissions
Search for known terms and confirm the right articles rank, then verify every restricted pilot article is invisible to an anonymous browser. Test permissions from a logged-out session, not an admin one.
-
Run a pilot
Pick a representative space — one with macros, attachments, and nested pages — and migrate it first. Measure what translates, what breaks, and how long it takes under real Notion API constraints. A pilot turns assumptions into data.
Don't move on until
- Complex articles render correctly with formatting intact
- Every internal link and asset in the pilot resolves
- Search returns sensible results for the pilot content
05 Cutover Publish, redirect, and keep the search traffic.
Objective All in-scope content live in Notion with redirects serving and search engines informed.
Keep these open
-
Load the full content set ahead of the switch
Run the full conversion and load into Notion, unpublished or on a staging domain. Content migration differs from data migration here: you can stage the whole thing before anyone sees it.
-
Publish the runbook with the redirect step first-class
Sequence the freeze, final delta, publish, redirect activation, sitemap submission and link updates, with owners for each. Redirect activation is the step with lasting commercial consequences, so it gets explicit ownership.
-
Freeze editing and migrate the delta
Stop editing in Confluence, then convert and load anything changed since the full load. Announce the freeze to every team that publishes — content teams are used to editing whenever they like.
-
Publish and verify permissions live
Publish the content set, then immediately verify restricted articles are not publicly reachable using an anonymous session. Do this before announcing the new site, not after.
Verify restricted content from a logged-out browser. An admin session will show you everything and tell you nothing.
Migration Validation Tool Confirm the final delta landed before you reopen -
Activate 301 redirects and submit the sitemap
Turn on the redirects from the URL map, then spot-check a sample of high-traffic old URLs and confirm each returns 301 to the right article. Submit the new sitemap and keep the old one reachable until search engines have recrawled.
Redirect chains and redirect loops both leak ranking. Verify each redirect resolves in a single hop.
-
Repoint in-product and support links
Update help links embedded in your product, in support macros, in email templates and in onboarding material. These are the links your existing customers actually use, and they are easy to forget.
Confluence → Notion specifics
- Confluence Cloud
- Your instance is still live. No data has been removed.
- Confluence Server/DC
- If you're migrating because of a planned Server shutdown, take a full site backup (XML export or database snapshot) before decommissioning. Store it somewhere accessible — you may need it for audit, compliance, or re-import.
- Notion rollback
- Notion does not have a one-click "undo import" feature. If you need to remove imported content, you'll delete the imported page trees manually. For large imports, this is tedious but straightforward.
Don't move on until
- All content loaded, categorised and correctly permissioned
- 301 redirects live and verified from a sample of old URLs
- Sitemap submitted and support links repointed
06 Validation Watch traffic, links and search rankings for weeks, not hours.
Objective Verified content completeness, healthy redirects, and search traffic recovered to baseline.
Keep these open
-
Reconcile content counts and assets
Compare article counts by category and status, plus asset counts, against source. Confirm every article in the keep list is present and every retired one genuinely is not.
Migration Validation Tool Reconcile Confluence and Notion record-for-record -
Crawl the new site for broken links and assets
Run a full crawl for 404s, broken images and missing attachments, and fix everything it finds. Repeat the crawl after the fixes rather than assuming they worked.
-
Verify the redirects at scale
Test every mapped old URL for a single-hop 301 to the right destination. Chains and loops both leak ranking and are invisible unless you check the whole map, not a sample.
-
Monitor organic traffic and rankings for four to eight weeks
Track organic sessions, impressions and rankings for your top articles against baseline. A dip in the first two weeks is normal; one that has not recovered by week six is a redirect or indexing problem to investigate.
Do not decommission the old platform until search traffic has recovered — you may still need the old URLs to diagnose a ranking loss.
-
Verify search, permissions and feedback loops
Confirm on-site search returns good results for real queries, re-verify restricted content from a logged-out session, and check article feedback and analytics are collecting.
-
Sign off and decommission on a delay
Get acceptance against the Discovery criteria, keep Confluence available read-only until traffic has recovered, take a final export, and only then close the account.
Confluence → Notion specifics
- Needs post-migration rebuild
- page-properties, roadmap, jira-issues panel, custom app macros
Don't move on until
- Article counts reconciled and no broken links remain
- Redirects returning 301 with no chains or loops
- Organic traffic recovered to within tolerance of baseline
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Internal Links | high | All Confluence page-ID-based cross-references break — requires full link remapping after import |
| Confluence Macros (Nested/Complex) | high | Nested bodied macros, Page Properties, LaTeX blocks, and Jira macros degrade to plain text or are dropped entirely |
| Page-Level Permissions | high | No Notion equivalent — granular access controls must be completely redesigned for Notion's teamspace model |
| Confluence Databases | high | Standard page exports do not retain database content — each must be exported to CSV separately with relations rebuilt manually |
| Unreferenced Attachments | high | Files attached to pages but not embedded in the body are silently dropped during import |
| Expand/Panel Macros | medium | Expand maps to toggles (reasonable), but Info/Warning/Note panels often lose visual styling |
| Comments & User Attribution | medium | Only the API importer retains comments and user mapping — ZIP import drops both entirely |
| Blog Posts | medium | Atlassian's HTML export does not include blog posts — ZIP import path misses them entirely |
| Code Blocks | low | Generally survive import but may lose language annotations |
| Page Hierarchy | low | Both importers preserve basic parent-child page structure within a single space |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Macro Degradation
Most Confluence macros are unsupported. Nested bodied macros flatten to plain text, LaTeX blocks fail to render, and Gliffy diagrams are dropped unless pre-converted to images before import.
Broken Internal Links
Notion does not remap Confluence internal links during import. Every cross-reference between pages breaks and must be rebuilt via a page-ID-to-Notion-URL mapping pass.
Size & File Count Limits
ZIP importer caps at 5 GB (15 GB on request) and archives with 10,000+ files can fail. The API importer supports up to 30 GB but larger imports may fail with no resume capability.
Permission Model Loss
Confluence's granular space-level and page-level permissions are not replicated. All content lands under a single private root and access must be rebuilt manually in Notion teamspaces.
Unreferenced Attachments
Attachments and media not explicitly embedded in page bodies are silently dropped during import — files used as a repository on Confluence pages vanish without warning.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
What are the size limits for Notion's Confluence importer?
The ZIP-file importer supports up to 5GB (15GB upon request). The API importer supports up to 30GB and ~50k pages. Notion's ZIP docs also warn that 10,000+ files can fail even under the size limit. Workspaces larger than 30GB must be split or migrated using custom pipelines.
Do Confluence macros work after migrating to Notion?
Most Confluence macros are unsupported. Notion maps them to the nearest block type (e.g., Expand → Toggle), but complex macros like nested bodied macros, ui-steps, Page Properties, and LaTeX blocks degrade to plain text or are dropped entirely.
How do I fix broken internal links after migrating Confluence to Notion?
Notion does not remap Confluence internal links during import. You need to build a mapping of old Confluence page IDs to new Notion page URLs and run a find-and-replace across all imported pages. ClonePartner does this automatically during migration.
Can I migrate Confluence comments and users to Notion?
Only the API importer retains comments and maps Confluence users to Notion users by email or username. The ZIP-file importer does not carry over comments or user attribution. Atlassian's HTML export also excludes page comments.
How do I migrate Confluence Databases to Notion?
Treat Confluence Databases as a separate migration stream. Standard page exports do not retain database content or functionality. Export each database to CSV, import into Notion, then rebuild relations, rollups, and formulas manually.