How to Migrate from Notion to Confluence

Teams migrate from Notion to Confluence for different reasons — Atlassian ecosystem consolidation, enterprise SSO requirements, tighter Jira integration, or simply an organizational decision after a company merger. Whatever the reason, the migration path is more practical than it looks.

Notion exports your content as markdown (or HTML). Confluence can import markdown. The gap between those two facts is what this guide covers: what the export gives you, what needs cleanup, and how to get everything into Confluence cleanly.

Step 1 — Export Your Notion Workspace to Markdown

In Notion:

Open Settings & Members → Settings
Click Export all workspace content
Choose Markdown & CSV as the export format
Enable Include subpages and Create folders for subpages
Click Export and download the ZIP

The export produces a ZIP with:

One .md file per Notion page
Subpages nested in folders matching the page hierarchy
Images saved as local files (usually in a folder alongside each page)
Database tables exported as .csv files

Step 2 — Understand What Transfers Well and What Doesn't

Transfers cleanly:

Text content, headings, paragraphs
Bold, italic, inline code
Bulleted and numbered lists
Code blocks with language tags
Images (as embedded files)
Basic tables

Needs manual attention:

Notion databases — exported as CSV, not as Confluence pages. Plan to recreate these as Confluence tables or use a Jira integration for structured data
Toggle blocks — exported as regular text; the expand/collapse behavior is lost
Notion-specific embeds (YouTube, Figma, etc.) — exported as plain URLs, not embedded. You'll need to re-embed them in Confluence
Linked databases and relations — not preserved in markdown export
Comments and mentions — not included in the export

For a large workspace, do a test export and import of a small section first to understand what the output looks like for your specific content before committing to a full migration.

Step 3 — Clean Up the Exported Markdown

Before importing, a few cleanup steps save time:

Remove Notion IDs from filenames. Notion appends a unique ID to every file and folder name (e.g., Engineering Wiki a3f2c1b4d5e6.md). You can strip these with a script or a bulk rename tool. The Markdown Importer uses the filename as the Confluence page title, so cleaner names give you cleaner page titles.

# macOS/Linux — remove Notion IDs from .md filenames
for f in *.md; do
  newname=$(echo "$f" | sed 's/ [a-f0-9]\{32\}\.md$/.md/')
  [ "$f" != "$newname" ] && mv "$f" "$newname"
done

Convert CSV databases to markdown tables. For Notion databases that you want in Confluence as pages (not Jira issues), convert the CSV to a markdown table:

# Quick CSV to markdown table conversion (Python)
python3 -c "
import csv, sys
rows = list(csv.reader(open(sys.argv[1])))
print('| ' + ' | '.join(rows[0]) + ' |')
print('| ' + ' | '.join(['---'] * len(rows[0])) + ' |')
for row in rows[1:]:
    print('| ' + ' | '.join(row) + ' |')
" your-database.csv

Organize the folder structure. Notion's export mirrors its page hierarchy as nested folders. Review the structure and reorganize if needed — the folder structure becomes the Confluence page hierarchy.

Step 4 — Import into Confluence

Install Markdown Importer for Confluence from the Atlassian Marketplace.

For a small migration (up to 20–30 pages):

Open the target Confluence page (where the imported pages should live)
Click ••• → Markdown Importer & Exporter
Select your cleaned-up markdown files or the ZIP archive
Enable Page Hierarchy to preserve folder structure as Confluence parent/child pages
Click Import

For a large migration:

Use the ZIP upload option. Zip your cleaned-up Notion export folder (after stripping IDs and reorganizing) and upload it as a single archive. The importer processes the entire folder tree and creates the Confluence page hierarchy in one operation.

If you're migrating multiple Notion workspaces or sections to different Confluence spaces, you can target different parent pages and spaces in separate import operations.

Step 5 — Handle Images

Notion's markdown export embeds images as relative file paths:

![Screenshot](./Screenshot_2025-03-14.png)

Markdown Importer reads the ZIP archive and uploads images as Confluence attachments, replacing the relative paths with Confluence attachment references automatically. This works when you import via ZIP — the images need to be inside the ZIP alongside the markdown files.

If you're importing individual .md files without a ZIP, images won't transfer automatically — you'll need to upload them to Confluence and update the image references manually.

Step 6 — Post-Import Cleanup

After the import, walk through the imported pages:

Check page titles. The importer uses filenames as titles. If you missed some Notion IDs in the cleanup step, some pages will have IDs in their titles — rename them in Confluence.

Re-embed external content. Notion embeds for YouTube, Figma, Loom, or other services come through as plain URLs. Add Confluence macros or HTML Macro embeds to restore the embedded experience where it matters.

Review tables. Notion tables with select, multi-select, or date columns export as text — the structured data type is lost. Verify these look reasonable in Confluence or recreate them using Confluence's table macro.

Update internal links. Links between Notion pages are relative paths in the export and may not resolve correctly after import. Run a search in Confluence for notion.so URLs to find any that were hardcoded, and update them to Confluence page links.

What to Expect at Scale

For a workspace with 200–500 pages, the full migration — export, cleanup, import — typically takes a day of dedicated effort. Larger workspaces benefit from dividing the work by Notion workspace section and importing incrementally rather than all at once.

The most time-consuming part is usually the post-import cleanup: reviewing imported pages, fixing database content, and re-embedding media. Budget more time for this than for the import itself.

Install Markdown Importer for Confluence →

Read the documentation →

Featured App