How to Migrate from Confluence to Modern Documentation Platforms

Most engineering teams don't leave Confluence because the product is broken. They leave because the search is slow, the editor feels like a 2010 CMS, the page tree has 14 levels of nested spaces, and half the content is rotting in a "Team X Archive" nobody opens. The moment a faster, cleaner alternative shows up, the question stops being whether to migrate and becomes how to migrate without losing a year of institutional knowledge.

This guide walks through that process: the tools, the order of operations, the failure modes, and the parts Confluence vendors conveniently leave out of their sales pitch.

Why Teams Are Leaving Confluence

Confluence earned its seat at the table by being the first reasonable wiki for the enterprise. But the reasons engineers are actively migrating in 2025 cluster into a few buckets:

• Search and navigation collapse at scale. Once a workspace crosses a few thousand pages, the built-in search becomes the bottleneck of onboarding. New hires can't find runbooks that exist. Senior engineers stop writing because nobody reads them.
• Editor friction. Pages render slowly, macros break across versions, and pasting anything from a terminal into the editor produces a formatting mess. Markdown-first platforms win on this axis decisively.
• Permissions sprawl. Space-level permissions, page-level restrictions, and group inheritance make "who can see this" a question you cannot answer without an admin. Modern platforms flatten this.
• Cost per seat. Confluence Cloud pricing scales linearly with users, which gets painful when you want the whole company (PMs, support, sales engineers) to read but not edit.
• CI/CD expectations. Engineering orgs expect docs that live next to the code, auto-generate from OpenAPI specs, and update via webhooks. Confluence does none of this natively.

None of these are dealbreakers in isolation. Together, they make migration an active backlog item instead of a hypothetical.

Pre-Migration: Audit Before You Move

The single biggest mistake in Confluence migrations is treating it as a copy operation. It isn't. You are doing three things at once: extracting content, classifying it, and deciding what survives. Do the audit first.

Inventory your spaces

Pull a list of every space and count pages, attachments, and last-modified dates. Most teams discover that 30–50% of their pages haven't been edited in over a year. Those are candidates for archive, not migration.

# Using the Confluence REST API
curl -u "email:api_token" \
  "https://your-domain.atlassian.net/wiki/api/v2/spaces?limit=250" \
  | jq '.results[] | {id, key, name, status}'

Classify content

Tag every space with one of four labels:

Label	Action	Example
Keep	Migrate as-is	API reference, onboarding docs
Rewrite	Migrate stub, rewrite at destination	Architecture overviews, RFCs
Archive	Export, do not import	Resolved post-mortems, old projects
Delete	Don't bother exporting	Empty spaces, draft experiments

This step is where you save weeks of work. A 4,000-page Confluence instance might shrink to 600 pages that actually need to land in the new platform.

Map permissions and ownership

Capture who owns what space, which groups have access, and which pages have explicit restrictions. Modern docs tools have different permission primitives (usually workspace + collection, or workspace + page), so you'll need a translation table.

Choosing a Migration Tool

The migration tooling landscape splits into three categories. Pick based on volume, custom content, and how much engineering time you want to spend.

1. Native importers

Platforms like Notion, GitBook, and most modern wikis ship Confluence importers. These handle pages, attachments, and basic formatting reasonably well.

• Pros: Zero setup, handles the basics (headings, tables, code blocks, images), preserves page hierarchy.
• Cons: Macros (Info, Note, expand, status lozenges) often render as raw HTML or get stripped. Page restrictions and space permissions may not transfer cleanly. Custom user mentions break.
• Best for: Small to medium workspaces (under 1,000 pages) with mostly prose.

2. Dedicated migration tools

Products like Confluence Cloud Migration Assistant (Atlassian's own, but it migrates to Atlassian), CloudFuze, Litera, and open-source scripts on GitHub target Confluence specifically.

• Pros: Handle edge cases like macros and version history. Some preserve attachments and comments.
• Cons: Pricing per GB or per page adds up fast. Vendor lock-in to their data model.
• Best for: Mid-market migrations where you need compliance and audit trails.

3. Custom scripts using the REST API

For engineering teams that want full control, the Confluence REST API exports to HTML or storage format, which you can transform and import on your terms.

import requests
from requests.auth import HTTPBasicAuth

auth = HTTPBasicAuth('email', 'api_token')
base = 'https://your-domain.atlassian.net/wiki'

def fetch_pages(space_key, limit=25):
    url = f"{base}/rest/api/content/search"
    params = {
        'cql': f'space={space_key} and type=page',
        'limit': limit,
        'expand': 'body.storage,version,ancestors'
    }
    r = requests.get(url, auth=auth, params=params)
    return r.json()['results']

• Pros: Total control over transformation, can rewrite content during migration, can pipe directly into Markdown or MDX.
• Cons: You own the script. Macro conversion is a project of its own. Expect 2–4 weeks of engineering time for a non-trivial instance.
• Best for: Engineering orgs migrating to Markdown-based platforms with non-standard content.

Quick comparison

Approach	Setup time	Cost	Macro handling	Best fit
Native importer	Hours	Free	Poor	<1k pages, prose
Dedicated tool	Days	$$	Good	1k–10k pages
Custom script	Weeks	Engineering time	Custom	10k+ pages, complex

The Migration Pipeline

Once you've picked a tool, the actual migration follows the same shape regardless of destination.

Step 1: Export

Use the Confluence export to HTML or XML. For incremental migrations, the REST API is your friend. Pull pages in batches with start cursors and respect rate limits (typically 5,000 requests per hour per token for Cloud).

Step 2: Transform

Convert storage format to your target. If you're going Markdown, the body.storage field is closer to HTML than Markdown; most teams run HTML→Markdown with a tool like turndown (Node) or markdownify (Python).

const TurndownService = require('turndown');
const turndown = new TurndownService({ headingStyle: 'atx' });

// Custom rule for Confluence code blocks
turndown.addRule('confluenceCodeBlock', {
  filter: node =>
    node.nodeName === 'DIV' &&
    node.classList.contains('code-block'),
  replacement: (content, node) => {
    const lang = node.getAttribute('data-language') || '';
    return `\n\n\`\`\`${lang}\n${content}\n\`\`\`\n\n`;
  }
});

const markdown = turndown.turndown(htmlContent);

Step 3: Resolve links and attachments

Confluence internal links break the moment they leave the platform. Map them:

• /wiki/spaces/ENG/pages/123456/Foo → /engineering/foo
• Download all attachments, upload to new platform's asset store, rewrite src attributes.

If you skip this step, your new docs will be a graveyard of 404s. It's the most common reason "migrations look done but nobody can find anything."

Step 4: Import in waves

Don't migrate everything at once. Ship in cohorts:

1. Pilot: One team, one space, internal-only docs.
2. Wave 1: Public-facing API reference and onboarding.
3. Wave 2: Internal engineering runbooks.
4. Wave 3: Long-tail spaces, archived content, PM/Design wikis.

Keep Confluence read-only during the cutover. Most platforms support an alias redirect, so old bookmarks land on the new location instead of 404ing.

Pitfalls That Bite Every Team

A few failures are universal enough to flag explicitly.

• Version history loss. Most importers ignore it. If your org relies on audit trails (regulated industries, legal docs), confirm the destination preserves history or export it as XML for archival.
• Comment threading. Comments rarely survive migration intact. Export them as a CSV alongside the page content if they matter.
• User mentions. @username becomes literal text. Map to the new platform's user directory during transform.
• Macros. The Info panel, the expand block, the status lozenge, the page properties report. Each needs a custom transformation rule. Budget a week.
• Attachments over 100 MB. Confluence silently allows these; some destinations do not. Audit attachment sizes early.
• Permissions drift. A page with restrictions in Confluence might import as world-readable in the new system. Run a permissions diff post-migration.

Validating the Migration

Before flipping the DNS or closing the old instance, run these checks:

• Link checker. Crawl every imported page, confirm no broken internal links.
• 404 audit. Compare server logs from the new platform against expected traffic from the old.
• Permission matrix. Verify that restricted pages are still restricted.
• Search parity. Pick 20 queries engineers actually use (runbook names, service names, error strings) and confirm the new platform returns the same pages.
• Sample user test. Have three engineers who never saw the migration docs find a specific page. Time them. If it's slower than Confluence, the migration failed even if every file moved.

When Not to Migrate

A short reality check. Migration is the right call when:

• Your docs are read more than they're written.
• Search is your primary bottleneck.
• You have a clear destination that fits your team's workflow.

Migration is the wrong call when:

• The real problem is that nobody writes docs. New platform won't fix that.
• You haven't done the audit. You'll just move the rot.
• Your org uses Confluence for project tracking, decision logs, and meeting notes — none of which a docs platform does well. Keep those where they are.

What Comes After the Migration

The hardest part isn't the cutover. It's the six months after, when the old Confluence URL still shows up in muscle memory and Slack links.

Run a redirect for at least 90 days. Add a banner to old pages ("This space is archived, find current docs at…"). Make the new platform's URL the canonical one in onboarding docs. And turn off Confluence write access the day you ship — read-only is your friend during the transition.

---

If your team is migrating from Confluence to a documentation platform that lives next to your code, DocPilot handles the heavy lifting on the destination side. It connects to GitHub, generates READMEs, setup guides, architecture docs, and API references from your repos, and keeps them in sync via webhooks the moment you merge a PR. Free tier available, no credit card to try it. Worth a look once your migration plan is in motion.