Markdown Support

Markdown support

Markdown written by pull converts back to the same Notion blocks on push, so a pull → push round trip changes nothing.

Frontmatter

The tool reads and writes these YAML frontmatter fields:

---
title: "My Document"          # page title; the file name is used when missing
notion_id: "1e369015-..."     # set by pull, or by the first push of a new file
created_at: "2026-11-01T18:39:00Z"
updated_at: "2026-11-03T15:38:10Z"
sync_enabled: true            # false = leave this file alone
tags: ["tag1", "tag2"]
status: "published"
---

• Don't edit notion_id by hand. It links the file to its page.
• Changing title renames the page on the next push.

Blocks

Markdown	Notion block
#, ##, ###	Heading 1–3. #### and deeper become Heading 3.
Paragraph text	Paragraph
- item / 1. item (nested too)	Bulleted / numbered list
- [ ] task / - [x] done	To-do
```lang fenced code	Code block. 70+ languages; aliases such as js and py are mapped. Newlines are kept.
| a | b | tables	Table
> quote	Quote
> 💡 text (emoji first)	Callout with that icon
<details><summary>Title</summary> … </details>	Toggle
$$ … $$	Equation (LaTeX)
	Image (external URL)
A link alone on its line	Bookmark
---	Divider

Inline formatting: bold, italic, code, strikethrough and links survive the round trip. Long text is split to fit Notion's 2000-character limit per rich-text item.

Math

$$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

Mermaid

Mermaid diagrams are code blocks with the language mermaid, and sync like any other code block.

What doesn't convert

Blocks Markdown can't express, such as columns, synced blocks, embeds, files and Notion-hosted images, are kept in Notion and shown as marker lines. See Directory Layout and Kept Blocks.