Notion Markdown Formatting

Markdown Shortcuts While Typing

Notion converts these as soon as you type the closing character or the space, and the Markdown characters disappear: Notion keeps the formatting, not the syntax. Inline styles work anywhere in a line; block shortcuts work at the start of a new or existing block.

Inline formatting

Block shortcuts (start of a line)

Also handy: type : plus an emoji name (:apple) for the emoji picker, @ to mention a person, page, or date, and [[ to link to another page.

Keyboard Shortcuts for Formatting

For text you've already written, select it and use a shortcut. Underline, links, and colors have no Markdown shortcut, so these are the only quick way to apply them.

The same modifier pair with 0–9 turns the current block into text (0), a heading (1–3), a to-do (4), bullets (5), numbers (6), a toggle (7), a code block (8), or a page (9).

Pasting Markdown into Notion

Paste Markdown as plain text, from a code editor, a .md file, or a README, and Notion turns it into blocks. Pasting covers syntax that typing doesn't: [text](url) links, > quotes, and - [ ] task lists all convert. Notion's Help Center doesn't document paste conversion in detail, so check the result on anything long.

## Weekly update

**Shipped:** the new onboarding flow.
Docs: [release notes](https://example.com)

- [x] Fix login bug
- [ ] Write the changelog

> Ship small, ship often.

---

Headings

#, ##, and ### followed by a space create Heading 1, 2, and 3. Notion added a fourth level, Heading 4, in March 2026 (Notion 3.4); its shortcut isn't in Notion's list, so add it from the / menu or with Turn into. There is no H5 or H6: Notion's Markdown API converts them to Heading 4. Headings can also be toggle headings that fold the blocks under them. See Markdown headings for how other apps handle levels.

Quotes, Toggles, and Callouts

This catches almost everyone coming from another Markdown app. In Notion, > plus a space is the shortcut for a toggle list. A quote block comes from a double quote plus a space, or /quote. Pasted or imported Markdown follows the normal rule, and a > line there becomes a quote.

Code Blocks and Mermaid Diagrams

Type ``` at the start of a line, use /code, or paste a fenced block. Choose the language for syntax highlighting from the label at the top left of the block. Hover the block for Copy, Wrap code, and Caption.

flowchart LR
  Draft --> Review
  Review --> Publish

Math Equations

Notion renders LaTeX with KaTeX. Type $$ on both sides of an expression for an inline equation, or press Cmd/Ctrl + Shift + E to open the equation input. For a display equation on its own line, use /math (or /latex). Note the difference from GitHub and Obsidian, where $...$ is inline and $$...$$ is a block. KaTeX supports most of LaTeX plus the mhchem \ce macro for chemistry; use aligned instead of align.

Tables

There is no way to type a Markdown table in Notion. Use /table for a simple table, or create a database when you need sorting, filters, and properties. Pasting a Markdown pipe table is reported to work by some and to arrive as plain text by others; importing the .md file is the dependable route. To build a table quickly, try the Markdown table generator, and for spreadsheet data, import a CSV: it becomes a Notion database with columns as properties.

Importing Markdown Files

Go to Settings → Import → Text & Markdown, or type / on a page and search for the importer. Imports run on desktop and web, not mobile.

Exporting Notion to Markdown

Open the ••• menu at the top right of a page, choose Export, and pick Markdown & CSV. Turn on Include subpages to export nested pages too. You download a zip file.

• Each page becomes a .md file; a full-page database becomes a CSV plus a .md file per database page.
• Callouts are written as HTML, since Markdown has no equivalent.
• For a database, you can export the current view or the default view, not all views.
• If Windows can't open the zip because of long file paths, turn off Create folders for subpages or extract with 7-Zip.
• To export everything: Settings → General → Export all workspace content. The download link arrives by email and expires after 7 days. Enterprise admins can disable exports.

Markdown in the Notion API

Since Notion 3.4 (March 2026), the API reads and writes page content as Markdown: POST /v1/pages accepts a markdown body, and GET / PATCH /v1/pages/:page_id/markdown read and update a page. It uses Notion's "enhanced markdown": standard Markdown plus XML-like tags for blocks Markdown can't express.

# Launch plan {color="blue"}

<callout icon="🎯" color="blue_bg">
	Ship by **Friday**.
</callout>

<details>
<summary>Open questions</summary>
	Who owns QA?
</details>

Plain text with <span underline="true">underline</span>.

Slash Commands

Type / anywhere for the block menu, then keep typing to filter it. These are the commands that map to Markdown elements, with the typing shortcut where one exists.

Common Mistakes

Most come from assuming Notion follows the same Markdown rules as GitHub or Obsidian.

Quick Reference

Every common Markdown syntax and whether Notion converts it when typed or when pasted or imported.

Frequently Asked Questions