Repository navigation
Home
notion-md-sync keeps a folder of Markdown files and a tree of Notion pages in step. You can pull Notion pages down as Markdown, edit them in any editor, and push the changes back. Block IDs, comments and links on unchanged blocks survive the round trip.
| Page | What's in it |
|---|---|
| Installation | Install scripts, release binaries, building from source, shell completion |
| Configuration | Notion integration setup, init, config.yaml, .env and environment variables |
| Commands | Every command and flag: pull, push, sync, add, reset, status, watch, verify, tui
|
| Directory Layout and Kept Blocks | How pages map to Folder/Folder.md, how new files find their parent page, and the <!-- notion:... --> markers |
| Markdown Support | Frontmatter fields and the Markdown syntax that converts to Notion blocks |
| Databases | How databases are exported to CSV on pull |
| Troubleshooting | Common errors and known quirks |
| Development | Building, testing and releasing |
Every page under your configured parent page becomes Page Name/Page Name.md, with its sub-pages in sub-folders. Each file records its page in a notion_id frontmatter field, so you can move or rename files freely. On push, the tool compares your Markdown with the blocks already in Notion and only touches what changed: edited blocks are updated in place, new ones inserted, removed ones deleted. Sub-pages, databases and blocks that Markdown can't express are never deleted. They show up in your file as <!-- notion:TYPE ID --> marker lines.
The client talks to the Notion API version 2026-03-11.