Notion markdown: what Notion types, imports and exports
Updated
Notion is a block editor, not a markdown editor, but it speaks markdown at three borders: shortcuts you type convert into blocks, pasted or imported markdown becomes blocks, and "Markdown & CSV" export turns blocks back into files. The tables below say exactly what crosses each border and what turns into plain text, straight from Notion's help articles.
Markdown shortcuts Notion converts as you type
| Type this | Notion makes | In GFM | Note |
|---|---|---|---|
**text** | Bold | Same | |
*text* | Italic | Same (also _text_ in GFM; Notion only documents *) | |
`text` | Inline code | Same | |
~text~ | Strikethrough | GFM prefers ~~text~~ | Single tilde |
# + space | Heading 1 | Same | |
## + space | Heading 2 | Same | |
### + space | Heading 3 | Same; Notion has no H4–H6 | |
-, * or + + space | Bulleted list | Same | |
1., a. or i. + space | Numbered list | Only 1. in GFM | |
[] + space | To-do checkbox | - [ ] in GFM | No space between the brackets |
> + space | Toggle list | > is a blockquote in GFM | The biggest surprise for markdown users |
" + space | Quote block | Not markdown | |
--- | Divider | Same (horizontal rule) | |
[text](url) | Not converted while typing | Link | Paste a URL over selected text, or Cmd/Ctrl+K |
| a | b | | Not converted while typing | Table | Use /table, or paste a whole markdown table |
``` | Not documented as a shortcut | Code block | Use /code or Cmd/Ctrl+Option/Shift+8 |
 | Not converted while typing | Image | Use /image |
Inline shortcuts (type around text)
Bold, italic, code, strikethrough
**bold** *italic* `code` ~strike~bold italic code strike
Notion converts the markers the moment you type the closing one. Strikethrough is a single tilde; the double tilde GFM uses also works on paste.
Block shortcuts (type at the start of a line, then space)
Headings, lists, to-dos
# Heading 1
## Heading 2
### Heading 3
- Bulleted item
1. Numbered item
[] To-do itemHeading 1
Heading 2
Heading 3
- Bulleted item
- Numbered item
- To-do item
Notion has only three heading levels. The to-do shortcut is [] with no space inside, then a space — different from GFM's - [ ].
Toggle vs quote: > is a toggle in Notion
> This becomes a TOGGLE in Notion
" This becomes a QUOTE in Notion
--- (divider)In every other markdown dialect > is a blockquote. Notion's "typing" shortcut makes it a collapsible toggle; the quote block shortcut is a double quote. On paste or import, > is treated as a quote.
Pasting markdown
Paste a whole document
## Release notes
- [x] Ship v2
- [ ] Write docs
| Area | Owner |
| --- | --- |
| API | Sam |
```js
console.log("hi");
```Release notes
- Ship v2
- Write docs
| Area | Owner |
|---|---|
| API | Sam |
console.log("hi");
Pasting multi-line markdown into a Notion page converts headings, lists, to-dos, tables and code fences into blocks. Anything Notion has no block for (footnotes, alerts, HTML, front matter) stays as plain text.
What export writes
Callout and toggle after "Markdown & CSV" export
<aside>
💡 A callout comes out as HTML because markdown has no callout block.
</aside>
- A toggle heading
The toggle body is exported as an indented block under it; the fold is gone.Notion's help says callouts "will be exported as HTML, as there is no Markdown equivalent". Replace the <aside> with a GitHub alert or a blockquote before publishing elsewhere.
Database → CSV + one .md per row
Tasks 1a2b3c4d.csv
Tasks/
Write docs 5e6f7a8b.md
Ship v2 9c0d1e2f.mdEvery exported file name carries the 32-character page id. Only the current or default view is exported, and form views cannot be exported at all.
What survives paste and .md import
| Markdown element | Imports? | Notes |
|---|---|---|
| Headings | Yes | Notion only has heading blocks 1–3 |
| Paragraphs, bold, italic, code | Yes | Standard markdown |
| Bulleted and numbered lists | Yes | Nesting preserved |
| Task lists | Yes | - [ ] becomes a to-do block |
| Fenced code blocks | Yes | Named in the help article as supported |
| Blockquotes | Yes | > becomes a quote block, not a toggle |
| Tables | Yes (simple) | Pipe tables become simple table blocks |
| Links | Yes | External links; relative links between files are not re-pointed |
| Anchor links (#heading) | No | Explicitly listed as not importing |
| Images | If reachable | Remote URLs import; local paths need the files zipped with the markdown |
| HTML inside markdown | No | Not a Notion block; not listed as supported |
| Front matter (YAML) | No | Not standard markdown — arrives as plain text |
| Footnotes, alerts, wikilinks, math | No | "Advanced or nonstandard Markdown extensions" are not imported |
| Folder structure | Yes, from a ZIP | Zip the folder first to keep the hierarchy |
What "Markdown & CSV" export produces
| Notion block | Exported as |
|---|---|
| Page | One .md file named "Title <32-char id>.md" |
| Headings 1–3 | #, ##, ### |
| Text with bold / italic / code / strike | **bold**, *italic*, `code`, ~~strike~~ |
| Bulleted, numbered, to-do lists | -, 1., - [ ] / - [x] |
| Toggle | Its heading line plus the indented content; the fold is lost |
| Callout | HTML (<aside>) — Notion says there is no Markdown equivalent |
| Quote | > blockquote |
| Code block | Fenced block with the language tag |
| Divider | --- |
| Simple table | Pipe table |
| Image / file | Downloaded into a folder, linked with a relative path |
| Sub-page | Separate .md file (with "Include subpages" on), linked from the parent |
| Full-page database | One .csv per view you choose, plus a .md per row page |
| Inline database | A .csv next to the page and a link in the .md |
| Database form view | Cannot be exported; use Table view |
| Comments | Only the HTML export option mentions comments |
| Columns, colours, page icon and cover | No markdown equivalent |
Does Notion support markdown?
Partially. Notion is not a markdown editor: it stores blocks, but it accepts markdown three ways. While typing, it converts shortcuts (**bold**, # headings, - lists, [] to-dos, > toggles, --- dividers). On paste, it converts whole markdown documents including tables and code fences. On import, it reads .md files. In each case anything without a Notion block equivalent becomes plain text.
Why does > make a toggle instead of a quote in Notion?
Because Notion assigned the > shortcut to its toggle block and gave quotes the " shortcut. This only applies to the typing shortcut: when you paste or import markdown, a > line becomes a quote block. If you want a toggle from imported markdown, you have to convert the block afterwards.
How do I import a markdown file into Notion?
Settings → Import → Text & Markdown, or drag the .md file onto a page. Notion imports headings, lists, code blocks and standard markdown; anchor links and non-standard extensions (footnotes, alerts, wikilinks, math, HTML) do not import. Files are limited to 5 MB on the Free plan and 50 MB on paid plans, and there is a limit of roughly 120 file imports per 12 hours. Zip a folder to keep its structure.
How do I export a Notion page to markdown?
Open the page menu (…) → Export → format "Markdown & CSV". You get a ZIP with one .md per page, a folder of images and files, a .csv for every database, and separate .md files for sub-pages if "Include subpages" is on. Callouts come out as HTML, toggles lose their fold, and comments are not included.
What markdown features does Notion not have?
Headings 4–6, footnotes, alerts and callouts in markdown form, definition lists, HTML, front matter, math inside text (Notion has a separate equation block), wikilinks, and nested tables. Pasting them produces plain text; exporting a Notion page never produces them.
Do Notion exports render on GitHub?
Mostly: headings, lists, to-dos, tables, code fences, dividers and quotes are GFM. Fix two things first — the <aside> blocks from callouts (GitHub keeps the tag but not the styling; rewrite them as > [!NOTE] alerts) and the relative image paths with page ids and spaces in them, which need URL-encoding.
Related tools and sheets
Clean up an export with the markdown formatter, check its links with the link checker, convert database CSVs with CSV to markdown, or share the page as a link. Compare with the Obsidian sheet and the flavor comparison.