notion-md-upload-skill

name	notion-md-upload-skill
description	Upload local Markdown files to Notion pages or databases. Supports local images (auto-uploaded), batch upload of directories, and the new Notion markdown API. Use when user wants to upload .md files to Notion, or mentions "upload markdown to notion", "上传md到Notion", "本地笔记上传Notion".

Notion Markdown Upload

Upload local Markdown files to Notion. Uses the Notion 2026-03-11 API with native markdown support — no block conversion needed.

Prerequisites

1. Notion API Key: Create an integration at https://notion.so/my-integrations
2. Store the key:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

3. Share target database/page with your integration (click "..." → "Connect to" → your integration name)

First Time Setup

Dependencies are auto-installed when the script runs. No manual setup needed.

Agent Execution Instructions

CRITICAL: Always use the command pattern below. It auto-installs dependencies on first run.

1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Command pattern:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <args>)

3. Replace ${SKILL_DIR} with the actual path

Usage

# Upload single .md file to a page
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts notes.md --page <page_id_or_url>)

# Upload to a database by name
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts notes.md --database-name "Knowledge Base")

# Upload all .md files in a directory
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts ./docs/ --page <page_id>)

# Specify custom title
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts notes.md --page <page_id> --title "My Notes")

# List accessible databases
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts --list-databases)

Options

Option	Description
<file.md|dir>	Markdown file or directory containing .md files
--page, -p <id|url>	Parent page ID or Notion URL
--database, -d <id>	Target database by ID
--database-name, -n <name>	Target database by name
--title, -T <title>	Custom page title (default: filename)
--list-databases, -l	List accessible databases and exit

Image Handling

• URL images (![](https://...)) are included as-is in the markdown
• Local images (![](./image.png)) are automatically uploaded to Notion's file hosting and the paths are replaced with uploaded URLs
• Supported formats: PNG, JPG, JPEG, GIF, WebP, SVG

How It Works

1. Read: Load the local .md file
2. Images: Find local image references, upload them to Notion, replace paths
3. Upload: Create a Notion page using the new markdown API (2026-03-11)
4. The Notion API handles all markdown → block conversion server-side

Dependencies

• Node.js (script runs with tsx)
• Notion API key configured

(Other dependencies auto-install on first run.)