fs-notion-sync

Sync local Markdown files to Notion pages. Converts Markdown with frontmatter to Notion blocks and keeps them in sync.

Features

• 📄 Markdown to Notion - Converts Markdown files to Notion blocks using @tryfabric/martian
• 📑 Frontmatter support - Extracts title and metadata from YAML frontmatter
• 📁 Folder hierarchy - Preserves directory structure as nested Notion pages
• 👀 Watch mode - Automatically sync on file changes
• 🔄 Incremental updates - Updates existing pages instead of duplicating

Folder Hierarchy

The sync preserves your filesystem structure in Notion:

~/clawd/
  memory/
    2026-01-30.md
    2026-01-24.md
  AGENTS.md

Creates in Notion:

• AGENTS.md (page)
• 📁 memory/ (parent page)
  • 2026-01-30 (sub-page)
  • 2026-01-24 (sub-page)

Installation

bun install

Configuration

Set the following environment variables:

export NOTION_TOKEN="your-integration-token"
export NOTION_ROOT_ID="your-root-page-id"

Getting a Notion Token

1. Go to Notion Integrations
2. Create a new integration (requires workspace owner access)
3. Copy the Internal Integration Token (starts with ntn_)
4. Share your target page with the integration (click Share → Add connections)

Getting the Root Page ID

1. Open your target Notion page in the browser
2. Copy the page ID from the URL: https://www.notion.so/workspace/Page-Title-**abc123def456**
3. The ID is the last part after the title (32 hex characters, sometimes with dashes)

Usage

One-time sync

# Sync current directory
bun run sync

# Sync specific directory
bun run sync ./docs

Watch mode

# Watch and sync on changes
bun run watch ./docs

Dry run

# Preview what would be synced
bun run sync -n ./docs

Markdown Format

Files can include YAML frontmatter:

---
title: My Document
tags: [documentation, guide]
---

# Content here

Your markdown content...

Development

# Run in development mode
bun run dev

# Type check
bun run typecheck

# Build
bun run build

Project Structure

src/
├── index.ts     # CLI entry point
├── sync.ts      # Sync orchestration
├── parser.ts    # Markdown parsing
└── notion.ts    # Notion API client

License

MIT