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 |
|---|---|
# Heading | Heading 1 |
## Heading | Heading 2 |
### Heading | Heading 3 |
- item or * item | Bulleted list |
1. item | Numbered list |
[] or [ ] | To-do (unchecked) |
[x] | To-do (checked) |
> quote | Quote 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
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):
| Action | Windows / Linux | macOS |
|---|---|---|
| Bold | Ctrl+B | Cmd+B |
| Italic | Ctrl+I | Cmd+I |
| Strikethrough | Ctrl+Shift+S | Cmd+Shift+S |
| Inline code | Ctrl+E | Cmd+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.
Links
Typed links: Notion does not reliably convert [label](https://example.com) while you type in a normal paragraph. Use one of these instead:
- Paste Markdown that already contains links — conversion often works.
- Select text →
Ctrl/Cmd+Kand paste the URL. - Bare URL — Notion auto-links
https://example.com. - Slash command
/linkon 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:
| Type | Typical use |
|---|---|
| 💡 Note | Neutral context |
| ⚠️ Warning | Caution, breaking changes |
| ❗ Important | Must-read detail |
| ✅ Success | Confirmations, 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
/codefor 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:

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:
- Keep canonical content in Git as
.mdfiles. - Mirror summaries in a Notion database with a URL property linking to the repo file.
- 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 feature | Export result |
|---|---|
| Callouts | Quoted text + emoji, usually |
| Toggles | Heading + indented content |
| Columns | Linearized — layout lost |
| Databases | Separate CSV + stub Markdown page |
| Comments | Not included |
@mentions | Plain text or user IDs |
| Embeds | Link 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
| Command | Purpose |
|---|---|
/toc | Table of contents from headings |
/code | Fenced code block |
/equation | LaTeX math block |
/callout | Highlighted callout |
/toggle | Collapsible section |
/template | Reusable block patterns |
/mention | Link people or pages |
/date | Date with reminders |
/embed | External iframe content |
Slash commands are Notion-only — they do not exist in exported Markdown.
Notion vs. standard Markdown (cheat sheet)
| Syntax | Standard MD | Notion typing | Notion paste |
|---|---|---|---|
**bold** | ✅ | ✅ | ✅ |
*italic* | ✅ | ✅ | ✅ |
~~strike~~ | ✅ (GFM) | ✅ | ✅ |
[text](url) | ✅ | ⚠️ | ✅ often |
 | ✅ | ⚠️ | ✅ 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:
- Draft in the Markdown editor with live GFM preview.
- Lint structure with the GFM checklist and heading audit.
- Copy rendered sections or raw Markdown into Notion pages.
- Enhance in Notion with databases, mentions, and callouts.
- 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
mermaidblock.
Related articles
- HTML to Markdown guide — clean up Notion exports for Git
- Obsidian Markdown guide — wikilinks, callouts, and vault workflows
- GitHub README guide — structure and templates for repo front pages
- Markdown cheat sheet — every standard feature on one page
- Markdown table guide — build tables before pasting into Notion
- Best Markdown editors — where Notion fits in the landscape
Quick reference
| Syntax / action | Purpose |
|---|---|
# H1 ## H2 ### H3 | Headings (H4+ not supported) |
**bold** *italic* ~~strike~~ | Inline styles |
`inline code` | Inline code |
| Triple-backtick + language tag | Code block |
- bullet / 1. numbered | Lists |
- [ ] / - [x] | To-do items |
> quote | Quote block |
--- | Divider |
| Pipe table | Paste GFM tables |
/equation | LaTeX block |
| Ctrl/Cmd+K | Link selected text |
/embed /callout /toggle | Notion-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.
Master Markdown in Microsoft Teams — chat compose formatting, the differences from GitHub GFM, Adaptive Card markdown, and incoming-webhook message formatting for bots and CI.
Every WhatsApp formatting trick — bold, italic, strikethrough, monospace, bulleted and numbered lists, block quotes, and inline code — plus what breaks when you paste from elsewhere.
Complete Telegram formatting guide — MarkdownV2 vs legacy Markdown vs HTML parse modes, the full escaping rules, spoilers, custom emoji, and in-app shortcuts that actually work.