Banana Sync to Notion

Automatically sync local Markdown files to Notion while preserving directory structure and full Markdown formatting.

Setup

Before using this skill:

1. Install dependencies in the skill directory:

   cd banana-sync-to-notion
   npm install

2. Configure environment variables by creating a .env file:

   NOTION_TOKEN=your_notion_integration_token
   NOTION_ROOT_PAGE_ID=target_page_id

   • NOTION_TOKEN: Get from Notion Integrations
   • NOTION_ROOT_PAGE_ID: The parent page ID where files will be synced
   • Ensure the integration has read/write permissions to the target page

Usage

Sync Files to Notion

Run from the skill directory:

npm run sync:notion

This command:

• Recursively scans the source directory (default: Files/ in project root)
• Converts Markdown files to Notion blocks
• Preserves directory hierarchy as nested pages
• Assigns emoji icons based on filenames
• Skips existing pages (incremental sync)
• Shows detailed progress and statistics

Clean Notion Pages

Remove all child pages under the target page:

npm run clean:notion

Use this before a fresh re-sync.

Re-sync Everything

Clean existing content and sync fresh:

npm run resync:notion

Combines clean:notion + sync:notion.

Markdown Support

All standard Markdown syntax is converted to native Notion blocks:

Syntax	Notion Output
**bold** or __bold__	Bold text
*italic* or _italic_	Italic text
***bold italic***	Bold italic
`code`	Inline code
[text](url)	Clickable link (http/https only)
```language ... ```	Code block
- item or * item	Bullet list
1. item	Numbered list
> quote	Quote block
> 💡 note	Callout (emoji-prefixed quotes)
--- or ***	Divider
Markdown tables	Native Notion tables

Relative Links:

• ./file.md or ../folder/file.md → Converted to Notion page links
• ./image.png → Preserved as text (no local file upload)
• http://... → Clickable external links

Automatic Icon Selection

The script assigns emoji icons based on filename patterns:

• 📖 Chapters (e.g., "01-intro.md")
• 🎯 Getting started, basics
• ❓ FAQ, troubleshooting, problems
• 💡 Examples, case studies
• 🔧 Tools, utilities
• 📚 Methods, tutorials
• 📊 Data, analysis, reports
• ⚙️ Configuration, settings
• 🏗️ Architecture, system
• 💻 Scripts, code
• ✍️ Writing, creative
• 📝 Notes, records
• 🚀 Advanced, recommendations
• 📋 Guides
• 📘 README files
• 📦 Downloads, resources
• 🎨 Presentations
• 📄 Default (no match)

Customize icons by editing the selectIcon function in scripts/sync-notion.js.

Smart Features

Duplicate Detection: Automatically skips pages that already exist with the same title, enabling incremental syncs without duplicates.

Smart Chunking:

• Handles Notion's 2000-character limit per block
• Supports files with >100 blocks
• Batches API requests to avoid rate limits
• Automatic retry on temporary failures

Progress Reporting: Shows detailed statistics during sync:

• Files processed
• Files created vs skipped
• Folders created
• Duration and errors

Output Example

🚀 Starting Notion Sync...
📂 Source: /path/to/Files
📄 Target Page: My Knowledge Base

📁 Syncing directory: Files
  ✨ Creating: 📖 01-Introduction
  📁 Syncing directory: 01-Introduction
    ✨ Creating: 📖 01-overview.md
    ⏭️  Skipping existing: 02-concepts.md
    ✨ Creating: 🎯 03-quickstart.md

==================================================
✅ Sync Complete!
==================================================
⏱️  Duration: 45.2s
📊 Statistics:
   • Files processed: 35
   • Files created: 25
   • Files skipped: 10
   • Folders created: 5
   • Errors: 0
==================================================

File Structure

banana-sync-to-notion/
├── SKILL.md
├── .env (user created)
├── package.json
├── scripts/
│   ├── sync-notion.js   # Main sync logic
│   └── clean-notion.js  # Cleanup utility
└── Files/ (default source directory)

Troubleshooting

Image support: Current version focuses on text/Markdown. Images require hosted URLs (image hosting) to display in Notion. Local image upload requires more complex authentication.

Missing icons: Files that don't match any icon pattern use the default 📄 emoji. Add custom patterns in scripts/sync-notion.js.

Rate limits: The script includes automatic retry logic for Notion API rate limits. Large syncs (>100 files) may take several minutes.

Relative links not working: Ensure the linked Markdown file was also synced. Links only work to pages that exist in Notion.