Convert Notion Export to Clean Markdown

What is a Notion-to-Markdown conversion?

Notion is the most popular all-in-one workspace platform today — docs, wikis, databases, project boards, roadmaps, meeting notes, all in one tool. When you export from Notion (Settings → Export, or File → Export on a specific page), you can choose Markdown format. Notion will zip up your pages as .md files along with any attached media. So far so good: you have Markdown, the universal format. But open one of those .md files and you discover quirks — document headers with Created: and Last edited: lines that Notion inserts automatically, callout blocks rendered with emoji-prefixed blockquotes that don't match GFM admonition syntax, database exports with hash-based internal URLs, and other idiosyncrasies.

Converting Notion-exported Markdown to standard Markdown means cleaning up these Notion-specific quirks so the content fits into downstream systems (GitHub wikis, Jekyll/Hugo blogs, Docusaurus sites, Obsidian vaults, Logseq graphs) that expect plain GFM. Our converter normalizes the common Notion patterns while preserving everything else as-is.

Why migrate out of Notion to standard Markdown?

Notion is a great authoring tool but a lock-in for long-form content. Once your content lives in Notion, it's inside a proprietary database, rendered by Notion's client, accessible through Notion's app. Four recurring reasons to migrate out:

First, permanence: Notion is a SaaS product. It's alive today but could shut down, be acquired, change pricing, or change features. If your content is your IP (internal knowledge base, published handbook, research notes), you want it in a format that survives independent of any single vendor. Plain Markdown files in a git repo outlive any SaaS.

Second, publishing: Notion has public-page sharing and a paid "Notion Sites" feature, but the SEO of a Notion-hosted page is weaker than a purpose-built static site. If you want to publish (personal blog, company handbook, open docs), the path is usually Notion → Markdown → static site generator → deployment.

Third, offline and search: plain Markdown in a local folder works offline, is grep-able, is editable in any text editor. Notion requires the app or browser, a Notion account, and a network. For personal notes you plan to reference for years, local Markdown is often more durable.

Fourth, integration: version control (git), CI pipelines, automated testing of docs, documentation-as-code workflows — these work with Markdown files, not with Notion databases. Teams moving from "docs in Notion" to "docs in the repo" need the content exported and cleaned.

Manual approach

Cleaning up a Notion-exported Markdown file by hand is straightforward for a single document, slow for a library. You open the file, delete the Created: / Last edited: lines at the top, find any callout blocks (they start with > <emoji> like > 💡 …), decide whether to convert them to GFM admonitions or leave as plain blockquotes, walk through any database exports and check the table formatting. Links usually work (internal Notion page URLs are hashes, which stay as-is), but if you want pretty slug URLs for a target static site, you need a URL rewrite pass.

For a 10-page Notion export, manual cleanup takes 20-40 minutes. For a 100-page knowledge base export, it's a full afternoon. The callouts are the slowest — finding them, deciding on mapping, and applying consistently is a repetitive task perfect for automation.

Automated approach (our tool)

Our Notion normalizer runs four passes over the pasted content:

Frontmatter strip. Notion prepends Created: <date> and Last edited: <date> lines to exported pages. These are metadata, not body content. Our engine strips them along with any leading blank lines so the cleaned output starts at the first real heading or paragraph.

Emoji callout conversion. Notion exports callout blocks as blockquote lines prefixed with an emoji:

• > 💡 Tip content → > [!TIP] Tip content
• > ⚠️ Warning content → > [!WARNING] Warning content
• > ❗ Important content → > [!IMPORTANT] Important content
• > 📝 Note content → > [!NOTE] Note content
• > 🔥 Caution content → > [!CAUTION] Caution content

The five emojis above map to the five GFM admonition types. Any other emoji-prefixed blockquote falls back to > [!NOTE] … — preserving the callout semantic without forcing a type match. These GFM admonitions render as styled callout blocks on GitHub, Obsidian (with Callouts plugin), and most modern Markdown renderers.

Standard blockquote preservation. A regular blockquote (> some quoted text without an emoji) stays as-is — our engine only transforms emoji-prefixed ones.

Passthrough of standard Markdown. Headings (#, ##), lists (-, 1.), code fences (```), inline formatting (**bold**, *italic*, `code`), tables (GFM pipe syntax), images (![alt](url)) — all preserved verbatim. Notion's exports use standard Markdown for these, so no transformation is needed.

The tool doesn't do anything speculative. It doesn't rewrite URLs, doesn't re-slug internal links, doesn't strip or reformat database export tables. The philosophy: normalize the Notion-specific quirks, pass everything else through unchanged so you can apply your own target-specific conventions.

Common gotchas

Database exports are MD tables but have Notion URL hashes. When you export a Notion database, each page entry in the database appears as a row in the resulting MD table, with the page title wrapped as an internal link: [Page Title]\(Page Title <hash>.md\). These URLs reference the individual page files in the exported zip. After cleanup, you have two options: (a) if you're migrating the whole workspace, rewrite internal links to match your target platform's slug scheme; (b) if you're extracting a single page, decide whether to drop the links or keep as broken references.

Exports split pages across files. A top-level Notion workspace export produces one .md file per page, plus subfolder .md files per nested page. The internal links reference sibling files. Cleanup is per-file — you paste each file into our tool one at a time. For bulk, script the extraction or use our tool's per-page output as part of a larger pipeline.

Toggles become headings with nested content. Notion's "Toggle" blocks (collapsible sections) export as a heading followed by the nested content. Our tool doesn't recognize them as a special structure — they pass through. If you wanted toggle-equivalent behavior in the target (e.g., HTML <details> tags), you need to add those by hand after conversion.

Embedded files and images land as relative URLs. Notion exports images and file attachments as separate files in the zip, with relative URLs in the MD. Our tool preserves these. After cleanup, copy the attachment files to your target's media folder and verify the relative paths still resolve. For static site generators, usually you move all assets to a /static/ or /public/ folder and adjust URLs.

Notion's inline equations export as plain text. If your Notion page had math equations (from the Equation block), they export as LaTeX-ish text without delimiters. Our tool preserves the text but doesn't wrap in $…$. You'll need to add math delimiters by hand if your target supports KaTeX/MathJax rendering.

Mentions and page references. Notion lets you @-mention people and link to other pages inline. These export with Notion-specific hashes. Our tool preserves the link syntax but the hashes are only meaningful inside the exported zip. In a migration, rewrite or strip depending on your target.

Headers inside callouts. Some Notion users put headings inside callout blocks. When exported, these appear as > ## Heading inside callout. Our GFM admonition conversion keeps the heading inside the blockquote, which GFM renderers handle correctly (most render as a styled header inside the callout box).

When to use a different tool instead

For bulk export and transformation: notion-to-md (GitHub: souvikinator/notion-to-md) uses the Notion API directly rather than exports, preserving more structure (block types, properties, database schemas). Requires a Notion integration token and some scripting.

For Notion-to-static-site migration (whole workspace): notion-blog or next-notion-blog templates pull from the Notion API directly and render as Next.js sites. No manual export step; content stays live in Notion.

For editing Notion pages without leaving Notion: don't convert — use Notion's built-in editor. Our tool is for the outbound migration case.

For converting Notion pages to other formats (PDF, Word, EPUB): use Notion's native export to that format instead of Markdown-then-convert. Our tool is specifically for cleaning Markdown exports.

For archival backups (just preserving the content without conversion): Notion's native Markdown export is the archive. Our tool is for when you want to use that content elsewhere.

Migration workflow

A workflow for moving a Notion workspace to a Markdown-based system:

1. Export from Notion. Settings & Members → Settings → Export Content. Choose Markdown & CSV. This produces a zip with one .md file per page, CSVs for databases, and a media folder.
2. Unzip and inspect. Look at the file structure — top-level pages, subfolders for nested content, media folder. Identify the pages you want to migrate vs. the scratch work you want to leave behind.
3. Per-page cleanup via our tool. Paste each relevant .md file into our tool, paste the cleaned output back into a local file. Or script this: our tool's source is also available as @vust/markdown::notionNormalize npm package if you want local batch processing.
4. Handle database exports separately. Notion databases export as MD tables (page titles with internal links). Decide: keep as a table in your target? Turn each database row into its own page? Strip the database structure and keep just content?
5. Rewrite internal links. The exported hashes reference files in the zip. Run a search-and-replace or script to map them to your target's slug scheme (Hugo: lowercase-hyphenated; Jekyll: same; Obsidian: keep hashes for wiki-link compatibility).
6. Handle media. Move images and attachments from Notion's media folder to your target's asset location. Adjust relative paths in the Markdown if the folder structure changed.
7. Add frontmatter. Our tool doesn't generate frontmatter — that's target-specific. Add YAML --- blocks with title, date (recover from the stripped Created: line before cleanup if you need it), tags, layout.
8. Preview in target platform. Build the site locally or open the Obsidian vault. Verify that: callouts render as GFM admonitions, links work, images load, tables display, no Created: / Last edited: lines survived the cleanup.
9. Iterate on mapping decisions. First pass will surface edge cases — toggles that need to become details tags, equations that need math wrappers, page mentions that need custom components. Build a small script or note these for manual fixing.

For a 30-page Notion workspace migration, expect 2-4 hours spread across the steps. The per-page cleanup (step 3) is fast with our tool; the per-page custom work (steps 5-7) is where most time goes.