Guide · Updated May 2026

How to migrate from Notion to Markdown.

You've decided you want your notes on your own disk in plain Markdown. Notion makes the export easier than it used to be — but the export has gotchas, and the next 30 minutes after extracting the .zip determine whether your migrated vault is genuinely useful or a folder you'll never open. Here's the complete walkthrough.

What you'll lose going in.

Set expectations honestly. The export converts most things but flattens a few:

• Databases → CSV files. Rollups, formulas, linked-database views: gone. You get a snapshot.
• Synced blocks → duplicated content in each location. The link is broken.
• Embedded pages → links to other files in the export folder, which mostly work but break for deeply-nested pages.
• Toggle blocks → flat Markdown headings with the body inline (no longer collapsible).
• Notion-hosted file uploads → relative path references that point to the export's assets/ folder. Keep that folder next to your Markdown files.
• Comments → gone.
• Page hierarchies → flattened into folder paths reflecting the original page tree.

What survives: the actual text of every page, headings, lists, links, code blocks, images, and the rough hierarchy.

Step 1: trigger the export.

1. Open Notion on desktop (not the web app — the desktop app handles larger exports better).
2. Settings & members → Settings → Export content.
3. Choose Export format: Markdown & CSV.
4. Toggle "Include subpages" ON.
5. Toggle "Create folders for subpages" ON. This preserves your page hierarchy as a folder tree.
6. Click Export. Notion emails you when the .zip is ready — usually within minutes, up to an hour for large workspaces.

Step 2: unzip into a vault folder.

Pick a permanent home for the vault. We recommend ~/Documents/Notes/ or somewhere in iCloud Drive if you want cross-device sync.

cd ~/Documents
mkdir Notes
cd Notes
unzip ~/Downloads/Export-*.zip

You'll see your page hierarchy as a folder tree. Each page is now a .md file, with subpages as files inside a folder named after the parent.

Step 3: clean up the export artifacts.

The fastest 15-minute cleanup pass:

3a. Strip Notion's UUID suffixes from filenames.

Notion exports filenames like My Page Title abc123def456.md. The 32-char hex suffix is the page UUID. You almost certainly want it gone.

cd ~/Documents/Notes
find . -type f -name "* [0-9a-f]*" | while read f; do
  newname=$(echo "$f" | sed -E 's/ [0-9a-f]{32}//')
  mv "$f" "$newname"
done

Test on a copy first if you're nervous. (And: do the same for folders, which also have UUIDs.)

3b. Move images to a consistent folder.

Notion scatters image uploads next to each Markdown file in a sibling folder. If you'd rather have one assets/ folder at the vault root, you can consolidate — but most editors handle the relative paths fine, so this is optional.

3c. Fix internal links.

Notion's exported Markdown links look like [Page Title](Page%20Title%20uuid/Page%20Title%20uuid.md). After stripping UUIDs, you'll need to fix the link targets too:

find . -type f -name "*.md" -exec sed -i '' -E \
  's/(\([^)]*) [0-9a-f]{32}/\1/g' {} \;

This removes UUIDs from the parenthesized link targets too. (Macs require the empty '' argument to sed.)

3d. Decide what to do with database CSVs.

Each Notion database becomes a CSV in the export folder. Three options:

• Keep the CSV if the data is one-shot — you don't need it to update anymore.
• Convert to Markdown table if it's small and readable. csvjson | mlr can help here.
• Re-create in Eyrie as Markdown with frontmatter properties on each note. Slower but recovers most of the original database semantics.

Step 4: open in Eyrie (or your editor of choice).

Open the folder. Eyrie indexes everything in seconds. Wikilinks light up. Tags appear in the sidebar. Smart Categories auto-classify the migrated notes (give them a few minutes to process if AI categorization is on).

You can also use Obsidian, iA Writer, Logseq, or any other Markdown editor — the cleaned-up vault is portable.

Step 5: decide what to delete in Notion.

Don't cancel your Notion subscription the same day you migrate. Run both for two weeks:

• Use the new Eyrie vault for daily writing.
• If you find Notion features you can't live without, you'll know within 14 days.
• If the migration feels complete, downgrade Notion to free, archive the workspace, and stop paying.

Notion retains exported data per their privacy policy for some retention period — don't delete the workspace until you're 100% sure the local vault has everything.

Gotchas nobody warns you about.

• Synced blocks duplicate. If you used Notion's "synced block" feature, every place that referenced it now has its own copy. Search for duplicate paragraphs and clean up.
• Color-coded blocks lose color. Markdown is plain text. Notion's colored callouts become regular blockquotes.
• Cover images for pages are NOT exported. Some metadata loss.
• Drag-and-drop attachments live next to their host page, which means many small assets/ folders. Annoying but works.
• The export is a snapshot. If you write more in Notion after exporting, that's not in your migrated vault. Plan the cutover carefully.