Enhanced markdown format

Overview

Enhanced markdown is an extended Markdown format that supports all Notion block and rich text types. It is the default format (markdown_version: "v1") for the markdown content endpoints: POST /v1/pages (via the markdown body param), GET /v1/pages/:page_id/markdown, and PATCH /v1/pages/:page_id/markdown. See Markdown versions for the v2 preview. This format extends standard Markdown with XML-like tags and attribute lists to represent Notion-specific features such as callouts, toggles, columns, mentions, and block-level colors.

Indentation

Use tabs for indentation. Child blocks are indented one tab deeper than their parent.

Escaping

Use backslashes to escape special characters. The following characters should be escaped outside of code blocks: \ * ~ ` $ [ ] < > { } | ^ Do not escape characters inside code blocks. Code block content is literal.

Block types

Text

Rich text {color="Color"}
	Children

Headings

# Heading 1 {color="Color"}
## Heading 2 {color="Color"}
### Heading 3 {color="Color"}
#### Heading 4 {color="Color"}

Headings do not support children. Headings 5 and 6 are converted to heading 4.

Lists

- Bulleted list item {color="Color"}
	Children

1. Numbered list item {color="Color"}
	Children

List items should contain inline rich text. Other block types render as children of an empty list item.

To-do

- [ ] Unchecked item {color="Color"}
	Children
- [x] Checked item {color="Color"}
	Children

Quote

> Rich text {color="Color"}
	Children

For multi-line quotes, use <br> tags within a single > line:

> Line 1<br>Line 2<br>Line 3 {color="Color"}

Multiple > lines render as separate quote blocks, not a single multi-line quote.

Toggle

<details color="Color">
<summary>Toggle title</summary>
Children (must be indented)
</details>

Toggle headings use the {toggle="true"} attribute:

# Heading {toggle="true" color="Color"}
	Children

Callout

<callout icon="emoji" color="Color">
	Rich text
	Children
</callout>

Callouts can contain multiple blocks and nested children, not just inline rich text. Each child block should be indented.

Code

```language
Code content
```

Do not escape special characters inside code blocks. Set the language if known. Use ```mermaid for Mermaid diagrams.

Equation

$$
Equation
$$

Table

<table fit-page-width="true|false" header-row="true|false" header-column="true|false">
	<colgroup>
		<col color="Color">
	</colgroup>
	<tr color="Color">
		<td color="Color">Cell content</td>
	</tr>
</table>

All attributes are optional (default to false). Color precedence from highest to lowest: cell, row, column. Table cells can only contain rich text.

Divider

---

Empty line

<empty-block/>

Must be on its own line. Plain empty lines are stripped out.

Columns

<columns>
	<column>
		Children
	</column>
	<column>
		Children
	</column>
</columns>

Media blocks

![Caption](URL) {color="Color"}

<audio src="URL" color="Color">Caption</audio>
<video src="URL" color="Color">Caption</video>
<file src="URL" color="Color">Caption</file>
<pdf src="URL" color="Color">Caption</pdf>

Page and database references

<page url="URL" color="Color">Title</page>
<database url="URL" inline="true|false" icon="Emoji" color="Color">Title</database>

<table_of_contents color="Color"/>

Synced block

<synced_block url="URL">
	Children
</synced_block>

<synced_block_reference url="URL">
	Children
</synced_block_reference>

Custom blocks

<custom-block definition-id="11111111-1111-4111-8111-111111111111" />

Use a saved definition ID from the destination workspace. The tag must be self-closing and contain exactly one definition attribute. It has no body, children, or instance binding attributes. New placements and definition changes require read access to a live definition. Instances inherit the definition’s bindings. Readback uses definition-id. Preserving the same instance and definition does not require fresh definition access. Public API and MCP requests reject definition-key; App deployments can use it to resolve a declared custom block key. See Working with markdown content.

Rich text formatting

Format	Syntax
Bold	`text`
Italic	`text`
Strikethrough	`~~text~~`
Underline	`<span underline="true">text</span>`
Inline code	`code`
Link	`[text](URL)`
Inline math	$equation$
Line break	`<br>`
Color	`<span color="Color">text</span>`

Mentions

<mention-user url="URL">User name</mention-user>
<mention-page url="URL">Page title</mention-page>
<mention-database url="URL">Database name</mention-database>
<mention-data-source url="URL">Data source name</mention-data-source>
<mention-agent url="URL">Agent name</mention-agent>
<mention-date start="YYYY-MM-DD" end="YYYY-MM-DD"/>
<mention-date start="YYYY-MM-DD" startTime="HH:mm" timeZone="IANA_TIMEZONE"/>

Self-closing format is also supported: <mention-user url="URL"/>.

Custom emoji

:emoji_name:

Citations

[^URL]

Colors

Text colors

gray, brown, orange, yellow, green, blue, purple, pink, red

Background colors

gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg

Usage

Block colors: Add {color="Color"} attribute to the first line of any block.
Inline text colors: Use <span color="Color">Rich text</span>.

Complete example

A Notion page with a heading, a callout, a to-do list, and a code block renders as:

# Project kickoff {color="blue"}

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

- [x] Write spec
- [ ] Build prototype
- [ ] Collect feedback

```python
def greet(name):
    return f"Hello, {name}!"
```

| Status | Owner |
|---|---|
| In progress | <mention-user url="{{user://abc123}}">Ada</mention-user> |

Get started

Agent APIs

API versions

Data APIs

Resources

Compliance

Link previews

Enhanced markdown format

Overview

Indentation

Escaping

Block types

Text

Headings

Lists

To-do

Quote

Toggle

Callout

Code

Equation

Table

Divider

Empty line

Columns

Media blocks

Page and database references

Table of contents

Synced block

Custom blocks

Rich text formatting

Mentions

Custom emoji

Citations

Colors

Text colors

Background colors

Usage

Complete example

​Overview

​Indentation

​Escaping

​Block types

​Text

​Headings

​Lists

​To-do

​Quote

​Toggle

​Callout

​Code

​Equation

​Table

​Divider

​Empty line

​Columns

​Media blocks

​Page and database references

​Table of contents

​Synced block

​Custom blocks

​Rich text formatting

​Mentions

​Custom emoji

​Citations

​Colors

​Text colors

​Background colors

​Usage

​Complete example

Overview

Indentation

Escaping

Block types

Text

Headings

Lists

To-do

Quote

Toggle

Callout

Code

Equation

Table

Divider

Empty line

Columns

Media blocks

Page and database references

Table of contents

Synced block

Custom blocks

Rich text formatting

Mentions

Custom emoji

Citations

Colors

Text colors

Background colors

Usage

Complete example