notion-clipper-skill

name	notion-clipper-skill
description	Clip web pages to Notion. Fetches any URL via Chrome CDP, converts HTML to Markdown, then uploads via Notion's markdown API. Use when user wants to save/clip a webpage to Notion, or mentions "clip to notion", "save page to notion", "网页剪藏到Notion".

Notion Clipper

Clip any web page to Notion. Uses Chrome CDP for full JavaScript rendering, converts to Markdown, then uploads via Notion's 2026-03-11 markdown API.

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 (package.json in scripts/; always run lazy install first):

(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

IMPORTANT - Use this command pattern for best results:

# Recommended: Clear proxy env vars and use tsx runtime
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts <url> --database-name "Resources")

# Clip to a Notion database by NAME (recommended - searches for database)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database-name "Resource")

# Clip to a Notion database by ID
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database <database_id>)

# Clip to an existing page (creates child page)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --page <page_id>)

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

# For pages requiring login (wait mode)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database-name "Resource" --wait)

Options

Option	Description
<url>	URL to clip
--database-name, -n <name>	Target database by name (searches for match)
--database, -d <id>	Target Notion database by ID
--page, -p <id>	Target Notion page ID (creates child page)
--list-databases, -l	List all accessible databases and exit
--wait, -w	Wait for user signal before capturing
--timeout, -t <ms>	Page load timeout (default: 30000)
--no-bookmark	Don't include source link at top

Capture Modes

Mode	Behavior	Use When
Auto (default)	Capture on network idle	Public pages, static content
Wait (--wait)	User signals when ready	Login-required, lazy loading, paywalls

Wait mode workflow:

1. Run with --wait → Chrome opens, script outputs "Press Enter when ready"
2. Log in or navigate as needed in the browser
3. Press Enter in terminal to trigger capture

Output Structure

When saving to a database, creates a new page with:

• Name: Page title
• Content: Source link + converted markdown content

When saving to a page, creates a child page with:

• Source link
• Converted markdown content

Database Setup

For best results, create a Notion database with these properties:

• Name (Title) - Required, will contain page title

How It Works

1. Fetch: Launch Chrome via CDP, navigate to URL
2. Render: Wait for JavaScript to execute, scroll to trigger lazy loading
3. Extract: Run cleanup script to remove ads/nav, extract main content
4. Convert: HTML → Markdown
5. Save: Upload markdown directly via Notion's 2026-03-11 markdown API

Dependencies

• Chrome/Chromium browser (installed locally)
• Node.js (script runs with tsx)
• Notion API key configured

(Other dependencies auto-install on first run.)

Environment Variables

Variable	Description
NOTION_CLIPPER_CHROME_PATH	Custom Chrome executable path
NOTION_CLIPPER_CHROME_PROFILE_DIR	Custom Chrome profile directory

Troubleshooting

Error	Solution
ECONNREFUSED	Run unset http_proxy https_proxy all_proxy first
empty body	Use tsx runtime (NOT bun)
Chrome not found	Set NOTION_CLIPPER_CHROME_PATH
Content missing	Try --wait mode for dynamic/lazy-loaded pages
Notion API error	Ensure integration has access to target database/page