--- title: "Confluence to Notion Migration: Limits, Macros & Broken Links" slug: confluence-to-notion-migration-limits-macros-broken-links date: 2026-04-07 author: Raaj categories: [Confluence, Notion] excerpt: "Notion's native Confluence importer caps at 30GB, breaks macros, and drops internal links. Learn what fails and how to migrate without data loss." tldr: "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." canonical: https://clonepartner.com/blog/confluence-to-notion-migration-limits-macros-broken-links/ --- # 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](https://clonepartner.com/blog/blog/notion-vs-confluence-2026/). ## 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. | | ZIP Importer | API Importer | |---|---|---| | **Size limit** | 5GB (15GB on request) | 30GB | | **Scope** | Selective pages | Entire workspace | | **Comments** | ❌ Not imported | ✅ Retained | | **User mapping** | ❌ No | ✅ Email/username match | | **Multi-space** | One at a time | Up to 10 at once (Business/Enterprise) | | **Auth requirement** | HTML export ZIP | Atlassian API token | | **Best for** | Partial moves, testing | Full workspace migrations | 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](https://www.notion.so/help/import-from-confluence)) 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](https://clonepartner.com/blog/blog/how-to-export-all-data-from-confluence-methods-limits-tools/). ([support.atlassian.com](https://support.atlassian.com/confluence-cloud/docs/export-content-to-word-pdf-html-and-xml/)) ### API Importer: Auth Requirements > [!WARNING] > 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](https://www.notion.so/help/import-from-confluence)) 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](https://support.atlassian.com/confluence-cloud/docs/export-content-to-word-pdf-html-and-xml/)) 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](https://support.atlassian.com/confluence-cloud/docs/create-a-site-backup/)) > [!CAUTION] > 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. ### 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](https://www.notion.so/help/import-from-confluence)) ### 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). > [!CAUTION] > 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. ## 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](https://developers.notion.com/reference/request-limits)) - 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 | Criteria | Native Importer | DIY Scripts | ClonePartner | |---|---|---|---| | **Max data volume** | 30GB | Unlimited (slow) | Unlimited | | **Macro handling** | Degrades to plain text | Custom per-script | Programmatic block mapping | | **Internal link preservation** | ❌ All break | Partial (with effort) | ✅ Full remap | | **Comments & users** | API importer only | ❌ Most scripts skip | ✅ Preserved | | **Delta/incremental sync** | ❌ | ❌ | ✅ | | **Downtime** | Full cutover required | Full cutover required | Zero downtime | | **Engineering effort** | Low | High | None | ## 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 `` 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](https://clonepartner.com/blog/blog/notion-confluence-sync-integration-architecture/). **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: ```bash # 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](https://www.notion.so/help/import-from-confluence)) ### 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](https://support.atlassian.com/confluence-cloud/docs/create-a-site-backup/)) ### 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 `` and `` 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](https://www.notion.so/help/import-from-confluence)) ### 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. > [!TIP] > **ClonePartner offers sample migrations** — we'll run your most complex space through our pipeline before any commitment, so you can see exactly what the output looks like. ## 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. > Ready to migrate from Confluence to Notion without losing macros, links, or your sanity? Book a free 30-minute consultation and we'll scope your migration — including a sample run on your most complex space. > > [Talk to us](https://cal.com/clonepartner/meet?duration=30&utm_source=blog&utm_medium=button&utm_campaign=demo_bookings&utm_content=cta_click&utm_term=demo_button_click) ## Frequently asked questions ### 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.