Skip to content
All posts

Notion Markdown: Complete Formatting Guide (2026)

Everything Notion supports from Markdown — headings, lists, code, tables, callouts, math, import/export quirks, and the workarounds power users rely on when standard syntax does not paste cleanly.

Notion is one of the most popular places people write today — but it is not a Markdown editor. It is a block-based workspace that understands Markdown when you paste or type certain patterns, then silently converts them into Notion blocks.

That hybrid model is powerful and frustrating in equal measure. Type **bold** and it works. Paste a full GitHub README and half the syntax breaks. Try [link text](url) in a paragraph and nothing happens.

This guide is the full reference: what Notion accepts from Markdown, what it ignores, how import and export behave, and the workflows that keep your notes portable without fighting the editor.

How Notion handles Markdown

Notion stores content as blocks — paragraphs, headings, toggles, databases, embeds — not as a raw .md file. When you type Markdown-like syntax, Notion's input rules convert it inline:

You type (then space or Enter)Notion block
# HeadingHeading 1
## HeadingHeading 2
### HeadingHeading 3
- item or * itemBulleted list
1. itemNumbered list
[] or [ ]To-do (unchecked)
[x]To-do (checked)
> quoteQuote block
---Divider
`code`Inline code
```Code block

Everything else — bold, italic, strikethrough, links — is handled as inline formatting inside a paragraph block, not as separate block types.

The paste behavior (most important detail)

When you paste Markdown from another app, Notion runs a conversion pass:

  • Headings, lists, quotes, dividers, code fences usually convert correctly.
  • Tables may become a native Notion table or fall back to plain text, depending on complexity.
  • Markdown links [text](url) often convert to Notion links — but not when typed character-by-character in an existing paragraph.
  • Images ![alt](url) may import if the URL is reachable; local paths fail.
  • HTML is stripped or escaped — do not rely on raw HTML in Notion.
  • GFM alerts > [!NOTE] and Obsidian callouts do not map to Notion callouts automatically.

Rule of thumb: paste works better than typing for block-level structure; inline formatting works better when you type the trigger characters fresh.

Inline formatting

Bold, italic, and strikethrough

Notion supports the standard trio:

**bold text**
*italic text*
~~strikethrough~~

You can combine them:

***bold italic***
**~~bold strike~~**

Keyboard shortcuts (faster once muscle memory kicks in):

ActionWindows / LinuxmacOS
BoldCtrl+BCmd+B
ItalicCtrl+ICmd+I
StrikethroughCtrl+Shift+SCmd+Shift+S
Inline codeCtrl+ECmd+E

Inline code

Wrap text in single backticks, or select text and press Ctrl/Cmd+E:

Run `npm install` before `npm start`.

Notion does not syntax-highlight inline code — only fenced code blocks get language highlighting.

Typed links: Notion does not reliably convert [label](https://example.com) while you type in a normal paragraph. Use one of these instead:

  1. Paste Markdown that already contains links — conversion often works.
  2. Select text → Ctrl/Cmd+K and paste the URL.
  3. Bare URL — Notion auto-links https://example.com.
  4. Slash command /link on selected text.

For documentation that must stay Markdown-portable, write links in standard syntax in your source files and paste into Notion only when publishing.

Underline and highlight

Notion supports underline (Ctrl/Cmd+U) and text highlight colors — neither has standard Markdown syntax. They are Notion-only affordances and will be lost or flattened on Markdown export.

Headings

Notion supports three heading levels in most workspaces (H1–H3). Type at the start of a line:

# Page title level
## Section
### Subsection

There is no H4–H6 in native Notion. For deeper hierarchy, use bold paragraph text, toggles, or indented sub-pages.

Heading blocks double as outline anchors in the Notion sidebar table of contents (when enabled on a page).

Lists

Bulleted and numbered

- First item
- Second item
  - Nested item

1. Step one
2. Step two
   1. Sub-step

Tab to indent, Shift+Tab to outdent. Notion list blocks support one level of visual nesting cleanly; deeper nesting gets awkward in exports.

To-do lists

- [ ] Unchecked task
- [x] Completed task

To-do blocks sync with Notion databases when you convert a list to a database view. For personal task tracking, they are the fastest Markdown-compatible block.

Quotes and callouts

Quote blocks

Type > at the start of a line:

> This renders as a quote block.
> Multiple lines stay in the same block if you keep typing.

Callouts (Notion-native)

Callouts are not standard Markdown. Create them with /callout or by typing the emoji shortcut patterns some templates use.

Common callout types in Notion:

TypeTypical use
💡 NoteNeutral context
⚠️ WarningCaution, breaking changes
❗ ImportantMust-read detail
✅ SuccessConfirmations, done states

When exporting to Markdown, callouts usually become quoted paragraphs with emoji prefixes — not GFM alerts. If portability matters, author callouts in GitHub/Obsidian alert syntax in your source repo and convert on import.

Code blocks

Fenced blocks with optional language tags:

```javascript
const page = await notion.pages.retrieve({ page_id });
console.log(page);
```

Supported languages match a subset of VS Code's grammar list — javascript, typescript, python, bash, json, sql, and markdown work reliably. Unknown language tags still create a code block without highlighting.

Tips:

  • Use /code for an empty block, then paste.
  • Notion code blocks have a copy button — great for internal runbooks.
  • Long logs: consider a toggle titled "Full output" instead of a 500-line block (page performance).

Tables

Markdown table paste

Paste a GFM table and Notion often converts it to a native table block:

| Feature    | Notion | Markdown file |
| ---------- | :----: | :-------------: |
| Live sync  |   ✅   |        ❌       |
| Offline    |   ⚠️   |        ✅       |
| Raw `.md`  |   ❌   |        ✅       |

Limits:

  • Very wide tables truncate or scroll horizontally.
  • Cell-level Markdown (bold in a cell) works in native tables.
  • Merged cells are Notion-only — they break on export.

Build complex tables in the Markdown table generator, then paste into Notion.

Math (equations)

Notion supports LaTeX-style equations in dedicated equation blocks (/equation or $$ on paste in some clients):

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Inline math uses a single `$...$` equation block in some workflows, but the supported surface changes between Notion versions. For critical docs, preview equations after paste.

Use the math inventory tool to audit `$...$` and $$...$$ pairs before moving technical docs into Notion.

Images, files, and embeds

Images

Markdown image syntax on paste:

![Architecture diagram](https://example.com/diagram.png)

Local paths (./assets/diagram.png) fail — upload to Notion or host the image at a public URL.

Native Notion approach: /image upload, or drag-and-drop. Notion hosts files on its CDN; exported Markdown will reference temporary or broken URLs unless you re-host assets.

Embeds

Notion embeds (/embed) are not Markdown. Supported oEmbed sources include Figma, Loom, GitHub gists, CodePen, and generic iframes where workspace policy allows.

For a live Markdown editor inside a Notion page, use an Embed block with the Markdown Viewer integration shortcode — same editor as the site, no API key required.

Databases vs. Markdown

Notion databases are not Markdown tables. They are structured data with properties (status, date, person, relation). Common migration pattern:

  1. Keep canonical content in Git as .md files.
  2. Mirror summaries in a Notion database with a URL property linking to the repo file.
  3. Use Notion for workflow (status, owners); use Markdown for long-form body text.

Trying to represent a database as a giant Markdown table loses relations, rollups, and filters.

Import and export workflows

Import Markdown

Import → Markdown creates a new page per file. Relative links between files become broken unless you import a zip of a folder structure Notion understands.

Best practices:

  • Import one page at a time for critical docs.
  • Fix image paths immediately after import.
  • Re-apply callouts and toggles manually where conversion flattened them.

Export Markdown & CSV

Settings → Export → Markdown & CSV produces a zip of .md files mirroring the page tree.

Known export quirks:

Notion featureExport result
CalloutsQuoted text + emoji, usually
TogglesHeading + indented content
ColumnsLinearized — layout lost
DatabasesSeparate CSV + stub Markdown page
CommentsNot included
@mentionsPlain text or user IDs
EmbedsLink URL only

If you need clean Markdown for Hugo, Docusaurus, or GitHub, export from your source repo, not from Notion — treat Notion as the editing UI, not the source of truth.

Sync with Git (advanced)

Teams that need both Notion's UX and Git's portability use:

  • Notion API scripts to push/pull page content (Markdown-ish conversion via API).
  • Third-party sync tools (evaluate security before connecting production workspaces).
  • Manual cadence — weekly export for docs that rarely change.

For automated transforms (HTML ↔ Markdown, frontmatter extraction), see the Markdown API and API quickstart.

Slash commands power users use daily

CommandPurpose
/tocTable of contents from headings
/codeFenced code block
/equationLaTeX math block
/calloutHighlighted callout
/toggleCollapsible section
/templateReusable block patterns
/mentionLink people or pages
/dateDate with reminders
/embedExternal iframe content

Slash commands are Notion-only — they do not exist in exported Markdown.

Notion vs. standard Markdown (cheat sheet)

SyntaxStandard MDNotion typingNotion paste
**bold**✅✅✅
*italic*✅✅✅
~~strike~~✅ (GFM)✅✅
[text](url)✅⚠️✅ often
![alt](url)✅⚠️✅ if remote
# H1✅✅✅
#### H4✅❌⚠️ flattens
GFM tables✅⚠️✅ often
> [!NOTE] alerts✅ (GFM)❌❌
[[wikilink]]✅ (Obsidian)❌❌
YAML frontmatter✅❌❌
HTML <div>✅❌❌
Mermaid fenced blocks✅ (GFM)❌ native❌

Common Notion Markdown mistakes

1. Treating Notion as the canonical .md repo. Export surprises are inevitable — keep Git as source of truth for developer docs.

2. Typing link syntax instead of Cmd+K. [docs](url) in a paragraph often stays literal.

3. Expecting H4–H6. Use toggles or bold lines instead.

4. Pasting Obsidian wikilinks. [[Page]] does not become an internal Notion link — convert to @Page mentions manually.

5. Huge Markdown tables. Notion performance degrades past ~100 rows; link to a database or external sheet.

6. Relying on export for code docs. Fenced language tags usually survive, but callout semantics and embeds do not.

7. Local image paths in pasted Markdown. Always use uploaded Notion assets or HTTPS URLs.

Workflow: write in Markdown, publish to Notion

A portable pipeline many teams use:

  1. Draft in the Markdown editor with live GFM preview.
  2. Lint structure with the GFM checklist and heading audit.
  3. Copy rendered sections or raw Markdown into Notion pages.
  4. Enhance in Notion with databases, mentions, and callouts.
  5. Export only for backups — not for primary publishing.

For HTML-heavy legacy content, convert with HTML to Markdown before step 1.

Preview before you paste

Paste your draft into the Markdown editor first. If the preview looks correct in GFM, Notion will usually accept the block-level structure on paste — even when Notion's own typing rules would not have produced the same result.

Differences to expect:

  • Notion underline/highlight has no Markdown equivalent.
  • GFM task lists and Notion to-dos align closely.
  • Mermaid diagrams must be screenshots or embeds in Notion — they will not render from a fenced mermaid block.

Quick reference

Syntax / actionPurpose
# H1 ## H2 ### H3Headings (H4+ not supported)
**bold** *italic* ~~strike~~Inline styles
`inline code`Inline code
Triple-backtick + language tagCode block
- bullet / 1. numberedLists
- [ ] / - [x]To-do items
> quoteQuote block
---Divider
Pipe tablePaste GFM tables
/equationLaTeX block
Ctrl/Cmd+KLink selected text
/embed /callout /toggleNotion-only blocks

Notion rewards people who learn both Markdown shortcuts and block semantics. Master the paste workflow, keep a portable source copy, and you get collaboration without locking your words in a single app.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.