Notion export is broken. Not slightly imperfect, not "needs some cleanup." It is fundamentally broken for anyone who expects their content to arrive on the other side looking the way it does inside Notion. Callout blocks export as raw HTML. Databases export as CSV files that lose every view, filter, relation, and rollup you configured. Images land in separate folders with broken references. Nested pages produce filenames stuffed with 32-character UUIDs that exceed Windows path limits.
If you have ever tried to export a Notion workspace and bring it into another tool, you already know the pain. This post documents exactly what breaks, why it breaks, and what you can do about it.
Why Notion export is broken: what fails when you export
Notion's built-in export gives you two primary options: Markdown & CSV, or HTML. Neither produces clean, usable output. Here is a breakdown of the most common failures.
Callout blocks become raw HTML. Notion's callout blocks are a popular formatting feature. People use them for warnings, tips, highlights, and notes. When you export to markdown, these blocks export as raw HTML <aside> tags with inline styles. Most markdown renderers ignore them entirely, so your carefully formatted callouts either display as unstyled HTML or disappear.
Databases export as CSV, not markdown. This is the single biggest complaint in the Notion export community. Your database is not just rows of data. It is views, filters, sorts, relations, rollups, formulas, and custom properties. CSV preserves none of that. You get flat rows with column headers. Every relational link, every rollup calculation, every filtered view is gone. There is a $5,000 bounty on the Obsidian Importer GitHub repository (issue #421) specifically for someone to build proper database import from Notion. That bounty has been open for over two years.
Images break in multiple ways. Notion stores images on its own CDN. When you export, images download into separate subfolders alongside each page's markdown file. The references in the markdown point to relative paths that assume a specific folder structure. Move one folder, rename one directory, and every image link breaks. Some users report images exporting at lower resolution than the originals. Others find that images embedded from external URLs are not downloaded at all, leaving dead links in the export.
Nested pages create impossibly long filenames. Notion appends a 32-character hexadecimal ID to every exported file. A page called "Q4 2025 Marketing Plan" becomes Q4 2025 Marketing Plan abc123def456789012345678abcdef01.md. Nest that page three levels deep inside other pages, and the full file path can exceed 260 characters. On Windows, that means the file silently fails to extract from the zip. On macOS and Linux you might not notice until you try to sync the folder to a Windows machine or a cloud storage service with path limits.
Tables lose rich content. If your Notion table cells contain images, checkboxes, or nested lists, the export strips them. You get plain text in pipe-delimited markdown tables. The structure is technically correct, but the content inside each cell is flattened. This is part of a broader pattern where AI and productivity tool outputs lose formatting on transfer.
Toggle blocks, code blocks, and dividers can break. Toggle blocks (Notion's collapsible sections) export as summary/details HTML tags, which most markdown renderers do not support. Code blocks sometimes lose their language identifiers. Dividers may export inconsistently depending on where they sit relative to other blocks.
Bold, italic, and colored text can be lost. Notion supports colored text and background highlights. Markdown does not have a native syntax for either. On export, colored text becomes plain text. Background highlights vanish. Bold and italic usually survive, but users have reported cases where inline formatting is stripped from complex block structures.
Large exports freeze the desktop app. Multiple users have reported that exporting workspaces with more than a few hundred pages causes the Notion desktop app to hang or crash. The workaround is to use the web version or break the export into smaller chunks. Neither is a good experience when you are trying to leave a platform.
Why Notion export fails at the markdown level
The core problem is that Notion is not a markdown tool. It is a block-based editor with a rich internal data model that includes databases, embeds, toggles, callouts, synced blocks, and dozens of other features that have no direct markdown equivalent.
When you ask Notion to export as markdown, it has to translate its proprietary block format into a format that was designed in 2004 for writing blog posts. Markdown has headings, bold, italic, links, images, lists, code blocks, blockquotes, and tables. That is roughly the full inventory. Everything else in Notion either gets converted to raw HTML (callouts, toggles), dumped to CSV (databases), or silently dropped (colors, synced blocks, embeds).
This is not a bug that Notion will fix with a patch. It is a structural mismatch between what Notion can represent and what markdown can represent. The export will always be lossy because the source is richer than the target format. Understanding what markdown publishing actually is helps clarify why the format itself is both the limitation and the solution.
How to fix common Notion export problems
Despite the limitations, there are practical steps you can take to get better results from a Notion export.
Clean up callout blocks before exporting. If your callouts contain critical information, convert them to blockquotes or plain paragraphs before you export. Blockquotes have native markdown syntax (>) and survive the export cleanly. You lose the colored icons, but you keep the content.
Export databases separately as CSV, then rebuild. Accept that database exports will be flat CSV files. Export them, then import the CSV into whatever tool you are migrating to. For Obsidian users, this means creating individual notes from each row using a script or the Obsidian Importer plugin. For other tools, look for CSV import features.
Fix image paths with a script. After exporting, the images are in the zip file. The references are relative. A simple find-and-replace script can normalize the paths. Python, Node.js, or even a bash one-liner can walk the exported directory tree, find all image references in the markdown files, and update them to match your target folder structure.
Strip UUIDs from filenames. Every exported file has a 32-character ID appended. A rename script can strip these. On macOS or Linux:
find . -name "*.md" | while read f; do
newname=$(echo "$f" | sed 's/ [a-f0-9]\{32\}\.md$/.md/')
mv "$f" "$newname"
done
After renaming, you will also need to update any internal links that reference the old filenames with IDs.
Break large exports into smaller chunks. If the desktop app freezes, switch to the Notion web app and export individual sections or databases rather than the entire workspace. This is slower but more reliable.
Third-party tools that help with Notion export
The community has built several tools specifically to fix Notion's export problems.
Obsidian Notion Importer. This is a community plugin for Obsidian that reads Notion export zips and converts them into Obsidian-compatible vault files. It handles some of the filename cleanup and link restructuring automatically. It does not solve the database problem (still CSV), but it significantly reduces manual work for everything else.
notion-export-markdown (Dwarves Foundation). A Node.js tool on GitHub that post-processes Notion exports. It strips UUIDs from filenames, fixes internal links, cleans up image paths, and converts some HTML blocks back to markdown. It is open source and actively maintained.
n2o (Notion to Obsidian). Another community conversion tool focused specifically on the Notion-to-Obsidian pipeline. It handles internal links, property frontmatter, and file naming conventions.
confluence-to-markdown and similar converters. If you are not moving to Obsidian specifically, generic HTML-to-markdown converters can help. Since Notion also exports as HTML, you can take the HTML export and run it through a conversion tool like Turndown, Pandoc, or the reverse conversion approach detailed in our HTML to markdown guide. The HTML export preserves more formatting than the markdown export, paradoxically, because the HTML can represent more of Notion's block types.
The alternative approach: stop exporting, start publishing
Here is a different way to think about the problem. If your goal is to get your content out of Notion and into a format that looks good in Google Docs, Word, Slack, email, or on the web, you do not necessarily need a perfect Notion export. You need a publishing layer that can take markdown and deliver it to its destination in the right format.
The workflow looks like this: export what you can from Notion (even with its imperfections), clean it up to standard markdown, and then use a tool like Unmarkdown™ to publish it wherever it needs to go. Unmarkdown™ takes markdown and converts it to properly formatted output for Google Docs, Word, Slack, email, or the web. The markdown does not need to be perfect. It needs to be structurally correct: headings, paragraphs, lists, links, images, code blocks.
For ongoing work, the smarter move might be to write in markdown from the start. Tools like Unmarkdown™ let you write or paste markdown, style it with professional templates, and publish to any destination. You skip the export problem entirely because your content is already in the most portable format available.
The fundamental lesson of Notion export is this: proprietary formats lock you in, even when the vendor provides an export button. Markdown is not perfect, but it is the one format that every tool in the ecosystem can read without losing your content. The closer your writing workflow stays to plain markdown, the less time you will spend fighting export problems when it is time to move.
When Notion export is good enough
To be fair, Notion export works fine for simple content. If your workspace is mostly text pages with headings, lists, and basic formatting, the markdown export will be clean and usable. The problems appear when you use Notion's more advanced features: databases, callouts, toggles, embeds, colors, and deep nesting.
If you are evaluating whether to export, open a few representative pages from your workspace, export them individually, and inspect the output. If the markdown looks acceptable, your full export will probably be fine. If those sample pages are messy, multiply that mess by every page in your workspace.
For teams sitting on large Notion workspaces with hundreds of database-heavy pages, the honest answer is that no tool, including Notion itself, provides a clean automated export. The migration will require manual effort. The question is how much, and which tools can reduce it.
