Documentation Index
Fetch the complete documentation index at: https://developers.notion.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Enhanced markdown (also called “Notion-flavored Markdown”) is an extended Markdown format that supports all Notion block and rich text types. It is used by 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.
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"}
Lists
- Bulleted list item {color="Color"}
Children
1. Numbered list item {color="Color"}
Children
To-do
- [ ] Unchecked item {color="Color"}
Children
- [x] Checked item {color="Color"}
Children
Quote
> Rich text {color="Color"}
Children
<br> tags within a single > line:
> Line 1<br>Line 2<br>Line 3 {color="Color"}
> 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="true"} attribute:
# Heading {toggle="true" color="Color"}
Children
Callout
<callout icon="emoji" color="Color">
Rich text
Children
</callout>
Code
```language
Code content
```
```mermaid for Mermaid diagrams.
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>
false). Color precedence from highest to lowest: cell, row, column. Table cells can only contain rich text.
Divider
Empty line
Must be on its own line. Plain empty lines are stripped out.
Columns
<columns>
<column>
Children
</column>
<column>
Children
</column>
</columns>
 {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
<table_of_contents color="Color"/>
Synced block
<synced_block url="URL">
Children
</synced_block>
<synced_block_reference url="URL">
Children
</synced_block_reference>
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"/>
<mention-user url="URL"/>.
Custom emoji
Citations
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> |
