notion-md-sync

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.

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.

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.

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.

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.

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.