Notion Sync

Bi-directional sync between markdown files and Notion pages, plus database management utilities for research tracking and project management.

Upgrading

From v2.0: Replace --token "ntn_..." with --token-file, --token-stdin, or NOTION_API_KEY env var. Bare --token is no longer accepted (credentials should never appear in process listings).

From v1.x: See v2.0 changelog for migration details.

Requirements

• - Node.js v18 or later
• A Notion integration token (starts with ntn_ or secret_)

Setup

1. 1. Go to https://www.notion.so/my-integrations
2. Create a new integration (or use an existing one)
3. Copy the "Internal Integration Token"
4. Pass the token using one of these methods (priority order used by scripts):

Option A — Token file (recommended):
CODEBLOCK0

Option B — Stdin pipe:
CODEBLOCK1

Option C — Environment variable:
CODEBLOCK2

Auto default: If ~/.notion-token exists, scripts use it automatically even without --token-file.

1. 5. Share your Notion pages/databases with the integration:

- Open the page/database in Notion - Click "Share" → "Invite" - Select your integration

JSON Output Mode

All scripts support a global --json flag.

• - Suppresses progress logs written to stderr
• Keeps stdout machine-readable for automation
• Errors are emitted as JSON: INLINECODE10

Example:
CODEBLOCK3

Path Safety Mode

Scripts that read/write local files are restricted to the current working directory by default.

• - Prevents accidental reads/writes outside the intended workspace
• Applies to: md-to-notion.js, add-to-database.js, notion-to-md.js, INLINECODE14
• Override intentionally with INLINECODE15

Examples:
CODEBLOCK4

Core Operations

1. Search Pages and Databases

Search across your Notion workspace by title or content.

CODEBLOCK5

Examples:
CODEBLOCK6

Output:
CODEBLOCK7

2. Query Databases with Filters

Query database contents with advanced filters and sorting.

CODEBLOCK8

Examples:
CODEBLOCK9

Common filter patterns:

• - Select equals: INLINECODE16
• Multi-select contains: INLINECODE17
• Date after: INLINECODE18
• Checkbox is true: INLINECODE19
• Number greater than: INLINECODE20

3. Update Page Properties

Update properties for database pages (status, tags, dates, etc.).

CODEBLOCK10

Supported types: select, multiselect, checkbox, number, url, email, date, richtext

Examples:
CODEBLOCK11

4. Batch Update

Batch update a single property across multiple pages in one command.

Mode 1 — Query + Update:
CODEBLOCK12

Example:
CODEBLOCK13

Mode 2 — Page IDs from stdin:
CODEBLOCK14

Features:

• - --dry-run: prints pages that would be updated (with current property value) without writing
• INLINECODE22: max pages to process (default 100)
• Pagination in query mode (has_more/next_cursor) up to limit
• Rate-limit friendly updates (300ms between page updates)
• Progress and summary on stderr, JSON result array on stdout

5. Markdown → Notion Sync

Push markdown content to Notion with full formatting support.

CODEBLOCK15

Example:
CODEBLOCK16

Supported formatting:

• - Headings (H1-H3)
• Bold/italic text
• Links
• Bullet lists
• Code blocks with syntax highlighting
• Horizontal dividers
• Paragraphs

Features:

• - Batched uploads (100 blocks per request)
• Automatic rate limiting (350ms between batches)
• Rich text is automatically chunked to Notion's 2000-character limit (including bold/italic/link spans)
• Returns Notion page URL and ID

Output:
CODEBLOCK17

6. Notion → Markdown Sync

Pull Notion page content and convert to markdown.

CODEBLOCK18

Example:
CODEBLOCK19

Features:

• - Converts Notion blocks to markdown
• Preserves formatting (headings, lists, code, quotes)
• Optional file output (writes to file or stdout)

7. Change Detection & Monitoring

Monitor Notion pages for edits and compare with local markdown files.

CODEBLOCK20

Example:
CODEBLOCK21

State tracking: By default maintains state in memory/notion-watch-state.json (relative to current working directory). You can override with --state-file <path> (supports ~ expansion):

CODEBLOCK22

Default state schema:
CODEBLOCK23

Output:
CODEBLOCK24

Automated monitoring: Schedule periodic checks using cron, CI pipelines, or any task scheduler:
CODEBLOCK25

The script outputs JSON — pipe it to any notification system when hasChanges is true.

8. Database Management

Add Markdown Content to Database

Add a markdown file as a new page in any Notion database.

CODEBLOCK26

Examples:
CODEBLOCK27

Features:

• - Creates database page with title property
• Converts markdown to Notion blocks (headings, paragraphs, dividers)
• Handles large files with batched uploads
• Returns page URL for immediate access

Note: Additional properties (Type, Tags, Status, etc.) must be set manually in Notion UI after creation.

Inspect Database Schema

CODEBLOCK28

Example output:
CODEBLOCK29

Use when:

• - Setting up new database integrations
• Debugging property names/types
• Understanding database structure

Archive Pages

CODEBLOCK30

Note: This archives the page (sets archived: true), not permanent deletion.

Common Workflows

Collaborative Editing Workflow

1. 1. Push local draft to Notion:

CODEBLOCK31

1. 2. User edits in Notion (anywhere, any device)

1. 3. Monitor for changes:

CODEBLOCK32

1. 4. Pull updates back:

CODEBLOCK33

1. 5. Repeat as needed (update same page, don't create v2/v3/etc.)

Research Output Tracking

1. 1. Generate research locally (e.g., via sub-agent)

1. 2. Sync to Notion database:

CODEBLOCK34

1. 3. User adds metadata in Notion UI (Type, Tags, Status properties)

1. 4. Access from anywhere via Notion web/mobile

Page ID Extraction

From Notion URL: INLINECODE32

Extract: abc123-example-page-id-456def (last part after title)

Or use the 32-char format: abc123examplepageid456def (hyphens optional)

Limitations

• - Property updates: Database properties (Type, Tags, Status) must be added manually in Notion UI after page creation. API property updates can be temperamental with inline databases.
• Block limits: Very large markdown files (>1000 blocks) may take several minutes to sync due to rate limiting.
• Formatting: Some complex markdown (tables, nested lists >3 levels) may not convert perfectly.

Troubleshooting

"Could not find page" error:

• - Ensure page/database is shared with your integration
• Check page ID format (32 chars, alphanumeric + hyphens)

"Module not found" error:

• - Scripts use built-in Node.js https module (no npm install needed)
• Ensure running from the skill's directory (where scripts/ lives)

Rate limiting:

• - Notion API has rate limits (~3 requests/second)
• Scripts handle this automatically with 350ms delays between batches

Resources

scripts/

Core Sync:

• - md-to-notion.js - Markdown → Notion sync with full formatting
• notion-to-md.js - Notion → Markdown conversion
• watch-notion.js - Change detection and monitoring

Search & Query:

• - search-notion.js - Search pages and databases by query
• query-database.js - Query databases with filters and sorting
• update-page-properties.js - Update database page properties
• batch-update.js - Batch update one property across many pages (query or stdin IDs)

Database Management:

• - add-to-database.js - Add markdown files as database pages
• get-database-schema.js - Inspect database structure
• delete-notion-page.js - Archive pages

Utilities:

• - notion-utils.js - Shared utilities (error handling, property formatting, API requests)

All scripts use only built-in Node.js modules (https, fs) - no external dependencies required.

references/

• - database-patterns.md - Common database schemas and property patterns