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
.mdfile 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
.csvfiles
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 "
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:
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.
Top comments (0)