Repository files navigation

A Python CLI tool that extracts Notion pages and converts them to Markdown files with automatic project organization. Built for seamless integration with Claude Code workflows.

Extract Notion pages to clean Markdown format with automatic organization into your project structure:

• Auto-directory creation: Saves touser-context/notion-pages/ in your projects
• Local image downloads: All images downloaded with relative path references
• Rich block support: Converts callouts, tables, toggles, synced blocks, and more
• Project-aware: Detects Software Projects and Thought Projects automatically
• Cross-project usage: Global CLI installation works from any directory

Status: MVP Complete ✅

✅Auto-organizing extractions - Saves touser-context/notion-pages/ automatically✅Project detection - Recognizes Software Projects and Thought Projects✅Synced block support - Extracts reusable Notion content correctly✅Local image downloads - All images saved with relative paths✅Rich block types - Headings, lists, code, tables, callouts, toggles, and more✅UTF-8 encoding - Windows-compatible out of the box✅Global CLI - Use from any directory✅Clean Markdown - Optimized for Claude Code context

• Python: 3.12+ (confirmed working with 3.13.7)
• UV Package Manager: Fast Python package manager
• Notion API Token: Integration token from Notion workspace

# Windows (PowerShell)powershell -c"irm https://astral.sh/uv/install.ps1 | iex"# macOS/Linuxcurl -LsSf https://astral.sh/uv/install.sh| sh

cd"Software Projects/notion-markdown-extractor"uv tool install.

notion-md configure --token<your-notion-integration-token>

How to get your Notion API token:

1. Go tohttps://www.notion.so/my-integrations
2. Click "New integration"
3. Give it a name (e.g., "Markdown Extractor")
4. Copy the "Internal Integration Token"
5. Share the Notion pages you want to extract with this integration

# Navigate to your projectcd"Thought Projects/my-research-project"# Extract a Notion page (auto-saves to user-context/notion-pages/)notion-md extract"https://www.notion.so/Your-Page-Title-abc123"# ✅ Saved to: ./user-context/notion-pages/your-page-title.md# ✅ Images to: ./user-context/notion-pages/images/

# Override auto-directory with explicit pathnotion-md extract"https://notion.so/Page-abc123" --output~/Documents/notes.md

notion-md status

The tool automatically organizes extracted Notion pages:

1. Detects Project Directory

• Checks if you're in "Software Projects" or "Thought Projects"
• Falls back to creating structure anywhere

2. Creates Structure

your-project/└── user-context/    └── notion-pages/        ├── page-title.md        ├── another-doc.md        └── images/            ├── diagram-1.png            └── chart-2.png

3. Saves with Clean Filenames

• Page titles converted to kebab-case
• Images downloaded locally with relative paths

Benefits:

• ✅ Consistent organization across all projects
• ✅ Files ready for Claude Code context
• ✅ No manual directory creation
• ✅ Override with--output when needed

Auto-organized (default in projects):

user-context/notion-pages/├── framework-document.md├── meeting-notes.md├── strategic-plan.md└── images/    ├── architecture-diagram.png    ├── workflow-chart.png    └── screenshot.jpg

Custom location (with--output flag):

your-custom-path/├── custom-name.md└── images/    └── downloaded-images.png

• Text: Paragraphs, Headings (1-3), Quotes
• Lists: Bulleted, Numbered (with nesting)
• Code: Code blocks with syntax highlighting, Inline code
• Media: Images (downloaded locally), File attachments
• Structure: Dividers, Tables, Callouts, Toggle blocks
• Links: Internal page references (converted to placeholders)

Callouts → Blockquotes with emoji:

>💡**Key Point** This is important information

Toggle Blocks → Flattened to headings:

###Section TitleContent that was inside the toggle

Tables → Markdown tables:

| Column 1| Column 2||----------|----------|| Data 1| Data 2|

Internal Links → Placeholders:

[Related Document Name - see separate import]

• Databases (inline and full-page)
• Embedded content
• Video/Audio
• Column layouts (content extracted but layout flattened)

notion-markdown-extractor/├── explore/           # Research and discovery├── plan/              # Planning documents (PRD)├── execute/           # Implementation│   ├── src/          # Python source code│   ├── tests/        # Test suites│   └── pyproject.toml├── user-context/      # Context files└── README.md          # This file

# Navigate to projectcd"Software Projects/notion-markdown-extractor/execute"# Install dependenciesuv add click notion-client python-dotenv requests Pillowuv add --dev pytest pytest-mock pytest-cov# Run testsuv run pytest# Run CLI locally (development mode)uv run python -m src.cli extract<notion-url>

• Verify your token in Notion settings
• Ensure the integration has access to the page you're trying to extract
• Re-runnotion-md configure --token <new-token>

• Check that the Notion page URL is correct
• Ensure the integration is shared with the page (click Share → Add integration)

• Tool will log the error and continue processing
• Check network connection
• Verify images are accessible (not private external images)

• Tool automatically handles UTF-8 encoding
• If issues persist, check terminal encoding:chcp 65001

# Remove global CLI tooluv tool uninstall notion-markdown-extractor# Remove configurationrm -rf~/.notion-md/

• ✅ Single-page extraction
• ✅ Local image downloads
• ✅ Core block types
• ✅ Global CLI installation

• Batch extraction from databases
• Automatic link following
• Advanced block types (databases, embeds)
• Multi-workspace support
• BMAD BMB Agent integration

• Usage Guide - Complete CLI reference and examples
• Notion Setup Guide - Integration setup and permissions

• PRD - Product requirements
• Project Checkpoints - Development session notes
• Workspace Guidelines - BMAD workflow context

Internal tool for personal/business use.

For issues or questions about this prototype, refer to the PRD or project documentation inplan/ anduser-context/ directories.

Built with: Python 3.13.7 | UV Package Manager | Click CLI Framework | Notion API

Status: Prototype - Fast extraction for immediate business needs