mdsync

A Python CLI package to sync markdown files to Notion (and potentially other platforms in the future). One-way sync from markdown to platform with focus on simplicity and excellent markdown parsing.

Features

• One-way sync (markdown → platform)
• Dry-run mode to preview changes
• Command-line focused (simple args, no config files)
• Excellent markdown parsing with LaTeX support
• Preserve directory structure as nested pages

Installation

From PyPI

pip install mdsync

Quick Start

Prerequisites

1. Create a Notion integration at https://www.notion.so/my-integrations
2. Copy the integration token (starts with ntn_)
3. Share a Notion page with your integration
4. Copy the page ID or page URL from the Notion page

Usage

Sync a single markdown file:

mdsync notion --token ntn_... --parent PAGE_ID_or_PAGE_URL document.md

Sync an entire directory (preserves folder structure):

mdsync notion --token ntn_... --parent PAGE_ID_or_PAGE_URL docs/

Preview changes without syncing (dry-run):

mdsync notion --token ntn_... --parent PAGE_ID_or_PAGE_URL --dry-run docs/

Command-Line Options

Usage: mdsync notion [OPTIONS] PATH

  Sync markdown files to Notion.

  PATH can be a single markdown file or a directory containing markdown files.
  Directories are synced recursively, preserving the folder structure.

Options:
  --token TEXT                    Notion integration token  [required]
  --parent TEXT                   Parent page ID or page URL where files will
                                  be synced  [required]
  --dry-run                       Preview changes without actually syncing
  --page-icon                     Add random emoji icons to pages
  --page-title [heading|filename]
                                  How to determine page titles: 'heading'
                                  (from first heading) or 'filename' (from
                                  file/folder name)
  --help                          Show this message and exit.

Supported Markdown Features

• Headings (H1, H2, H3, H4+ mapped to H3)
• Paragraphs with inline formatting:
  • Bold
  • Italic
  • Strikethrough
  • Inline code
  • Links
  • Relative links between markdown files (auto-resolved to Notion pages)
• Code blocks with syntax highlighting
• Bulleted lists
• Numbered lists
• Nested lists
• Task lists (- [ ] and - [x])
• Blockquotes
• Tables with header detection
• Dividers/Horizontal rules
• LaTeX equations ($...$ inline, $$...$$ block)
  • Note: Dollar signs are treated as math delimiters. To use $ for currency, escape it: \$4000
• Line breaks

How It Works

1. File Discovery: Finds all .md and .markdown files in the specified path
2. Parsing: Uses mistletoe to parse markdown into an AST
3. Conversion: Transforms AST nodes to Notion block format
4. Sync: Creates pages in Notion with proper hierarchy
5. Link Resolution: Two-pass sync automatically resolves relative links between markdown files to Notion page URLs
6. Output: Shows progress and summary with beautiful terminal output

Directory Structure Mapping

Folders are converted to nested pages in Notion:

docs/
├── Getting Started.md       →  Page: "Getting Started"
├── guides/                  →  Page: "Guides" (container)
│   ├── Installation.md      →    └─ Page: "Installation"
│   └── Configuration.md     →    └─ Page: "Configuration"
└── api/                     →  Page: "Api" (container)
    ├── Authentication.md    →    └─ Page: "Authentication"
    └── Endpoints.md         →    └─ Page: "Endpoints"

Roadmap

Implemented Features

• LaTeX math equation support (inline and block)
• Relative link resolution between markdown files
• Task list support
• Strikethrough text support
• Nested lists
• Custom page icons (emoji)
• Configurable page title source (heading vs filename)

Future Features

• Additional platforms (Confluence, WordPress, Medium)
• Incremental sync / update detection
• Image upload support

Contributing

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

License

MIT License - see the LICENSE file for details.

Acknowledgments

• mistletoe - Excellent markdown parser
• click - Beautiful CLI framework
• rich - Terminal output formatting