Confluence to SharePoint Migration: Methods, Limits & Macro Mapping

There is no native migration path from Confluence to SharePoint. Microsoft's SharePoint Migration Tool (SPMT) does not support Confluence as a source — SPMT is a migration solution to help you migrate content from on-premises SharePoint sites to Microsoft 365, and it supports migrating data from SharePoint to SharePoint, OneDrive, and Teams, but doesn't support any other source. There is no Atlassian-built migration wizard for this direction either. Moving from Confluence to SharePoint requires third-party tools, custom API scripts, or a migration partner.

This guide covers the real methods for migrating Confluence content to SharePoint Online, the hard platform constraints on both sides, and the macro-to-web-part mapping decisions that determine whether your migration succeeds or silently drops content.

Method	Fidelity	Macros	Attachments	Link Rewriting	Best For
Manual Export → Import	Low	❌	Partial	❌	<50 pages, quick archive
HTML Export → ASPX Conversion	Low–Medium	❌	Manual re-upload	❌	Static content, no macros
Custom API Scripts	Medium–High	Manual mapping	✅ (separate)	Partial	Engineering teams with time
WikiTraccs	High	✅ (hundreds of rules)	✅	✅	Self-service, wiki-centric orgs
Tzunami Deployer	High	Partial	✅	✅	Enterprise, compliance-heavy
ClonePartner Managed Migration	Highest	✅	✅	✅	Complex workspaces, zero downtime

For a deep dive on getting data out of Confluence before starting any migration, see How to Export All Data from Confluence: Methods, Limits & Tools.

Why Migrating from Confluence to SharePoint Is Complex

Confluence and SharePoint solve fundamentally different problems, and their data models reflect that.

Confluence is a collaborative wiki. Content lives in spaces, each containing a deep, nested tree of parent-child pages. Pages combine rich text, inline macros, embedded diagrams (draw.io, Gliffy), tables, and attachments — all stored in Atlassian's proprietary XHTML-based storage format. Hierarchy is first-class: every page knows its parent, and the page tree drives navigation.

SharePoint is a document management and intranet platform. Content lives in sites, each containing document libraries (for files), lists (structured data), and modern site pages (.aspx pages rendered via CanvasContent1 JSON). Confluence follows a hierarchical structure with pages and subpages automatically displayed in navigation, while SharePoint uses a different approach with a single-page repository and libraries for documents — its navigation tree starts with a few default links but is customizable.

This architectural mismatch creates several hard problems:

• Page hierarchy doesn't transfer. Confluence's parent-child tree has no native equivalent in SharePoint. You need a third-party solution like WikiPakk or custom SPFx navigation to replicate the page tree experience.
• Macros don't exist in SharePoint. Confluence macros (Code Block, Expand, Info/Warning panels, Children Display, Table of Contents) must be mapped to SharePoint web parts — or replaced entirely. In SharePoint Online, on modern SharePoint pages, you cannot nest web parts. This is a hard limitation that breaks any macro using nested content.
• Labels ≠ Metadata. Confluence uses freeform labels for categorization. SharePoint uses managed metadata term sets, content types, and enterprise keywords — a much more structured system.
• Permissions models differ. Confluence has space-level and page-level restrictions tied to Atlassian accounts. SharePoint uses Entra ID (formerly Azure AD), SharePoint groups, and a completely different inheritance model.
• Blog posts need explicit mapping. Confluence blog posts don't have a direct equivalent in SharePoint pages. SharePoint's sitePage model supports promotionKind values of page and newsPost, so blog-style content usually fits the news post model better than a standard page.
• Authorship and timestamps are read-only. In SharePoint's sitePage schema, createdBy, createdDateTime, lastModifiedBy, and lastModifiedDateTime are read-only fields. If preserving source authorship and dates matters for audit or search, you need custom columns (e.g., Source Author, Source Created) rather than assuming the API will let you stamp native page metadata.

For guidance on mapping Confluence spaces into modern SharePoint architecture, see The Modern SharePoint Architecture 2026: Transitioning from Subsites to Hub Sites.

The 4 Methods for Confluence to SharePoint Migration

Method 1: Manual Export and Re-upload

The lowest-tech approach. You can export all or part of a Confluence space to various formats, including Microsoft Word, HTML, PDF and XML. To use the space export functionality, you need the 'Export Space' permission.

How it works:

1. Export individual pages as Word/PDF, or export an entire space as HTML or XML.
2. Upload the exported files to a SharePoint document library.
3. Optionally, convert HTML files to .aspx pages for display as SharePoint site pages.

What breaks:

• Only the first 50 images attached to the page are exported to your Word document. This is to prevent out of memory errors affecting your whole Confluence site. If your pages are image-heavy, the Word path silently drops content.
• Confluence space-level PDF and HTML exports exclude blog posts.
• You will lose page links, navigation, labels and many other types of essential content.
• XML export is designed for re-importing into another Confluence instance, not SharePoint.

Best for: Archiving small spaces (<50 pages) where formatting fidelity doesn't matter. Not a migration strategy.

Method 2: HTML Export → ASPX Conversion

Export all content from Confluence as HTML files. Because of compatibility issues, if you don't convert to HTML, you are likely to lose some information during the migration. Convert all HTML files to ASPX files.

How it works:

1. Export the space as HTML (zip).
2. Rename .html files to .aspx.
3. Enable custom scripts at the tenant and site level. Put all of the .aspx files into a folder on the SharePoint Sites Documents page.

What breaks:

• Macros are rendered as static HTML at export time — no interactivity survives.
• Internal Confluence links break entirely (they still point to Confluence URLs).
• No metadata is preserved (author, dates, labels).
• Tables and layouts may render poorly in SharePoint's modern page framework.

Best for: Quick-and-dirty moves where you need readable content in SharePoint but don't care about navigation, links, or metadata.

Method 3: Custom API Scripts (Confluence REST → Microsoft Graph)

For teams with engineering capacity, building custom middleware using Python or Node.js to read the Confluence REST API and write to Microsoft Graph (or PnP PowerShell) gives full control.

How it works:

1. Use the Confluence REST API to enumerate spaces, pages, and attachments.
2. Parse the Confluence storage format (XHTML with macro markup).
3. Transform content into SharePoint's CanvasContent1 JSON format.
4. Create pages via Microsoft Graph or PnP PowerShell.
5. Upload attachments to the Site Assets library.
6. Rewrite internal links.

What breaks:

• Confluence Cloud uses a points-based model to measure API usage. Instead of simply counting requests, each API call consumes points based on the work it performs. Starting March 2, 2026, phased enforcement begins for the new rate limits across Jira and Confluence REST APIs.
• On Data Center, admins can configure rate limits; the default can be, for example, 10 every 1 minute. This severely throttles extraction speed for large instances.
• Macro-to-web-part translation is the hardest part. You need to write custom transformation rules for every macro type your wiki uses.
• Migrating comments could bring pages to the maximum size of ~2 MB (technical limitation of SharePoint); switch comment migration off if you experience errors.
• SharePoint page APIs only support a documented subset of web parts, and canvasLayout updates require the full page layout, not partial patches.

Best for: Engineering teams with 6+ weeks of runway and fewer than 500 pages with simple formatting.

Method 4: Dedicated Third-Party Tools

Three tools dominate this space:

WikiTraccs — WikiTraccs makes migrating content from Atlassian Confluence to SharePoint Online easier. It contains hundreds of transformation rules for a wide range of Confluence formattings, structures and macros. It supports both Confluence Cloud and Data Center, outputs SharePoint Online modern pages, and handles link rewriting, attachment migration, and user mapping. The largest successful WikiTraccs-based migration "in the wild" consisted of ~160 spaces and ~200,000 pages. Note: WikiTraccs migrates all your content to SharePoint Online (not on-prem, though).

Tzunami Deployer — A purpose-built migration tool that supports Confluence-to-SharePoint scenarios. It preserves metadata (titles, created/modified dates, authors), maintains page structure, supports attachments and embedded content, automates permissions mapping, and handles link resolution.

Enterprise Bridge (CaseAgile) — Labels and tags on each page are converted into SharePoint enterprise keywords. Owners and contributors of the spaces, pages and files remain the same after migration. Labels on each page come across when migrated to SharePoint.

When evaluating any tool, ask five direct questions:

• What happens to unsupported macros?
• How are internal page and attachment links rewritten?
• Can the tool run delta/incremental syncs?
• How are restricted pages handled?
• What source metadata can be preserved natively versus stored in custom fields?

Mapping Data: Pages, Macros, and Permissions

Confluence Spaces → SharePoint Sites

The most common mapping is one Confluence space = one SharePoint communication site. For organizations with dozens of spaces, group related sites under a SharePoint hub site to replicate the cross-space navigation that Confluence provides natively. Do not map spaces to legacy SharePoint subsites — Microsoft's modern architecture has moved away from that model.

Confluence Concept	SharePoint Equivalent	Notes
Space	Communication Site or Team Site	One site per space is the cleanest mapping
Space home page	Site home page	Rebuild manually or with a template
Page tree (parent-child)	Site navigation + WikiPakk or custom SPFx	No native equivalent
Labels	Managed Metadata or Enterprise Keywords	Requires term set planning
Blog posts	News posts	Different authoring flow; use promotionKind: newsPost
Space permissions	Site permissions (Entra ID groups)	Re-map from Atlassian accounts
Attachments	Site Assets library	Per-page subfolder recommended
Source author / dates	Custom columns (Source Author, Source Created)	Native createdBy / lastModifiedBy are read-only
Comments	Archive list or appendix block	No native 1:1 page comment replay
Version history	External archive or retained source export	Full history replay is not realistic

If stakeholders ask for categories, translate that carefully. In Confluence that usually means a mix of space, page ancestry, and labels. In SharePoint, model that as metadata. If you recreate it as deep folder trees, you will make navigation, search, and future cleanup harder.

For a deeper breakdown of metadata strategy, see Mastering SharePoint Information Architecture 2026: Content Types, Metadata & Lists.

Confluence Macros → SharePoint Web Parts

This is where most migrations silently lose content. WikiTraccs contains explicit transformation rules for a range of Confluence macros, but also applies generic transformations. Macros are transformed on the fly and ideally replaced by something native to the SharePoint world. If there is no SharePoint way of replacing a Confluence macro, WikiTraccs tries to find an approximation (which is more the norm than the exception). Macros so far unknown to WikiTraccs are also transformed, but in a generic way.

Confluence Macro	SharePoint Equivalent	Migration Approach
Code Block	Code Snippet web part	Near 1:1
Info / Warning / Note / Tip	Text web part with colored background	Approximate (nesting lost)
Expand (accordion)	No native equivalent	Content displayed flat; loses interactivity
Table of Contents	PnP Page Navigator web part	Requires SPFx app
Children Display	WikiPakk Children Display web part or static links	Snapshot or SPFx app
draw.io diagrams	Static image	Editable source file retained as attachment
Jira Issue/Filter	Static table or SharePoint Connector for Jira	Limited — only works for Jira issue lists. Single Jira issues, or other Jira macros (charts) are not supported.
Excerpt / Excerpt Include	Flattened into target page	Cross-page transclusion doesn't exist in SharePoint
Panel / Section / Column	SharePoint page sections	The result of mapping sections and columns to tables may introduce nested tables. Since nested tables are not supported by SharePoint, WikiTraccs will de-nest them.
Status	Colored text or badge	Usually good enough
Content by Label / Report Table	Metadata-driven list view or static snapshot	Not a literal macro port; requires redesign
Page Attachments macro	File Viewer web part or document library link	Static snapshot

Permissions: Confluence Restrictions → SharePoint Permissions

Confluence has two permission layers: space permissions (who can view/edit a space) and page restrictions (who can view/edit a specific page). SharePoint has site permissions (inherited from Entra ID groups) and item-level permissions (which Microsoft discourages at scale — the recommended limit is 5,000 unique permissions per list).

Page restrictions can be migrated to a certain extent, confined to what is technically possible. The WikiTraccs author does not recommend migrating page restrictions. Instead, re-map permissions at the site level using Entra ID security groups, and only apply item-level restrictions where strictly required. Because SharePoint's permission inheritance is managed at the Site, Library, or Item level, replicating Confluence's granular page-level restrictions often means restructuring content into separate Document Libraries.

For detailed guidance on SharePoint permission modeling, see The Definitive Guide to SharePoint Permissions & Security (2026 Edition).

API Limits and Technical Constraints

These are the hard limits that will break your migration if you don't plan for them.

Confluence-Side Constraints

Constraint	Detail
Cloud API rate limits	Confluence Cloud uses a points-based model to measure API usage. Each call consumes points based on complexity; heavy operations consume more. Starting March 2, 2026, phased enforcement begins for the new rate limits. Build exponential backoff and resumable extraction.
Data Center rate limits	Configurable by admin; when automated integrations or scripts send requests in huge bursts, it can affect Confluence's stability. With rate limiting, you can control how many external REST API requests automations can make.
Word export image cap	If a page contains more than 50 images, exporting to Word will create a document with only 50 first images. All extra images will appear as empty boxes. The number is controlled by atlassian.confluence.export.word.max.embedded.images.
Space export timeouts	Massive spaces frequently time out during HTML or PDF generation. Atlassian says a typical export of around 100 pages should generally complete within a few minutes.
Cloud extensions	In Confluence Cloud, Atlassian introduced extensions which cannot be exported, like the Chart extension. Currently the only way to export those seems to print the web page to PDF. Even the Word export doesn't contain those extensions.
Bulk body expansion limits	CQL search with expand=body.storage.value can cap results at 50. Paginate everything and do not assume limit=500 returns 500 rich bodies.

SharePoint-Side Constraints

Constraint	Detail
Page content limit	~2 MB for the CanvasContent1 field. Long pages with embedded comments will fail. Split oversized pages before load.
Bulk upload cap	Bulk upload and move operations encounter two simultaneous limits: 30,000 files maximum or 100 GB total data, whichever threshold is reached first.
URL path length	400 characters is the URL limit allowed for SharePoint. Deep folder nesting or long file names will break.
File upload limit	250 GB — File upload limit. Files up to 250 MB can be uploaded in a single API call; larger files require an upload session.
List view threshold	5,000 items. Libraries with more items work but require indexed columns for views.
No nested web parts	In SharePoint Online, on modern SharePoint pages, you cannot nest web parts. It is technically impossible to put the Code Snippet web part into the Text web part. This is a huge restriction compared to what you can do with Confluence macros.
Blocked characters	Characters like * : < > ? / and backslashes will stop files from uploading. Normalize filenames before upload.
Canvas layout updates	SharePoint page layout updates require the full canvasLayout, not partial patches of one section.
Site storage	25 TB per site collection. Usually not a migration concern unless consolidating many spaces.

Step-by-Step Confluence to SharePoint Migration Process

Step 1: Pre-Migration Audit

Before touching any migration tool:

• Inventory your spaces. Count pages, blog posts, attachments, and total storage per space.
• Identify active macros. Which macros are used and how often? This drives your mapping effort.
• Catalog labels. Decide which labels become managed metadata terms vs. enterprise keywords.
• Revise all outdated, deleted, and internal-use content, so that only the necessary information migrates to SharePoint. Conducting an audit in a familiar environment makes this task easier. Check hidden pages — detect any pages called "archive", "outdated", or similar. Undeleted content may reside there.
• Document page restrictions in a spreadsheet with the planned Entra ID group mapping.

Step 2: Design Your SharePoint Target Architecture

• Map each Confluence space to a SharePoint site.
• Group related sites under hub sites for cross-space navigation.
• Create managed metadata term sets for labels that need to survive.
• Decide on navigation: WikiPakk page tree, custom SPFx, or SharePoint native navigation.
• Pre-create target sites using PnP PowerShell or the SharePoint Admin Center and configure content types.
• Decide what becomes a page, news post, list item, document, or archive record. Not every Confluence page should become a SharePoint page — some content fits better in a document library or a list.

Step 3: Build the Mapping Workbook

Define explicit rules for:

• Page and blog post type mapping (page vs. news post)
• Macro handling rules per macro type
• Label-to-metadata mapping
• Permission mapping (Atlassian groups → Entra ID groups)
• URL rewrite rules (old Confluence URLs → new SharePoint URLs)
• Source metadata columns to preserve (Source Author, Source Created, Source Updated, Source Confluence URL)

This workbook becomes your control plane for QA, redirects, and stakeholder sign-off. Keep it even if you migrate by API.

Step 4: Run a Pilot Migration (One Space)

Pick a representative space — not the cleanest one. Choose a space with mixed content: text, tables, macros, attachments, images, page restrictions, and deeply nested hierarchies.

Validate:

• Page count matches source.
• All attachments are accessible.
• Internal links resolve correctly.
• Macro-heavy pages render acceptably.
• Author/editor metadata is correct (or stored in custom columns).
• Labels/tags transferred as expected.
• No pages exceeded the ~2 MB limit.
• URL paths stay under 400 characters.

Step 5: Execute Full Migration in Batches

Migrate spaces in batches, not all at once. Batch by business unit or content priority.

• Run migration during off-peak hours to minimize SharePoint throttling. Depending on the usage of Microsoft 365 worldwide and the region you are in, the speed of SharePoint-related operations can vary; migrating on a weekend might be faster than during working hours.
• Load in order: Upload attachments and images first, then create pages that reference them, then apply page-level permissions last. This order makes troubleshooting far easier because you don't have broken pages trying to render files that don't exist yet.
• Monitor for failures: pages exceeding the ~2 MB limit, files with unsupported characters in names, and URL paths exceeding 400 characters.

Step 6: Delta Sync and Cutover

Between your initial migration and cutover day, users are still editing Confluence. Run a delta migration to pick up changes since the last run. Use source update timestamps and version numbers to identify late changes. Both WikiTraccs and Tzunami support incremental migrations.

On cutover day:

1. Set Confluence spaces to read-only.
2. Run the final delta sync.
3. Validate counts and spot-check high-traffic pages.
4. Update DNS/redirects if you're maintaining bookmarks.
5. Announce the switch to users.

Step 7: Post-Migration QA and Cleanup

No migration is 100% clean on the first pass. Allocate time for:

• Broken link audit — Search migrated pages for URLs still pointing to *.atlassian.net or your Confluence domain.
• Macro residue — Look for placeholder text where macros failed to transform.
• Image verification — Spot-check image-heavy pages to confirm all inline images render.
• Navigation rebuild — Configure SharePoint site navigation to reflect the old page hierarchy.
• Permission validation — Confirm that restricted content is actually restricted in SharePoint.
• Page count reconciliation — Verify total page and attachment counts match the source per space.
• Search testing — Confirm key content is discoverable through SharePoint search.
• Duplicate detection — Check for duplicates caused by title or slug changes during migration.

Post-Migration: Fixing Broken Links and Formatting

Broken links are the #1 post-migration complaint. There are three categories:

1. Internal wiki links (Confluence page → Confluence page)

Tools like WikiTraccs handle this automatically. Will links keep working after migrating from Confluence to SharePoint? Yes. WikiTraccs takes care of this. If you used custom API scripts, you need to build a URL mapping table and do a find-and-replace pass across all migrated page content. Confluence internal links look like /display/SPACE/Page+Title; these must be rewritten to their SharePoint destinations (e.g., /sites/SiteName/SitePages/Page-Title.aspx).

2. Hard links (raw HTTP URLs to Confluence)

Hard links are plain old HTML links that Confluence is oblivious of, from a metadata standpoint. These are harder to detect and rewrite because the migration tool has no metadata about their target. A post-migration script scanning for your old Confluence domain in page content is the only reliable fix.

3. External links pointing IN to Confluence

Bookmarks, emails, third-party docs, and search engine indexes still point to your old Confluence URLs. Set up HTTP 301 redirects from your Confluence domain to the corresponding SharePoint pages. If you're on Confluence Cloud and don't control the domain, you cannot set up redirects — communicate the URL change to users instead.

Formatting issues to watch for:

• Pages in Confluence are much wider than SharePoint modern pages. Wide tables or multi-column layouts will compress or reflow.
• Nested tables are de-nested (content is preserved but layout changes).
• Color-coded text may lose precision — SharePoint has a smaller color palette.
• Inline mentions become links to search results rather than interactive @mentions.
• SharePoint does not support deeply nested tables the same way Confluence does. Complex tables may need to be converted into SharePoint Lists.

What This Migration Gets You (and What It Doesn't)

Be honest with stakeholders about these trade-offs before starting.

What you gain:

• Unified platform — one Microsoft 365 tenant for docs, communication, and wiki content.
• Copilot and AI features across your knowledge base.
• Entra ID-based identity management instead of separate Atlassian accounts.
• Reduced licensing costs if you're already paying for Microsoft 365.

What you lose (or must rebuild):

• Native page tree navigation. SharePoint doesn't have this without third-party SPFx solutions.
• Interactive macros. Most become static content.
• Confluence-specific integrations (Jira deep links, Confluence-native automations).
• The editing experience. SharePoint's page editor is more constrained than Confluence's.
• Full version history. Confluence version history doesn't transfer natively.

The migration is technically achievable, but the destination platform behaves differently — and users will need to adapt.

When to Bring in a Migration Partner

Self-service tools work well for organizations with fewer than 100 spaces, standard macros (no heavy marketplace add-on usage), internal engineering capacity to run and validate the migration, and tolerance for some post-migration cleanup.

But the complexity scales non-linearly. If your migration has three or more of these traits, it's no longer a content copy project:

• Macro-heavy pages with marketplace add-ons
• Page-level restrictions that must be preserved
• Public or widely shared external links
• Large attachment volumes
• Hard cutover deadline with zero tolerance for downtime
• Strict compliance requirements for metadata preservation
• No appetite for manual cleanup

At ClonePartner, we treat Confluence-to-SharePoint moves as an ETL problem plus a content-design problem. We build custom extraction engines that pull pages, blogs, attachments, and nested macro content directly via the API, parse the proprietary storage format, rewrite all internal links, and map your specific macro inventory to SharePoint web parts — all with zero downtime.

The decision is straightforward: if you can tolerate manual rebuilding and some data loss, keep it lightweight. If you need clean macro handling, permission mapping, URL rewriting, and zero-downtime cutover discipline, engineer it properly or bring in a team that already has.