# Notion as Code Markdown

Use standard Markdown plus these Notion-specific forms in page `content`,
custom-agent `instructions`, and `APP.md`.

## Resource references

Mention declarations by resource ID, not a Notion URL or UUID. Keep the `url`
attribute; there is no `resourceId` Markdown attribute. Use ordinary Markdown
links for external URLs.

```text
See <mention url="guide">Guide</mention>.
Use <mention url="issues-source" type="data-source">Issues</mention>.
Ask <mention url="analyst" type="agent">Analyst</mention>.
```

Use a page or database handle's `resourceId` for page mentions. For a data source
or agent, use its handle's `resourceId` and the corresponding type above.
`type="database"` denotes a database container. User mentions are not available
through Notion as Code resource references.

Child pages and linked database views use block tags:

```text
<page url="guide">Guide</page>

<database url="issues-table" data-source-url="issues-source" inline="true">Issues</database>
```

Declare pages, databases, and views with the SDK helpers, not Markdown.

## Containers and formatting

Put a container's title in its body, not a `title` attribute. Separate the title
from children with a blank line; do not pad the opening or closing tags.

```text
<callout icon="💡" color="blue_bg">
Review the queue daily.

- Assign an owner.
</callout>

<toggle heading="h2">
Details

More context here.
</toggle>
```

- `<columns>` contains `<column ratio="50">...</column>` blocks.
- Colors are `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`,
  `pink`, and `red`; add `_bg` for backgrounds.
- Use `<span color="orange">text</span>` for inline color and `<u>text</u>`
  for underline. `<b>`, `<i>`, and `<s>` preserve edge whitespace.
- Dates use `<date start="2026-09-30" />`; ranges add `end`, and times add
  `start-time`, `end-time`, and `time-zone` (an IANA timezone).
- Custom emoji use `:smile:`. `<p />` creates an empty paragraph.
- Citations use `[^URL]`. Display math uses bare `$$` lines around the equation.
- Outside Notion Markdown tags and fenced code, write literal `<` and `>` characters as `&lt;` and `&gt;`.
  For example, write `x &lt; 5` or `&lt;tag&gt;`.
  Keep the `<` and `>` characters in Notion Markdown tags unchanged.
  Arbitrary HTML such as `<div>` and `<details>` is not Notion Markdown.

## Media and tables

Media tags use `source`, with captions in the body:

```text
<image source="https://example.com/image.png" color="blue_bg">Caption</image>
<pdf source="https://example.com/guide.pdf">Caption</pdf>
```

The same shape applies to `<file>`, `<audio>`, `<video>`, `<bookmark>`, and
`<embed>`. Images must be standalone blocks. Use `<embed>` for HTML embeds.

Use pipe tables for plain tables. Styled tables use `<table header-row="true">`
with `<tr>`, `<th>`, and `<td color="green_bg">` cells. Cells contain inline text;
use `<br />` for line breaks. Do not mix pipe and tag forms in one table.