notion-rsync

One-way sync from Notion to local Markdown files. Fast, idempotent, and designed for docs-as-code workflows.

# Sync your Notion workspace to markdown
notion-rsync sync --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

• Sync pages and databases (including nested databases)
• Preserves hierarchy as folder structure
• 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

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

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
• [ ] Progress indicators
• [ ] Configuration file support
• [ ] Image downloading (optional)
• [ ] Two-way sync (future)

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.