skills.rest
SpillwaveSolutions
SpillwaveSolutionsOFFICIAL
Explore all skills by this author →
WebsiteGitHub

notion-uploader-downloader

Synchronizes Markdown files with Notion pages and databases bidirectionally.

5|2|Updated Nov 9, 2025
Search Tags:#automation#markdown#notion#images#download#upload
One-click install
npx skills add https://github.com/SpillwaveSolutions/notion_uploader_downloader --skill notion-uploader-downloader
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: notion-uploader-downloader
Source: https://github.com/SpillwaveSolutions/notion_uploader_downloader/tree/main/.
Command: npx skills add https://github.com/SpillwaveSolutions/notion_uploader_downloader --skill notion-uploader-downloader

SYSTEM DOCUMENTATION & REQUIREMENTS

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

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

Frequently Asked Questions about notion-uploader-downloader

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

FAQPage Schema
How do I upload Markdown files with images to Notion?▼

Upload Markdown to Notion by running `python3 scripts/notion_upload.py article.md` after setting NOTION_TOKEN and NOTION_PARENT_PAGE environment variables. The Skill converts Markdown blocks and embeds local images up to 20MB as Notion content, creating new pages or database entries.

Can I download Notion pages back to Markdown files?▼

Download Notion pages to Markdown by running `python3 scripts/notion_download.py PAGE_ID`. The Skill converts Notion blocks to Markdown, preserves formatting and tables, downloads images locally, and supports recursive downloads of entire page hierarchies with YAML frontmatter.

What's the best way to keep Markdown and Notion in sync?▼

Bidirectional sync combines uploading Markdown changes to Notion and downloading Notion pages back to Markdown with YAML frontmatter and mapping files. This enables round-trip synchronization without manual copy-paste between tools.

Do I need any special setup or credentials to use Markdown-Notion sync?▼

Yes. Install dependencies via `pip install -r scripts/requirements.txt`, then create a `.env.notion` file or set NOTION_TOKEN and NOTION_PARENT_PAGE environment variables. The Skill uses these credentials to authenticate with the Notion API.

Can I append new content to an existing Notion page without overwriting it?▼

Yes. The Skill supports appending Markdown content to the end of existing Notion pages, preserving all prior content. This enables incremental updates without replacing the full page structure.

What image file sizes and formatting does Notion sync support?▼

Markdown-Notion sync handles images up to 20MB and preserves rich formatting including tables, headings, and inline styles. The Skill manages local image storage during download and uploads embedded images from Markdown files.

Related Skills

Explore More Software Engineering Skills→
n0rvynn0rvyn
1

notion-with-api

Search, read, create, and update Notion pages and databases via API.

Community
Advanced
hmzainjamilhmzainjamil
1

notion-automation

Automate Notion database updates, page creation, and workflow syncs.

Community
Advanced
bish-xbish-x
2

frontmatter-guard

Validate and repair YAML frontmatter in Markdown brain pages.

Community
Intermediate
vm0-aivm0-ai
76

notion

Manage Notion pages, databases, and blocks via the REST API.

Official
Intermediate