Notion Uploader Downloader

Notion Markdown Sync

Bidirectional synchronization between Markdown files and Notion pages with automatic image handling and rich formatting support.

Features

✅ **Upload to Notion**

• Convert markdown files to Notion pages or database entries
• Automatic local image upload (up to 20MB per file)
• Preserve all formatting: bold, italic, code, strikethrough, underline, links
• Support for tables, code blocks (with syntax highlighting), task lists, callouts
• GitHub-flavored markdown extensions (callouts, task lists)
• Mermaid diagram preservation

✅ **Download from Notion**

• Convert Notion pages back to markdown
• Download images to local storage
• Preserve formatting and structure
• Support for all major Notion block types

✅ **Recursive Download** (NEW in v2.1)

• Download a page AND all its child pages recursively
• Create folder structure matching Notion hierarchy
• YAML frontmatter with page metadata (notion_id, title, timestamps)
• Strict file naming (lowercase, underscores, no special chars)
• Generate mapping.json for round-trip sync

✅ **Append to Existing Pages**

• Add content to existing Notion pages or database entries
• Preserves existing content (appends at the end)
• Works with both regular pages and database entries

Quick Start

1. Installation

pip install -r scripts/requirements.txt

2. Get Notion Token

1. Go to Notion Integrations
2. Create a new integration
3. Copy the Internal Integration Token
4. Create .env.notion file:

   echo "NOTION_TOKEN=ntn_your_token_here" > .env.notion

3. Share Pages with Integration

• Open your Notion page
• Click "..." → "Add connections" → Select your integration
• Repeat for any pages/databases you want to access

Usage

Upload Markdown to Notion

**Upload to default Articles page:**

python3 scripts/notion_upload.py article.md --parent-id 2a5d6bbdbbea8089bf5cc5afdc1cabd0

**Up