notion-md-sync

Batch upload local Markdown files to Notion via the Notion API.

Updated Nov 17, 2025

Search Tags:#automation #markdown #python #notion #upload #notion-api

Ready to run

npx skills add https://github.com/waleking/weijing_claude_skills --skill notion-md-sync

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: notion-md-sync
Source: https://github.com/waleking/weijing_claude_skills/tree/main/notion-md-sync
Command: npx skills add https://github.com/waleking/weijing_claude_skills --skill notion-md-sync

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires requests, and includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill enables batch uploading of local Markdown files to Notion via a Python script, avoiding Notion MCP/LMM token costs and preserving formatting for large docs.

Core Features & Use Cases

Zero-token upload: Direct Notion API calls without LLM parsing for Markdown content.
Batch processing: Upload single or multiple files efficiently.
Preserves formatting: Tables, code blocks, links, and rich text remain intact.
Use Case: Convert an entire Markdown-based docs repo into a Notion page hierarchy without token overhead.

Quick Start

Use the notion-md-sync script to upload your Markdown file(s) to Notion. Example: python3 scripts/sync_md_to_notion.py report.md

Frequently Asked Questions about notion-md-sync

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I upload Markdown files to Notion without using tokens?▼

Markdown uploads to Notion can be done with zero-token cost by using direct Notion API calls instead of LLM parsing. This Skill batch-uploads local Markdown files via Python script, authenticating with NOTION_TOKEN and converting Markdown formatting—tables, code blocks, links, bold text—directly into Notion blocks without token overhead.

Can I upload multiple Markdown files to Notion at once?▼

Yes, batch processing is supported for single or multiple Markdown files. The script auto-detects the target parent page, converts all files to Notion blocks, and performs chunked uploads up to 100 blocks per request, making large-scale migrations efficient.

What Markdown formatting is preserved when uploading to Notion?▼

Tables, code blocks, headings, lists, links, bold text, and inline code are all preserved during upload. The Python script converts these elements into native Notion blocks, maintaining document structure and formatting fidelity without loss.

How do I authenticate the script to upload to my Notion workspace?▼

Authentication uses a NOTION_TOKEN environment variable. Set this token in your environment, then run the sync script with your Markdown file as an argument—for example, `python3 scripts/sync_md_to_notion.py report.md`—and the script handles API authentication and uploads automatically.

Is this better than using Notion's built-in import for Markdown docs?▼

This approach avoids LLM token costs by calling the Notion API directly, making it ideal for batch uploads and large documentation repos. It preserves formatting reliably and scales efficiently with chunked uploads, offering cost savings and consistent results compared to standard import methods.

What are the limitations when uploading Markdown to Notion?▼

Uploads are chunked at 100 blocks per request, so very large single files are split across multiple API calls. The script requires valid NOTION_TOKEN credentials and relies on the Notion API's block structure, which may not support every custom Markdown extension or edge-case formatting.