
How to Migrate from Notion to Confluence
Short answer: Export the Notion pages as Markdown & CSV with Include subpages on. That gives a ZIP of .md files, image folders and CSV files for databases. Clean up what doesn't transfer, then upload the ZIP to a Markdown importer such as Markdown Importer for Confluence. Folders become a Confluence page tree; Notion databases need to be rebuilt as tables or moved to Jira.
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 Content to Markdown
For a page or section (and everything under it):
- Open the top-level page in Notion and click the ••• menu (top right)
- Select Export
- Choose Markdown & CSV as the format
- Turn on Include subpages (and keep Create folders for subpages on so the hierarchy is kept as folders)
- Click Export and download the ZIP
For a whole workspace, workspace owners can use Settings, then General, then Export all workspace content. Notion emails a download link when the export is ready, which can take a while for large workspaces. Menu names change from time to time, so check Notion's export help page if yours look different.
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, so 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 usually appends a long ID to file and folder names (e.g., Engineering Wiki 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.md). Strip these with a script or a bulk rename tool before importing, so the IDs don't carry over into page titles. Clean names also help with Confluence's rule that page titles must be unique within a space.
# macOS/Linux: remove Notion IDs from .md filenames in the current folder
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, because the folder structure becomes the Confluence page hierarchy. If you rename folders, update the relative image paths that point into them.
Step 4: Import into Confluence
Install Markdown Importer for Confluence from the Atlassian Marketplace.
For a small migration (a few dozen pages):
- Open the target Confluence page (where the imported pages should live)
- Click ••• (More actions) and select Markdown Importer & Exporter
- Select your cleaned-up markdown files or the ZIP archive
- Keep the folder structure as page hierarchy so folders become parent/child pages
- Preview the result and check any conflicts the importer flags
- 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. The bulk import guide covers preparing a large ZIP in more detail.
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. From the global Apps menu you can also choose one or several target spaces.
Step 5: Handle Images
Notion's markdown export embeds images as relative file paths:

Markdown Importer uploads local images referenced by your Markdown as Confluence attachments and updates the references automatically. Remote images (full URLs) work too.
Importing the export as a ZIP is the most reliable route for a Notion migration, because the images stay at the relative paths the Markdown expects. Whichever way you import, make sure every referenced image is included. A missing file is the most common reason for a broken image after import.
Step 6: Post-Import Cleanup
After the import, walk through the imported pages:
Check page titles. If you missed some Notion IDs in the cleanup step, they may show up in page titles. Rename those pages 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, so 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 relative links between Markdown files may not always resolve to the right Confluence page 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 a few hundred pages, plan on at least a day of dedicated effort for the full migration (export, cleanup and import). 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.
If you are weighing the two tools before you move, see Confluence vs Notion for engineering teams.
Get Markdown Importer for Confluence on the Atlassian Marketplace


