Notion's Markdown Export Quirks (and How to Fix Them)

Notion has had a "Export as Markdown & CSV" option for years, and on the surface it works fine — pages come out as .md files, databases as .csv. The trouble starts when you actually try to use the output: pipe it into Obsidian, feed it to an LLM, or commit it to a docs repo. Several Notion block types don't have a clean Markdown equivalent, and Notion's export quietly degrades them rather than failing loudly.

Below are the quirks that break the most pipelines, and what to do about each.

Toggle blocks flatten

A toggle in Notion is a collapsible section — heading on top, hidden content underneath. Markdown has no native equivalent, so Notion exports the toggle title as a paragraph, followed by the toggle's contents as more paragraphs at the same indentation level.

The structural relationship is gone. If your Obsidian vault relies on collapsibility, or your RAG chunker uses heading hierarchy to bound a chunk, the toggle's contents bleed into whatever follows it.

Fix: wrap toggle contents in an HTML <details> block manually, or skip toggles in your information architecture if you plan to export regularly.

Callouts become quote blocks with an emoji

Notion's callout block — the boxed paragraph with a coloured background and an icon — exports as a Markdown blockquote with the icon emoji prepended to the first line. Color and "callout" semantics are lost; downstream renderers see only a quote.

For human reading this is mostly fine. For LLMs and search indexing it's worse: an "info" callout that says "this is the production endpoint" looks identical to a quoted Slack message, and the model has no way to tell which was meant as emphasis.

Synced blocks duplicate content

Synced blocks let one piece of content appear on multiple pages. The export resolves each instance independently and writes the content into every file that references it.

For a docs repo this is annoying. For embeddings it's worse — you index the same paragraph N times, inflate token cost, and pollute retrieval with near-identical matches.

Fix: before exporting, identify your synced blocks and decide whether each one should become a "canonical page + transclusion" or just live in one place. Notion will not do this for you.

Equations and embeds turn into plain text

KaTeX-style equation blocks export as their raw LaTeX source, with no fenced code block to signal what it is. Embed blocks (Figma, YouTube, Loom) export as a bare URL on a line by itself.

If your downstream tool understands neither, you lose the visual content entirely. Obsidian renders Figma URLs as plain links; an LLM ingesting the export sees \frac{a}{b} as a string, not a formula.

Image paths reference the ZIP root

When you export a workspace as Markdown, Notion ships you a ZIP with the .md files and an attachments folder. Image references in the Markdown are relative paths into that folder. The moment you copy a single .md file out of the ZIP — into Obsidian, into a git repo, into anywhere — the images break.

Fix: always export the full ZIP, never a single page. If you only need one page, extract the ZIP, find the matching attachments folder, and copy both together.

Wiki links and @-mentions get stripped

Notion's @page mentions and inline page links export as Markdown links to the page's exported .md filename — which Notion generates from the page title plus a UUID. The links work inside the exported ZIP, but the moment a title changes or you reorganise files, every cross-reference rots.

A cleaner workflow

If the destination is Obsidian, the safest path is to export the full ZIP, drop it into your vault, and run a one-time pass to rewrite callouts and toggles. See our Apple Notes guide for a similar paste-and-clean workflow on iOS.

If the destination is a RAG pipeline or an LLM context window, the export's losses compound: you index degraded content, then your model retrieves the degraded chunks. In that case it's worth a second pass — either through a converter that normalises the quirks, or by re-exporting individual pages as PDF and converting through our PDF to Markdown pipeline, which preserves heading structure and table cells more reliably than Notion's own Markdown writer.

For more on why the Markdown shape matters at all for AI tools, see why Markdown matters for LLMs.

Notion's export is a starting point, not a finished artifact. Treat it like the first stage of an ETL job, not the output.