notion-markdown-sync
Two-way markdown sync for Notion. Push local markdown files to Notion pages, pull Notion pages to local markdown, and keep them in sync — all through the Notion Markdown API.
Built as a Claude Code plugin — works with Claude Code, Claude.ai, and Claude Cowork.
Why This Plugin
We love Notion for organizing everything. We love writing in markdown — it's fast, portable, and lives in Git. And we love how AI agents like Claude Code work with markdown natively — reading, writing, and transforming text is what they're built for.
The problem? Getting markdown in and out of Notion has always been painful.
The existing approach — tools like Notion MCP and the blocks API — works at the block level. Reading a page means paginating through blocks 50 at a time, fetching nested children separately, then reconstructing the content. Writing means batching blocks 100 at a time with nesting limitations. For a complex page, that adds up to dozens of API calls.
This plugin uses Notion's Markdown API — the entire page in a single call. A full push or pull takes 2-4 API calls regardless of whether your page is 10 lines or 10,000 lines.
| Approach | Read a page | Write it back | Nested content |
|---|
| Blocks API / Notion MCP | Paginated (50 blocks/req) + separate child fetches | Batched (100 blocks/req) + nesting limits | Extra calls per level |
| This plugin (Markdown API) | 1 call | 1 call | Included |
Claude Code + markdown is a natural fit. Instead of fighting with block-level APIs and complex SDK setups, this plugin lets you just say "push this doc to Notion" — and Claude handles the rest.
We built this at VegaStack because we sync dozens of docs between our repos and Notion daily. We open-sourced it because everyone deserves a better way to bridge markdown and Notion.
Use Cases
Publish docs from your repo to Notion
Keep your documentation in Git (where developers work) and push it to Notion (where everyone else reads it). PRDs, technical specs, architecture docs, runbooks, API references, onboarding guides — write in your editor, push to Notion.
Push docs/architecture.md to our "Engineering Wiki" database in Notion
Push the PRD at docs/prd-user-auth.md to Notion under the Product Specs page
Push all markdown files in docs/runbooks/ to the "Runbooks" database
Pull Notion pages to local markdown
Download any Notion page as a clean markdown file. Edit in VS Code or Cursor, diff changes in Git, feed into Claude Code for analysis, or use as context for AI-assisted development.
Pull https://notion.so/My-Wiki-abc123 to local markdown at wiki/
Pull our API reference page from Notion to docs/api-reference.md
Pull the "Product Roadmap" database — save each page as a separate markdown file in docs/roadmap/
Keep PRDs and specs in sync
Write a PRD, technical spec, or RFC locally, push to Notion for team review. Product and engineering collaborate in Notion, developers pull changes back to their repo. The sync metadata tracks what changed and where.
Sync docs/prd-user-auth.md with Notion
Sync docs/rfc-new-api.md — check if Notion version has changes from the team
Convert GitHub-Flavored Markdown for Notion
Have existing docs from GitHub repos, Claude Code plans, or other markdown tools with pipe tables, -> arrows, > [!NOTE] callouts? The plugin auto-detects and converts them to Notion's format — no manual reformatting.
Push README.md to Notion — it has GFM tables and callouts
Push my Claude Code plan at docs/plans/migration-plan.md to Notion for team review
Manage Notion database pages from your editor
Push project docs to a Notion database — each file becomes a page with properties like Status, Owner, Sprint, and Priority managed from YAML frontmatter.
Push docs/features/ to the "Product Roadmap" database in Notion
Update the Status to "Done" and add tag "v2.1" for docs/features/dark-mode.md and push to Notion
Bonus: automated Notion backups
Since this plugin produces clean markdown files, you can combine it with Git and CI/CD for automated Notion backups. Pair with a nightly GitHub Action that pulls your critical Notion databases to a notion-backup/ branch — instant version history for your entire workspace. No more worrying about accidental deletions or workspace issues.
Features
vegastack
