Confluence to Notion Migration: Limits, Macros & Broken Links

Notion's native Confluence importer works for small wikis. For anything beyond a handful of spaces — enterprise documentation with nested macros, complex page hierarchies, thousands of internal links, or attachment-heavy content — the importer's limits will hit fast.

This guide covers what breaks, why it breaks, and the three main approaches to get your data across with the highest fidelity.

If you want to understand the architectural differences between the two platforms before committing to a move, start with our Notion vs. Confluence (2026) comparison.

Notion's Native Import Options: API vs. ZIP File

There are two ways to import from Confluence into Notion. The ZIP-file importer can import only part of your workspace, but is limited to 5GB (or 15GB upon request). The API importer imports the entire workspace, handles workspaces up to 30GB, and retains comments and user-mapping.

The API importer is reliable up to ~50k pages or 30GB in size. Larger imports may fail. Macros are mapped to flattened content or the closest Notion block type (e.g., Confluence Expand → Notion Toggle).

Multi-space imports allow up to 10 Confluence spaces at once through the UI. Each space generates its own log page and imports as a separate top-level private page. This feature is only available to Business and Enterprise plans.

ZIP Importer: Hidden Gotchas

The ZIP path depends on a very specific source export: Confluence exported to HTML — not XML, not PDF. Upload the full archive without unzipping it.

File count matters almost as much as file size. Notion's ZIP import documentation warns that very high file counts can fail even under 5GB, and archives with 10,000+ files are likely to fail or partially import. For attachment-heavy spaces, audit file count before attempting the import. (notion.so)

Atlassian's HTML export also does not include blog posts, and page comments are not exported in HTML format. If blogs or comments matter, the ZIP route is the wrong starting point. For a deeper breakdown of Confluence export formats, see How to Export All Data from Confluence. (support.atlassian.com)

API Importer: Auth Requirements

If you need to move several spaces, Notion supports multi-space imports for up to 10 spaces on Business and Enterprise plans. Outside that path, run spaces sequentially — one at a time.

How to Export Your Confluence Space for ZIP Import

1. From your Confluence workspace, go to Space Settings in the top-right sidebar. Select Content Tools in the top toolbar, then Export.
2. Select HTML from the list of formats. Select Custom Export and uncheck the "Include comments" box. Select which pages you want to export.
3. Pages containing large attachments can significantly increase the export size and complexity.
4. Once the export is complete, click Download to save the file. You should get a file titled something like Confluence-space-export-XXXXXX.html.zip.

Then in Notion:

1. Navigate to the Notion workspace you'd like to import into. Go to Settings → Import → Confluence.
2. Navigate to the .zip file and select it for upload. You do not need to unzip the file.
3. You'll see an "Uploading..." message, then a status update as the import progresses. When complete, it takes you to the newly imported content.

What Breaks: Macros, Nested Pages, Permissions, and More

This is where the "few-click migration" story falls apart. Notion's importer makes a best-effort pass, but several categories of Confluence content degrade or disappear.

Macros

Table styling and macros/plugins often degrade (e.g., ui-steps, callouts, image captions). Most macros are unsupported. Notion tries to map data to the nearest Notion block.

In practice:

• Expand macros → Notion toggles (this one works reasonably well)
• Info/Warning/Note panels → often become plain text or lose visual styling
• Code blocks → generally survive, but may lose language annotations
• Table of Contents macro → dropped entirely
• Nested bodied macros (macro inside a macro) → flatten to plain text with no structure
• LaTeX block macros → fail to render. Convert LaTeX block macros to inline macros in Confluence before re-importing, or place the LaTeX in a code block and convert to a math block manually after import.
• Gliffy diagrams → Notion doesn't support Gliffy images via the file importer. Fix: modify the HTML to replace the Gliffy block with an image block referencing the correct file before importing.

Attachments and Media

Attachments and media not referenced on pages will not be imported. This is a silent loss. If your team uses Confluence pages as a file repository — attaching documents that aren't explicitly embedded in the page body — those files vanish during import.

Atlassian's HTML export stores attachments in page-ID folders inside the ZIP. If you repackage the archive incorrectly, exclude parent pages, or leave orphaned files unattached to page bodies, expect missing assets after import.

Internal Links

Confluence internal links use page IDs and space keys. After import, these links point to URLs that no longer exist. Notion does not remap Confluence internal links to their new Notion page equivalents. Every cross-reference between pages breaks.

Broken links often stem from scope problems: the target page was excluded from a custom HTML export, was hidden by permissions, or was imported into a different root. (support.atlassian.com)

For large documentation sets with hundreds of cross-linked pages, this is the single most time-consuming post-migration fix.

Permissions

Confluence permissions are not replicated in Notion. This is expected with self-serve imports. Imported pages land under a single private root for the importing user or inside a selected teamspace. Confluence's granular space-level and page-level permission model has no direct equivalent in Notion's teamspace architecture. You rebuild access controls manually.

Confluence Databases

If your team uses the newer Confluence Databases feature, treat it as a separate migration stream. Atlassian says site backups show databases in the tree but do not retain their content, data, or functionality. Atlassian supports database exports to CSV, HTML, and PDF separately. On the Notion side, CSV imports create a database, but relations, rollups, formulas, and relation mapping need to be rebuilt after import. (support.atlassian.com)

Table Behavior

Not all table-like content behaves the same after import. A Confluence table with files or attachments becomes a Notion database; a table without files becomes a simple table. Useful for lightweight content, but not equivalent to preserving a structured data model. (notion.so)

Transient Failures and Timeouts

Transient failures due to Confluence API unreliability can cause the overall import or certain pages to fail. You may need to retry the entire import. For multiple spaces, run imports sequentially unless using multi-space import (Business/Enterprise only).

Import failures can also occur with complicated Confluence data (e.g., merged cells, tables within tables).

DIY Scripts vs. Native Importer vs. Managed Migration

Three main paths. The right one depends on your data volume, engineering capacity, and tolerance for post-migration cleanup.

Option 1: Notion's Native Importer

Best for: Teams under 5GB with simple page structures and minimal macro usage.

• Zero cost, built into Notion
• API importer retains comments and user mapping
• Works reasonably well for flat, text-heavy documentation
• 5GB/30GB hard ceilings (plus file-count limits on ZIP)
• No macro translation — everything degrades to plain text or nearest block
• All internal links break
• No delta/incremental migration — all-or-nothing per space
• Transient Confluence API errors force full restarts

Option 2: DIY Python Scripts

Open-source tools like startmatter/confluence2notion iterate over all available Confluence spaces and recursively convert them to Notion pages. Another option, hmartiro/confluence_to_notion, focuses on post-import cleanup — fixing common issues from a Confluence HTML export using the unofficial Notion API, since images, attachments, and titles are often broken.

Best for: Engineering teams with Python expertise who have time to customize and maintain scripts.

• Full control over transformation logic
• Can handle macro-to-block mapping with custom code
• The hmartiro script includes a --fix-links flag that builds a title-to-URL mapping and rewrites internal links
• Most scripts rely on the unofficial Notion API (token_v2 browser cookie), which is undocumented and can break without warning
• The Notion API rate limit is an average of three requests per second per integration. The public API also caps at 100 child blocks per append request and a maximum payload of 500KB. Recursive page creation across thousands of pages takes hours. (developers.notion.com)
• No support for attachments, comments, or user attribution in most open-source tools
• You own the maintenance burden indefinitely

Option 3: Managed Migration (ClonePartner)

Best for: Organizations over 10GB, heavy macro usage, strict link preservation requirements, or teams that can't afford a multi-week migration window.

• Bypasses Notion's 30GB API importer limit using custom extraction and ingestion pipelines
• Programmatic macro mapping into native Notion blocks
• Internal link graph rebuilt: every cross-reference remapped to new Notion page URLs
• Delta migrations (background sync) — your team keeps using Confluence during the migration, zero downtime
• Sample migration on your hardest pages before any commitment
• Not free, but typically cheaper than the engineering hours burned on DIY for large workspaces

How ClonePartner Handles Complex Confluence Migrations

We've run enough Confluence-to-Notion migrations to know where the native tools break and what it takes to fix each failure mode.

Custom extraction pipelines. Instead of relying on Confluence's HTML export or Notion's API importer, we pull content directly from the Confluence REST API — page by page, with full attachment resolution and metadata preservation. This bypasses the 30GB ceiling entirely and avoids the transient-failure-restart problem. Our infrastructure uses exponential backoff and chunked extraction, pulling data in parallel to avoid triggering Atlassian's rate limits or Notion's import caps.

Macro-to-block mapping. We maintain a mapping library that converts Confluence macros into native Notion blocks:

• {expand} → Toggle block
• {info}, {warning}, {note}, {tip} → Callout blocks with appropriate emoji/color
• {code} → Code block with language tag preserved
• {toc} → Rebuilt using Notion's native TOC block
• Nested bodied macros → Nested toggle blocks or synced blocks depending on context
• Structured tables with Page Properties → Notion databases with mapped properties

Internal link graph reconstruction. We build a complete mapping of Confluence page IDs → new Notion page URLs during ingestion. Every <ac:link> reference and hardcoded Confluence URL is rewritten to point at the correct Notion destination.

Delta migrations. For teams that can't afford a hard cutover, we run a background sync that captures changes made in Confluence during the migration window and applies them to Notion. Your team keeps working in Confluence until the day you flip the switch. If your rollout requires both platforms to run simultaneously, see our guide on Notion-Confluence syncing and coexistence.

Sample migrations. Before any paid engagement, we run a sample migration on a representative subset of your data. We pick the hardest pages — not the cleanest ones — so you see the real landing quality before committing.

Pre-Migration Checklist: Preparing Your Confluence Space

Regardless of which migration approach you choose, this prep work saves hours of post-migration cleanup.

1. Audit Your Macros

Run a macro usage report in Confluence (or use the REST API: GET /wiki/rest/api/content?cql=macro="macroName") to identify every macro in use across your spaces. Categorize them:

• Auto-mapped by Notion: expand, basic code, simple tables
• Needs pre-migration conversion: LaTeX blocks → inline LaTeX, Gliffy → exported PNG/SVG
• Needs post-migration rebuild: page-properties, roadmap, jira-issues panel, custom app macros
• Can be dropped: outdated or unused macros

2. Identify Unreferenced Attachments

Since Notion silently drops attachments not embedded in page bodies, run an audit:

# Using Confluence REST API, find pages with attachments
curl -u user@email.com:API_TOKEN \
  "https://your-instance.atlassian.net/wiki/rest/api/content/{pageId}/child/attachment" \
  | jq '.results[] | {title: .title, fileSize: .extensions.fileSize}'

Compare the attachment list against what's actually referenced in each page's body.storage XML. Anything unreferenced needs to be either embedded in the page body or exported separately.

3. Measure Size and File Count

If the export is near 5GB or the archive will include many thousands of files, split the space before import. Notion's ZIP documentation warns that 10,000+ files can fail even under the size limit. File count is as important as total size. (notion.so)

4. Flatten Unnecessary Nesting

Deeply nested structures (5+ levels) become hard to navigate in Notion and can trigger edge cases in the importer. Deep nesting can cause edge cases in export structure. Test with a representative subset first; reorganize in Notion post-import. Before export, consider flattening to 3–4 levels max.

5. Pull Confluence Databases Out Separately

Export them directly to CSV or HTML. Standard page exports do not retain Confluence Database content or functionality. Plan to rebuild Notion relations and formulas. (support.atlassian.com)

6. Map Your Permission Model

• Export your Confluence space permission matrix
• Map Confluence groups to Notion teamspaces
• Identify page-level restrictions that need to be rebuilt as Notion page locks or private pages
• Accept that 1:1 permission parity is not achievable — plan for simplification

7. Document Your Internal Link Inventory

If you have hundreds of cross-space links, build an inventory before the move. A simple script can crawl your Confluence pages and extract every <ac:link> and <a href="/wiki/..."> reference into a CSV. You'll need this for link remediation regardless of migration approach.

8. Validate Auth Before Migration Week

Notion requires personal user-scoped tokens, not Atlassian scoped tokens. Atlassian now applies token expiration by default. Confirm your token configuration before cutover day. (notion.so)

9. Test With a Single Space First

Pick the space with the most macros, deepest nesting, and most cross-links. Run the migration on it first. If that space comes through clean, the rest will be straightforward.

What to Do After the Migration

The import is only half the job. Post-migration, plan for:

• Link audit: Crawl every imported page and verify internal links resolve. Flag anything pointing at old *.atlassian.net URLs.
• Macro rebuild: Walk through your macro audit list and rebuild anything the importer flattened.
• Attachment verification: Spot-check pages that previously had heavy attachments. Confirm files are accessible, not just referenced.
• Permission setup: Configure Notion teamspace access, page locks, and guest permissions based on your pre-migration permission map.
• Team onboarding: Confluence power users need guidance on Notion's block model, database views, and permission system.
• Redirect plan: If Confluence URLs were shared externally (in emails, Slack, Jira tickets), set up redirects or publish a mapping document.

Making the Right Call

For a small team with a single Confluence space under 5GB and light macro usage, the native importer is fine. Export HTML, upload the ZIP, spend an afternoon on cleanup.

For anything larger — multiple spaces, thousands of pages, macro-heavy documentation, strict link preservation requirements — the native tools will cost you more in engineering hours than a managed migration. The edge cases compound faster than most teams expect.

The honest reality: migrating content is straightforward. Migrating structure, context, and relationships is where it gets hard. That's the work we specialize in.