Markdown in Notion: shortcuts, import, export and limits

The shortcuts that convert while you type

Notion's shortcuts fall into two groups. Block shortcuts fire when you type the marker at the start of an empty line and press space. Inline shortcuts fire the moment you close the second delimiter.

Block-level shortcuts

# + space        →  Heading 1
## + space       →  Heading 2
### + space      →  Heading 3
- + space        →  Bulleted list
1. + space       →  Numbered list
[] + space       →  To-do block with a checkbox
> + space        →  Toggle list  (NOT a blockquote)
" + space        →  Quote block
``` (backticks)  →  Code block
---              →  Divider

Two of those surprise people. Notion stops at three heading levels, so #### and deeper have nowhere to go, which the headings guide contrasts with the six levels the spec allows.

Careful: > plus a space produces a toggle, not the blockquote every other Markdown tool gives you. Notion maps the quote block to a double quotation mark instead. If your muscle memory comes from GitHub or Reddit, this is the one that catches you.

Inline shortcuts

**bold**                          →  bold text
*italic*                          →  italic text
~~strikethrough~~                 →  strikethrough
`code`                            →  inline code
[MD Editor](https://mdeditor.tw)  →  a hyperlink

These are the same characters listed in our cheat sheet. What is missing matters just as much. There is no shortcut for a pipe table, an image, a footnote or raw HTML. Type a pipe table into Notion and you get a paragraph full of pipe characters.

Typing Markdown versus pasting it

Pasting is a bulk conversion

Typing converts one construct at a time. Pasting works in bulk: Notion parses the structure it recognises and builds the matching blocks in a single pass. Headings, lists, emphasis, code fences and links generally come across. Anything outside that set lands as literal characters.

So if you drafted a long document elsewhere, pasting beats retyping every time. It is also gentler on your hands, since no shortcut can fire at the wrong moment halfway through a sentence.

When you want the symbols kept

Sometimes the raw characters are the content. Writing documentation about Markdown is the obvious case. Use paste-without-formatting, which is Ctrl+Shift+V, or Cmd+Shift+V on a Mac.

Either way you end up holding blocks. Paste a heading and you own a heading block, not a line of text that begins with a hash. That is the same conversion described in our Markdown to HTML walkthrough, except Notion keeps the result instead of showing it to you.

Importing .md files: what survives and what breaks

How the Import command behaves

Notion's sidebar has an Import command with a Markdown option. It takes individual .md files or a .zip of them, and creates one page per file. The page title normally comes from the file name, so a leading # Title line often ends up duplicated as a heading inside the page. Deleting one of the two is usually the first cleanup step.

Below is the honest version of what makes it through. Spot-check the unreliable rows, because import behaviour has changed more than once.

What breaks, and the fix

The fix has the same shape for every failure: strip it before importing, rebuild it natively afterwards. Do that and the import stops being a lottery.

1. Remove tables, footnotes and raw HTML from the .md file first.
2. Flatten any list nested deeper than three levels.
3. Import the file, or the zip with its images inside.
4. Rebuild the tables with /table, then delete the duplicated title line.

Footnotes have no home in Notion, so turn them into inline parentheses or a short "Notes" section at the bottom. Our footnotes guide shows the syntax you are giving up.

Tables deserve the extra step. Notion's simple table is a real block and behaves far better than an imported one, so build it after the page arrives rather than fighting the parser. Deeply nested lists are the fourth risk: indentation a strict parser accepts can still collapse on the way in, which the lists guide explains.

Exporting a Notion page back to Markdown

Where the export button lives

1. Open the ... menu at the top of any page.
2. Choose Export.
3. Pick Markdown & CSV as the format.
4. Set the subpage and image options before you confirm.

You usually get a .zip rather than a bare file, because Notion packages the assets with the text. A typical export unpacks like this:

My Project Notes 8f3c1a20d4b6431f9e7a2c5d81b0e6a4.md
My Project Notes 8f3c1a20d4b6431f9e7a2c5d81b0e6a4/
    screenshot.png
    Task list 2b91f7c04e8d40a1.csv

The quirks to expect

• File names carry an ID. Files are named after the page title with a long hexadecimal string appended, the page's internal identifier. Functional, ugly. Batch-rename before they go into a repository.
• Images become local files. Attachments go into a folder beside the Markdown, referenced with relative, URL-encoded paths. Move the .md without its folder and every image breaks.
• Databases export as CSV, not Markdown. A Notion database is not a table in the Markdown sense, so it leaves as a separate .csv file covering the current view.
• Blocks with no Markdown equivalent are flattened. Structure disappears, content survives as ordinary paragraphs and lists. Exporting a page and importing it again will not reproduce the layout.

Why to schedule it anyway

Export is the only way to hold your writing in a format that does not depend on one company staying in business. A .md file opens in any editor, this decade and the next. Our note on the .md extension covers what that file actually is.

What Notion has that Markdown cannot express

Some of Notion's best features have no Markdown representation at all, which is precisely why export is lossy:

• Databases - Tables, boards, calendars and timelines, with typed properties, filters, sorts and relations. Markdown has one flat table construct and no concept of a property type.
• Toggles - Collapsible sections. Markdown has no fold, though HTML's <details> element is the nearest thing where inline HTML is allowed.
• Callouts - Coloured boxes with an emoji. GitHub added its own alert syntax for this, described in our GFM guide, but that is a GitHub extension, not portable Markdown.
• Synced blocks - One piece of content living in several pages at once. Text files have no such mechanism.
• Columns - Side-by-side layout. Markdown is strictly a single vertical flow of blocks.
• Mentions, comments and page properties - Notion-native metadata with nowhere to land in a text file.

Neither tool is at fault

Markdown is deliberately small so that it stays portable. Notion is deliberately rich so that it can replace a wiki, a spreadsheet and a task tracker at once. Knowing how much of a page lives in the portable subset tells you how much you can expect back, and the platform comparison shows where every other app draws the same line.

The workflow that actually works

Draft in Markdown, finish in Notion

If you care about owning your text, invert the usual order. Draft in real Markdown first, where characters stay characters. Then move the finished piece into Notion for sharing and commenting. Our free online Markdown editor is built for exactly this: write on the left, watch the rendered result on the right, then copy the raw text across.

That buys you two things Notion alone cannot. You keep a canonical .md file that opens in any tool in twenty years, and you get a clean, predictable paste instead of shortcuts firing mid-sentence. Documentation, blog drafts and anything destined for a code repository belongs in this lane.

Tip: Keep the .md file as the master copy and treat the Notion page as a published view. When the text changes, edit the file and paste again. Editing both and trying to reconcile them later is how versions drift apart.

What to leave to Notion

Use Notion natively for what it does better: collaborative pages, project databases, and meeting notes that need comments attached. Then export on a schedule as a backup, knowing the lossy parts in advance.

To ground the syntax itself, work through the complete Markdown guide. If you are unsure which dialect to write in, choosing a Markdown flavor is the short answer. Chat platforms differ again, as Markdown in Discord shows.