notion-rsync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nonfx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# notion-rsync
+
+One-way sync from Notion to local Markdown files. Fast, idempotent, and designed for docs-as-code workflows.
+
+```bash
+# Sync your Notion workspace to markdown
+notion-rsync sync --output ./docs
+```
+
+## 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
+
+```bash
+# With npm
+npm install -g notion-rsync
+
+# With bun
+bun add -g notion-rsync
+```
+
+Or run directly without installing:
+
+```bash
+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](https://www.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
+
+```bash
+# 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:
+
+```markdown
+<!-- 
+  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.
+
+```bash
+notion-rsync init abc123def456 --output ./docs
+```
+
+### `sync`
+
+Sync content from Notion to local markdown files.
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+# 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
+
+- [ ] Progress indicators
+- [ ] Configuration file support
+- [ ] Retry logic for rate limits
+- [ ] Image downloading (optional)
+- [ ] Two-way sync (future)
+
+## License
+
+MIT