Notion markets itself as Markdown-friendly, and for basic formatting it mostly is. But spend enough time moving documents between Notion and the rest of your toolchain and you’ll hit the edge cases: frontmatter that renders as prose, tables that become databases, Mermaid diagrams that become plain text, and HTML that disappears entirely.

This is a guide to what actually happens — not what the docs say should happen.

How Notion Handles Markdown Input

Notion has three different ways to get Markdown in, and they don’t all behave the same:

Method Best for Reliability
Paste Short snippets, quick formatting Medium — tables and code blocks often break
File import (drag .md file) Full documents, preserved structure High — most reliable option
/markdown slash command Pasting a block of Markdown text Medium — same caveats as paste

File import is more reliable than paste. When you paste Markdown, Notion processes it in real time, which can produce odd results with complex tables and fenced code blocks. Dragging a .md file into the sidebar triggers Notion’s dedicated importer, which handles the format more consistently.

What Converts Cleanly

These elements survive the trip from Markdown to Notion reliably:

  • Headings (#, ##, ###) → Notion heading blocks (H1, H2, H3)
  • Bold and italic (**bold**, *italic*) → rich text formatting
  • Inline code (`code`) → inline code formatting
  • Fenced code blocks with language labels → Notion code blocks with syntax highlighting
  • Unordered lists (-, *) → bulleted list blocks
  • Ordered lists (1., 2.) → numbered list blocks
  • Checkboxes (- [ ], - [x]) → to-do blocks
  • Links ([text](url)) → hyperlinks
  • Blockquotes (>) → Notion quote blocks
  • Horizontal rules (---) → divider blocks

For plain prose documents, Notion is actually solid. The problems start with the more complex elements.

What Breaks or Gets Transformed

YAML Frontmatter

Notion has no concept of frontmatter. If your document starts with:

---
title: My Document
date: 2026-06-26
---

Notion imports this as plain text — the dashes become a divider block, and title: My Document renders as a heading or prose depending on context. If you’re importing docs that have frontmatter, strip it before importing, or use our Markdown to Notion converter, which removes frontmatter automatically and warns you what was stripped.

Tables

Tables are the trickiest part. Notion renders them differently depending on context:

  • In the body of a page, a Markdown table becomes a simple inline table (not a database)
  • When imported via file, tables often become Notion databases with property columns
  • If the separator row is missing (|---|---|), the table may just render as pipe-separated text

Notion is strict about the GFM table format. Missing or malformed separator rows reliably break table rendering.

What Notion tables don’t support:

  • Column alignment (:---: / ---: is ignored)
  • Multi-line cells
  • Colspan or rowspan

Images

Image syntax (![alt](url)) works for external URLs. If your images use relative paths (e.g., ![chart](./images/chart.png)), they’ll break — Notion can’t resolve relative filesystem paths. Convert relative paths to absolute URLs before importing.

HTML

Notion strips HTML entirely. Any <div>, <span>, <details>, <summary>, or other HTML elements in your Markdown will disappear on import. If you’re using HTML for collapsible sections, badges, or custom alignment, those won’t survive.

Mermaid Diagrams

Notion does not render Mermaid diagrams. A fenced code block tagged with mermaid will import as a plain code block containing the diagram source — not a rendered diagram. This trips people up because GitHub, GitLab, and several documentation tools do render Mermaid natively.

If you have Mermaid diagrams, your options are: export them as images and embed, or use Notion’s native embed integration (which requires a third-party service).

Footnotes

Standard Markdown footnote syntax ([^1]) isn’t supported by Notion. On import, footnote references typically disappear and the footnote definitions render as plain text at the bottom of the page. Our converter inlines footnotes — replacing [^1] references with the footnote text in italics — which is the most readable fallback.

GitHub-Style Alerts

GitHub Flavored Markdown alerts like:

> [!NOTE]
> This is an important note.

…render in GitHub as styled callout boxes, but Notion imports them as plain blockquotes. The [!NOTE] text appears literally in the quote. In newer Notion workspaces you can manually convert the blockquote to a callout block after import, but it’s a manual step.

Exporting Markdown from Notion

Notion’s export (Page → Export → Markdown & CSV) produces reasonable Markdown, but with quirks to know about:

Tables export as CSV files — not inline Markdown tables. If your page contains a database, the export creates a separate .csv file and links to it from the Markdown. This roundtrip doesn’t work well for docs-as-code workflows where you expect embedded tables.

Internal page links export as full Notion URLs — not relative paths. An internal link to another Notion page becomes something like [Page Title](https://www.notion.so/workspace/abc123...). These links break when you move content out of Notion.

Callout blocks export as blockquotes with the emoji prepended as plain text.

Nested pages export as subdirectories. The folder structure maps to page hierarchy, which is useful if you want to mirror the Notion structure but inconvenient if you want a flat directory.

Whitespace in exported tables includes trailing spaces for column alignment. Most parsers handle this fine, but some produce artifacts.

Notion API and Markdown

If you’re using the Notion API to create or update pages programmatically, you can’t POST Markdown directly. The API uses Notion’s own block format — each heading, paragraph, list item, and code block is a separate JSON object. You need to convert Markdown to block format before posting.

This matters for teams automating documentation workflows: syncing a Git repo to Notion, generating pages from templates, or importing content on a schedule. The Notion API is capable, but it expects its own block format, not Markdown strings.

Quick Reference: Import Compatibility

Markdown feature Imports correctly? Notes
Headings H1–H3 Yes  
Bold, italic Yes  
Inline code Yes  
Fenced code blocks Yes Language labels preserved
Unordered / ordered lists Yes  
Checkboxes Yes  
Links Yes  
Blockquotes Yes  
Tables (with separator row) Mostly No alignment, colspan
YAML frontmatter No Renders as prose / divider
Images (relative paths) No Absolute URLs only
HTML No Stripped entirely
Mermaid diagrams No Renders as plain code block
Footnotes No Definitions appear as text
GitHub-style alerts Partial Renders as plain blockquote

Using the Converter Tool

If you’re regularly moving content into Notion, our Markdown to Notion converter handles the pre-processing:

  • Strips YAML frontmatter (with a warning listing what was removed)
  • Inlines footnotes as italic text inline with the reference
  • Converts GitHub-style alerts to labeled blockquotes
  • Removes HTML tags (with a warning)
  • Flags Mermaid diagrams so you can handle them manually

Paste your Markdown on the left, get Notion-ready Markdown on the right. No signup required.