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

Go to https://www.notion.so/my-integrations
Create a new integration (or use an existing one)
Copy the "Internal Integration Token"

Pass the token using one of these methods (priority order used by scripts):

Option A — Token file (recommended):

echo "ntn_your_token" > ~/.notion-token && chmod 600 ~/.notion-token
node scripts/search-notion.js "query" --token-file ~/.notion-token

Option B — Stdin pipe:

echo "$NOTION_API_KEY" | node scripts/search-notion.js "query" --token-stdin

Option C — Environment variable:

export NOTION_API_KEY="ntn_your_token"
node scripts/search-notion.js "query"

Auto default: If

~/.notion-token

exists, scripts use it automatically even without

--token-file

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:
```
{ "error": "..." }
```

Example:

node scripts/query-database.js <db-id> --limit 5 --json

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

watch-notion.js

Override intentionally with
```
--allow-unsafe-paths
```

Examples:

# Default (safe): path must be inside current workspace
node scripts/md-to-notion.js docs/draft.md <parent-id> "Draft"
Intentional override (outside workspace)
node scripts/notion-to-md.js <page-id> ~/Downloads/export.md --allow-unsafe-paths

Core Operations

1. Search Pages and Databases

Search across your Notion workspace by title or content.

node scripts/search-notion.js "<query>" [--filter page|database] [--limit 10] [--json]

Examples:

# Search for newsletter-related pages
node scripts/search-notion.js "newsletter"
Find only databases
node scripts/search-notion.js "research" --filter database
Limit results

node scripts/search-notion.js "AI" --limit 5

Output:

[
  {
    "id": "page-id-here",
    "object": "page",
    "title": "Newsletter Draft",
    "url": "https://notion.so/...",
    "lastEdited": "2026-02-01T09:00:00.000Z"
  }
]

2. Query Databases with Filters

Query database contents with advanced filters and sorting.

node scripts/query-database.js <database-id> [--filter <json>] [--sort <json>] [--limit 10] [--json]

Examples:

# Get all items
node scripts/query-database.js xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Filter by Status = "Complete"
node scripts/query-database.js <db-id> 

--filter '{"property": "Status", "select": {"equals": "Complete"}}'
Filter by Tags containing "AI"
node scripts/query-database.js <db-id> 

--filter '{"property": "Tags", "multi_select": {"contains": "AI"}}'
Sort by Date descending
node scripts/query-database.js <db-id> 

--sort '[{"property": "Date", "direction": "descending"}]'
Combine filter + sort
node scripts/query-database.js <db-id> 

--filter '{"property": "Status", "select": {"equals": "Complete"}}' 

--sort '[{"property": "Date", "direction": "descending"}]'

Common filter patterns:

Select equals:

{"property": "Status", "select": {"equals": "Done"}}

Multi-select contains:

{"property": "Tags", "multi_select": {"contains": "AI"}}

Date after:

{"property": "Date", "date": {"after": "2024-01-01"}}

Checkbox is true:

{"property": "Published", "checkbox": {"equals": true}}

Number greater than:

{"property": "Count", "number": {"greater_than": 100}}

3. Update Page Properties

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

node scripts/update-page-properties.js <page-id> <property-name> <value> [--type <type>] [--json]

Supported types: select, multi_select, checkbox, number, url, email, date, rich_text

Examples:

# Set status
node scripts/update-page-properties.js <page-id> Status "Complete" --type select
Add multiple tags
node scripts/update-page-properties.js <page-id> Tags "AI,Leadership,Research" --type multi_select
Set checkbox
node scripts/update-page-properties.js <page-id> Published true --type checkbox
Set date
node scripts/update-page-properties.js <page-id> "Publish Date" "2024-02-01" --type date
Set URL
node scripts/update-page-properties.js <page-id> "Source URL" "https://example.com" --type url
Set number

node scripts/update-page-properties.js <page-id> "Word Count" 1200 --type number

4. Batch Update

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

Mode 1 — Query + Update:

node scripts/batch-update.js <database-id> <property-name> <value> --filter '<json>' [--type select] [--dry-run] [--limit 100]

Example:

node scripts/batch-update.js <db-id> Status Review \
  --filter '{"property":"Status","select":{"equals":"Draft"}}' \
  --type select

Mode 2 — Page IDs from stdin:

echo "page-id-1\npage-id-2\npage-id-3" | \
  node scripts/batch-update.js --stdin <property-name> <value> [--type select] [--dry-run]

Features:

```
--dry-run
```
: prints pages that would be updated (with current property value) without writing
```
--limit <n>
```
: 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.

node scripts/md-to-notion.js \
  "<markdown-file-path>" \
  "<notion-parent-page-id>" \
  "<page-title>" [--json] [--allow-unsafe-paths]

Example:

node scripts/md-to-notion.js \
  "projects/newsletter-draft.md" \
  "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  "Newsletter Draft - Feb 2026"

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:

Parsed 294 blocks from markdown
✓ Created page: https://www.notion.so/[title-and-id]
✓ Appended 100 blocks (100-200)
✓ Appended 94 blocks (200-294)
✅ Successfully created Notion page!

6. Notion → Markdown Sync

Pull Notion page content and convert to markdown.

node scripts/notion-to-md.js <page-id> [output-file] [--json] [--allow-unsafe-paths]

Example:

node scripts/notion-to-md.js \
  "abc123-example-page-id-456def" \
  "newsletter-updated.md"

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.

node scripts/watch-notion.js "<page-id>" "<local-markdown-path>" [--state-file <path>] [--json] [--allow-unsafe-paths]

Example:

node scripts/watch-notion.js \
  "abc123-example-page-id-456def" \
  "projects/newsletter-draft.md"

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):

node scripts/watch-notion.js "<page-id>" "<local-path>" --state-file ~/.cache/notion-watch-state.json

Default state schema:

{
  "pages": {
    "<page-id>": {
      "lastEditedTime": "2026-01-30T08:57:00.000Z",
      "lastChecked": "2026-01-31T19:41:54.000Z",
      "title": "Your Page Title"
    }
  }
}

Output:

{
  "pageId": "<page-id>",
  "title": "Your Page Title",
  "lastEditedTime": "2026-01-30T08:57:00.000Z",
  "hasChanges": false,
  "localPath": "/path/to/your-draft.md",
  "actions": ["✓ No changes since last check"]
}

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

# Example: cron job every 2 hours during work hours
0 9-21/2 * * * cd /path/to/workspace && node scripts/watch-notion.js "<page-id>" "<local-path>"

The script outputs JSON — pipe it to any notification system when

hasChanges

true

8. Database Management

Add Markdown Content to Database

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

node scripts/add-to-database.js <database-id> "<page-title>" <markdown-file-path> [--json] [--allow-unsafe-paths]

Examples:

# Add research output
node scripts/add-to-database.js \
  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  "Research Report - Feb 2026" \
  projects/research-insights.md
Add project notes
node scripts/add-to-database.js 

<project-db-id> 

"Sprint Retrospective" 

docs/retro-2026-02.md
Add meeting notes

node scripts/add-to-database.js 

<notes-db-id> 

"Weekly Team Sync" 

notes/sync-2026-02-06.md

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

node scripts/get-database-schema.js <database-id> [--json]

Example output:

{
  "object": "database",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": [{"plain_text": "Ax Resources"}],
  "properties": {
    "Name": {"type": "title"},
    "Type": {"type": "select"},
    "Tags": {"type": "multi_select"}
  }
}

Use when:

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

Archive Pages

node scripts/delete-notion-page.js <page-id> [--json]

Note: This archives the page (sets

archived: true

), not permanent deletion.

Common Workflows

Collaborative Editing Workflow

Push local draft to Notion:

node scripts/md-to-notion.js draft.md <parent-id> "Draft Title"

User edits in Notion (anywhere, any device)

Monitor for changes:

node scripts/watch-notion.js <page-id> <local-path>
# Returns hasChanges: true when edited

Pull updates back:

node scripts/notion-to-md.js <page-id> draft-updated.md

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

Research Output Tracking

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

Sync to Notion database:

node scripts/add-research-to-db.js

User adds metadata in Notion UI (Type, Tags, Status properties)
Access from anywhere via Notion web/mobile

Page ID Extraction

From Notion URL:

https://notion.so/Page-Title-abc123-example-page-id-456def

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

Notion Sync

AI Skill Market Insights

Be Part of the 0+ Developer Community

Notion Sync

Upgrading

Requirements

Setup

JSON Output Mode

Path Safety Mode

Intentional override (outside workspace)

Core Operations

1. Search Pages and Databases

Find only databases

Limit results

2. Query Databases with Filters

Filter by Status = "Complete"

Filter by Tags containing "AI"

Sort by Date descending

Combine filter + sort

3. Update Page Properties

Add multiple tags

Set checkbox

Set date

Set URL

Set number

4. Batch Update

5. Markdown → Notion Sync

6. Notion → Markdown Sync

7. Change Detection & Monitoring

8. Database Management

Add Markdown Content to Database

Add project notes

Add meeting notes

Inspect Database Schema

Archive Pages

Common Workflows

Collaborative Editing Workflow

Research Output Tracking

Page ID Extraction

Limitations

Troubleshooting

Resources

scripts/

references/

Quick Start

Manual Installation

TEAR & SHARE

Tags

Channels

Learn

Compare

Company