vegastack-oss-notion-markdown-sync

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