Notion sync via Markdown API
Definitie
Notion biedt naast de klassieke block-level API ook een Markdown API waarmee een hele pagina in een enkele call gelezen of geschreven kan worden. Voor markdown-first workflows is dit substantieel efficienter dan de blocks API, die pagineert op 50 blocks per request en nested content apart moet ophalen.
Context
Bij het integreren van een lokale Obsidian of markdown-based vault met Notion is de standaardroute via Notion MCP met blocks API. Die route kost dozijnen API calls voor een complexe pagina: pagineren door blocks, losse fetches voor nested children, batched writes van 100 blocks per call met nesting limits. Voor een vault die honderden tot duizenden pages wil syncen is dat onhoudbaar. De Markdown API, een toevoeging aan Notion’s publieke API, doet hetzelfde werk in 2-4 calls ongeacht paginagrootte. De VegaStack plugin oss-notion-markdown-sync is een Claude Code plugin die hier specifiek op bouwt, met push, pull en two-way sync voor markdown files als primitieve operaties.
Kernpunten
Prestatieverschil
| Aanpak | Page lezen | Page schrijven | Nested content |
|---|---|---|---|
| Blocks API / Notion MCP | Paginated (50 blocks per request) plus aparte child-fetches | Batched (100 blocks per request) met nesting-limits | Extra calls per niveau |
| Markdown API | 1 call | 1 call | Meegenomen |
Wat de Markdown API wel en niet kan
De Markdown API leest en schrijft complete pagina-content als een string in GitHub Flavored Markdown. Nested pages, inline-media, tables, callouts en toggles komen mee. Wat niet direct meekomt: property-values in databases (die gaan via de reguliere properties API), collaborative comments, en bepaalde Notion-only blocks zoals inline databases.
oss-notion-markdown-sync plugin
Claude Code plugin van VegaStack die drie primitieven aanbiedt: push (lokale markdown naar Notion page), pull (Notion page naar lokale markdown), sync (two-way met conflict-detectie). Automatische conversie van GFM features die Notion niet standaard begrijpt (pipe tables, > [!NOTE] callouts, -> arrows).
YAML frontmatter koppeling
Een markdown-file met YAML frontmatter zoals status: draft, owner: jim, sprint: 3 kan als Notion database-row gepushed worden waarbij de frontmatter-velden als Notion properties verschijnen. Dit maakt eenvoudige metadata-sync mogelijk zonder een aparte mapping-laag.
Use cases waar dit glansrijk is
- PRDs en technische specs in git houden, pushen naar Notion voor team-review
- Essays of research notes lokaal schrijven, publiceren als Notion page voor samenwerking
- Complete Notion database pullen naar een markdown-folder voor AI-bewerking of backup
- GitHub Actions schedule die Notion workspaces nachtelijk naar een backup-branch pullt
Wanneer de blocks API beter is
- Property-only updates (status wijzigen, tag toevoegen): blocks API is precieser
- Programatisch blocks manipuleren (bijv. specifieke toggles openen of comments plaatsen)
- Relations tussen database-rows beheren: alleen via reguliere API, niet via markdown
Verbanden
- Zie ook: wiki-bidirectional-knowledge-sync
- Zie ook: wiki-vault-mcp-architectuur
- Zie ook: wiki-karpathy-llm-wiki
Bronnen
- Notion. (2024). Working with markdown content. Notion Developer Documentation. https://developers.notion.com/guides/data-apis/working-with-markdown-content
- VegaStack. (2026). oss-notion-markdown-sync [GitHub repository]. https://github.com/VegaStack/oss-notion-markdown-sync