notion-uploader-downloader

What problem does it solve?

This Skill provides bidirectional synchronization between Markdown files and Notion pages, enabling upload of Markdown (with images) to Notion pages or databases, and downloading Notion content back to Markdown. It supports appending to existing pages and recursively downloading page hierarchies, dramatically reducing manual copy-paste and context-switching.

Core Features & Use Cases

• Upload Markdown to Notion: Convert Markdown files to Notion blocks and either create new pages or database entries, including local image uploads.
• Download Notion pages to Markdown: Retrieve content from Notion and convert it back to Markdown with images stored locally.
• Append to Existing Pages: Add new content to the end of an existing Notion page without overwriting existing data.
• Recursive Downloads: Download an entire page hierarchy, preserving structure and creating YAML frontmatter for round-trip syncing.
• PDA-Compliant Architecture: Tiered metadata, orchestrator, and on-demand resources to optimize token budgets and loading.

Quick Start

To begin, install dependencies, configure credentials, and run a sample workflow:

• Install: pip install -r scripts/requirements.txt
• Configure: Create and populate a .env.notion file with NOTION_TOKEN and NOTION_PARENT_PAGE (or set env vars)
• Example Upload: python3 scripts/notion_upload.py article.md
• Example Download: python3 scripts/notion_download.py PAGE_ID