Push to Notion 📚

Move your local content to Notion while preserving directory structure and formatting. Perfect for importing Lumentis generated content or any folder containing markdown, MDX, and text files.

Features ✨

• 🔄 Smart Directory Sync: Recursively imports your content while maintaining folder hierarchy
• 📝 Multiple File Types: Supports Markdown, MDX, plain text, and JSON files
• 🔗 Lumentis Integration: Direct import of Lumentis-generated pages with full formatting
• 📁 Flexible Structure: Works with both flat files and nested directories
• 🎨 Content Organization: Use _meta.json to customize titles and order
• 🔄 Smart Updates: Only updates modified files, saving time and API calls
• 🧙‍♂️ Interactive Setup: User-friendly wizard for configuration
• 📊 Progress Tracking: Real-time progress bars and detailed logging

Installation 🚀

# Using npm
npm install -g push-to-notion

# Using yarn
yarn global add push-to-notion

# Using bun
bun add -g push-to-notion

# Or run directly with npx
npx push-to-notion

Quick Start 🏃‍♂️

1. Get your Notion API key from Notion Integrations
2. Create a page in Notion where you want to import your content
3. Share the page with your integration
4. Run the tool:

push-to-notion --token YOUR_NOTION_TOKEN --parent YOUR_PAGE_ID --path ./your/content/path

Or use the interactive wizard:

push-to-notion

Directory Structure 📁

Your content directory can include:

content/
├── _meta.json           # Optional: Configure titles and order
├── index.mdx           # Root content (processed first)
├── getting-started/
│   ├── index.mdx      # Directory content
│   ├── setup.mdx      # Sub-page
│   └── configuration/ # Nested directory
│       └── index.md   # Nested content
└── api/
    ├── _meta.json     # Directory-specific meta
    ├── endpoints.mdx
    └── auth.mdx

_meta.json Configuration 🎯

Control page titles and order:

{
  "getting-started": "Getting Started Guide",
  "api": {
    "title": "API Documentation",
    "order": 1
  },
  "endpoints": "API Endpoints",
  "auth": "Authentication"
}

Files are ordered:

1. By their order in _meta.json
2. Alphabetically for files not in _meta.json

Lumentis Integration 🤝

Import Lumentis-generated content directly:

1. Generate content with Lumentis
2. Point push-to-notion to your output directory:

push-to-notion --path ./lumentis-output --parent YOUR_PAGE_ID

Best Practices 💡

1. Directory Organization:

   • Use index.mdx for main directory content
   • Keep related files in subdirectories
   • Use consistent file naming

2. Content Structure:

   • Start with a clear root index.mdx
   • Use headings for better navigation
   • Break large content into subpages

3. Updates:

   • The tool tracks file modifications
   • Only changed files are updated
   • Use --fresh to force full reimport

Advanced Usage 🛠️

CLI Options

Options:
  -t, --token <token>        Notion API token
  -p, --parent <id>         Parent page ID
  -d, --path <path>         Content directory path
  -v, --verbose             Enable verbose logging
  --dry-run                 Test run without making changes
  --fresh                   Force reimport of all files
  -h, --help               Display help

Environment Variables

export NOTION_TOKEN=your_token
export NOTION_PARENT_PAGE=your_page_id

Development 🔧

# Clone the repo
git clone https://github.com/southbridgeai/push-to-notion.git

# Install dependencies
bun install

# Build
bun run build

# Run locally
bun run cli

Contributing 🤝

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

License 📄

Apache-2.0 - see LICENSE for details.

Made with ❤️ by Hrishi Olickel