Two-way markdown sync for Notion
npx claudepluginhub vegastack/oss-notion-markdown-syncTwo-way markdown sync for Notion — push, pull, and round-trip local markdown files with Notion pages via the Markdown API. Auto-detects GFM vs Notion format, handles media uploads/downloads, icon replication, and database page properties.
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.
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.
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
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/
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
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
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
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.
Directory of popular Claude Code extensions including development tools, productivity plugins, and MCP integrations
No description available.
Curated collection of 154 specialized Claude Code subagents organized into 10 focused categories