Notion and Markdown

Notion takes Markdown in and gives Markdown back, but never stores it: a page is a tree of blocks, so Markdown is a format it reads and writes rather than the thing it holds. Below is a converter for getting one page out, and what to expect in each direction.

Notion writes blocks, not Markdown

This one fact explains everything else on the page. When you type ## in Notion, the characters are consumed and a Heading 2 block appears. The Markdown was an instruction, not content — there is no ## in the page afterwards, because there is no text file afterwards.

So Markdown going in is a shortcut, Markdown coming out is a rendering, and nothing round-trips exactly. That is not a flaw so much as the trade Notion made: blocks buy databases, backlinks and synced content, and cost you the plain file.

Getting Markdown into Notion

Just paste it. Notion recognises Markdown in pasted text and converts it as it lands — headings, lists, bold, italic, links, code blocks and tables all arrive as real blocks. For most purposes this is the whole answer, and it is why there is no "import this paragraph" command.

Type it. The same shortcuts work as you write:

The > row is worth noticing. Everywhere else an angle bracket makes a blockquote; in Notion it makes a collapsible toggle, and the quote is a double quote character instead.

Import a file. Sidebar → Import → Markdown & CSV takes .md files or a .zip of them, creating a page per file. Right for a batch, slower than pasting for one.

Getting Markdown out of Notion

For one page, select the content, copy, and paste into the converter above. The clipboard carries an HTML version of the selection alongside the plain text, and that is what gets converted — so headings stay headings rather than becoming a wall of unstyled lines. No download, no unzip, and nothing leaves your browser.

For a workspace, use Notion's own export: ••• → Export → Markdown & CSV. It produces a .zip with one .md per page, databases as separate CSV files, and images in folders alongside.

Two things about that export are worth knowing before you rely on it. Every filename gets the page ID appended — Meeting notes 8a3f21c9….md — and every internal link points at those names, so a usable set of documents needs a rename-and-relink pass. And the first line of each file is the page title as an H1, which duplicates the filename.

What does not survive the trip out

The database row is the one that surprises people mid-migration. A page built around an inline database exports as a document with a gap in it and a CSV beside it, and reassembling that is manual work. If a Notion workspace is mostly databases, Markdown is not really the export format for it.

One syntax difference to remember

~struck~     Notion
~~struck~~   GitHub Flavored Markdown

One tilde, not two. Text moved either way loses the formatting without complaint — the markers just render as literal tildes. Everything else in Notion's inline syntax matches the standard.

Why convert at all

Usually because the document needs to outlive the tool, or go somewhere Notion cannot reach: a repository, a static site, a PDF for someone without an account. Markdown is the format that does all three, and once a page is Markdown you can export it to PDF or to Word from here without it going anywhere near a server.