notion-rsync

Two-way sync between Notion and local Markdown files. Fast, idempotent, and designed for docs-as-code workflows.

# Pull your Notion workspace down to markdown
notion-rsync sync --output ./docs

# Push local markdown back up to Notion
notion-rsync push --output ./docs

npm | GitHub | Issues

Why?

• Docs-as-code - Keep your documentation in git, use your favorite editor, run CI/CD on it
• LLM-friendly - Export Notion content for RAG pipelines and AI context
• Backup - Simple, readable backups of your Notion workspace
• Fast - Parallel fetching with concurrency control
• Idempotent - Safe to run repeatedly, only overwrites what changed

Features

• Two-way sync - Pull from Notion (sync) and push back up (push)
• Sync pages and databases (including nested databases)
• Preserves hierarchy as folder structure (both directions)
• Re-creates internal links between pages as Notion page mentions on push
• Rich frontmatter with all database properties
• Handles 20+ block types (text, lists, tables, code, callouts, toggles, equations, embeds...)
• Gracefully renders unsupported blocks (AI blocks, etc.) as HTML
• Dry-run mode for previewing changes
• Cleans up deleted pages automatically

Installation

# With npm
npm install -g notion-rsync

# With bun
bun add -g notion-rsync

Or run directly without installing:

npx notion-rsync sync --output ./docs
bunx notion-rsync sync --output ./docs

Quick Start

1. Create a Notion Integration

1. Go to notion.so/my-integrations
2. Click "New integration"
3. Give it a name and select your workspace
4. Copy the "Internal Integration Secret"

2. Share Your Page/Database

1. Open the Notion page or database you want to sync
2. Click "..." → "Add connections"
3. Select your integration

3. Initialize and Sync

# Set your token
export NOTION_TOKEN="secret_abc123..."

# Get your page/database ID from the URL:
# https://notion.so/My-Page-abc123def456
#                        ^^^^^^^^^^^^^^^ this part

# Initialize (creates .notion-rsync config)
notion-rsync init abc123def456 --output ./docs

# Run sync
notion-rsync sync --output ./docs

# Or preview first
notion-rsync sync --output ./docs --dry-run

4. Push Changes Back (optional)

Edit the local markdown, then push it back up to Notion:

# Push edits back to the pages they came from
notion-rsync push --output ./docs

# Or upload a brand-new folder under an existing Notion page
notion-rsync push abc123def456 --output ./my-new-docs

push updates existing pages in place (matched by the notion_id in each file's frontmatter) and creates pages for any new files, mirroring your folder structure and rewriting relative .md links as Notion page mentions.

Output Structure

docs/
├── .notion-rsync/
│   └── index.json          # Sync state (tracks pages for cleanup)
├── my-database/
│   ├── index.md            # Database root (if it has content)
│   ├── page-one.md
│   ├── page-two/
│   │   ├── index.md        # Pages with children become folders
│   │   └── nested-page.md
│   └── child-database/
│       ├── index.md
│       └── entry.md
└── standalone-page.md

Generated Markdown

Each file includes:

<!-- 
  Auto-generated by notion-rsync. Do not edit manually.
  Changes will be overwritten on next sync.
-->
---
notion_id: abc123-def456
title: "My Page Title"
last_edited: 2024-01-15T10:30:00.000Z
status: "In Progress"           # Database properties
priority: "P1"                  # are included in
assignee: "John Doe"            # frontmatter
tags: ["feature", "urgent"]
---

# My Page Title

Your content here...

Commands

init <page-id>

Initialize sync configuration for a Notion page or database.

notion-rsync init abc123def456 --output ./docs

sync

Sync content from Notion to local markdown files.

notion-rsync sync --output ./docs [--dry-run]

Options:

• --output, -o - Output directory (default: ./docs)
• --dry-run, -n - Preview changes without writing files
• --verbose, -v - Enable verbose logging

push [page-id]

Push local markdown back up to Notion, mirroring the folder hierarchy and re-creating internal links as page mentions.

# Round-trip: update the pages a synced folder came from
notion-rsync push --output ./docs

# Brand-new: create the folder's pages under a target Notion page
notion-rsync push abc123def456 --output ./my-new-docs

• Files with a notion_id in frontmatter update their existing page in place.
• Files without one are created. The optional page-id argument is the parent page for new top-level pages; if omitted, the root from .notion-rsync (created by init/sync) is used.
• Idempotent: after creating a page, push writes the new notion_id back into the file's frontmatter (and creates an index.md for folders without one), so running it again updates pages in place rather than duplicating them.

Options:

• --output, -o - Source directory (default: ./docs)
• --dry-run, -n - Preview what would be created/updated without writing
• --verbose, -v - Enable verbose logging

status

Show sync status and configuration.

notion-rsync status --output ./docs

Environment Variables

| Variable | Description | |----------|-------------| | NOTION_TOKEN | Notion API integration token (required) |

Supported Block Types

| Block Type | Markdown Output | |------------|-----------------| | Paragraph | Plain text | | Headings (1-3) | #, ##, ### | | Bulleted list | - item | | Numbered list | 1. item | | To-do | - [ ] / - [x] | | Toggle | <details><summary> | | Code | Fenced code blocks | | Quote | > blockquote | | Callout | > emoji text | | Divider | --- | | Table | Markdown tables | | Image | ![alt](url) | | Video/File/PDF | [name](url) | | Bookmark | [title](url) | | Embed | [title](url) | | Equation | $$latex$$ | | Columns | Sequential blocks | | Synced block | Resolved content | | Child page | Link | | Child database | Recursed |

Supported Property Types

All Notion database property types are extracted to frontmatter:

• Text, Number, Checkbox, URL, Email, Phone
• Select, Multi-select, Status
• Date (with ranges)
• People, Files
• Formula, Relation, Rollup
• Created/Last edited time and by
• Unique ID

Development

# Clone
git clone https://github.com/nonfx/notion-rsync.git
cd notion-rsync

# Install dependencies
bun install

# Run locally
bun run dev sync --output ./test-output

# Build
bun run build

# Lint & format
bun run lint
bun run format

Roadmap

• [x] Retry logic for rate limits
• [x] Two-way sync — push local markdown back to Notion (push)
• [x] Idempotent push — stamps notion_id into new files so re-push updates in place
• [ ] Push: block-level diffing (currently clear-and-replace content)
• [ ] Conflict detection & resolution
• [ ] Progress indicators
• [ ] Configuration file support
• [ ] Image downloading (optional)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT - see LICENSE for details.