notion-enhanced-markdown

name	notion-enhanced-markdown
description	Reference for Notion-flavored Markdown used by notionary's markdown endpoints. Use this when writing content for POST /v1/pages, GET/PATCH /v1/pages/:id/markdown.

Notion Enhanced Markdown

Notion-flavored Markdown extends standard Markdown with XML-like tags and attribute lists. Used by notionary when creating or updating Notion pages via markdown endpoints.

Core Rules

• Indentation: Use tabs for child blocks (not spaces)
• Escaping: Backslash-escape outside code blocks: \ * ~ \ $ [ ] < > { } | ^`
• Code blocks: Never escape inside — content is literal
• Empty lines: Use <empty-block/> — plain blank lines are stripped

Block Types

Text & Headings

Plain paragraph text {color="blue"}

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

Headings have no children. H5/H6 → H4.

Lists

- Bullet item {color="Color"}
    Child block (tab-indented)

1. Numbered item
    Child block

- [ ] Unchecked todo
- [x] Checked todo

Quote & Divider

> Single line quote {color="gray"}
> Line 1<br>Line 2<br>Line 3

---

Multiple > lines = separate quote blocks, not one multi-line quote.

Toggle

<details color="gray_bg">
<summary>Toggle title</summary>
    Child content (tab-indented)
</details>

# Heading {toggle="true"}
    Children

Callout

<callout icon="💡" color="yellow_bg">
    Main callout text
    More child blocks (tab-indented)
</callout>

Code & Equation

```python
def hello(): pass
```

$$
E = mc^2
$$

Inline: $x^2 + y^2$

Table

<table fit-page-width="true" header-row="true" header-column="false">
    <colgroup>
        <col color="gray_bg">
        <col>
    </colgroup>
    <tr>
        <td color="blue_bg">Header</td>
        <td>Cell</td>
    </tr>
</table>

Color precedence: cell > row > column.

Columns

<columns>
    <column>
        Left content
    </column>
    <column>
        Right content
    </column>
</columns>

Media & References

![Caption](https://example.com/image.png)

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

<page     url="URL">Page Title</page>
<database url="URL" inline="true" icon="📋">DB Title</database>
<table_of_contents color="gray"/>

Inline Rich Text

Format	Syntax
Bold	**text**
Italic	*text*
Strike	~~text~~
Underline	<span underline="true">text</span>
Inline code	`code`
Link	[text](URL)
Color	<span color="red">text</span>
Line break	<br>
Citation	[^URL]
Custom emoji	:emoji_name:

Mentions

<mention-user url="notion://user/abc123">Ada</mention-user>
<mention-page url="URL">Page title</mention-page>
<mention-database url="URL">DB name</mention-database>
<mention-date start="2025-01-15" end="2025-01-20"/>
<mention-date start="2025-01-15" startTime="09:00" timeZone="Europe/Berlin"/>

Self-closing also works: <mention-user url="URL"/>.

Colors

Text: gray brown orange yellow green blue purple pink red

Background: append _bg → gray_bg, blue_bg, yellow_bg, etc.

Usage:

• Block: {color="blue_bg"} on first line of any block
• Inline: <span color="red">text</span>

Complete Example

# Project Kickoff {color="blue"}

<callout icon="🎯" color="yellow_bg">
    Ship MVP by **Friday**. See <mention-page url="URL">Spec</mention-page>.
</callout>

- [x] Write spec
- [ ] Build prototype {color="gray"}

## Notes

> Key insight:<br>Keep it simple.<br>Ship fast.

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

<table header-row="true">
    <tr>
        <td>**Status**</td>
        <td>**Owner**</td>
    </tr>
    <tr>
        <td><span color="green">Done</span></td>
        <td><mention-user url="URL">Ada</mention-user></td>
    </tr>
</table>