banana-sync-to-notion

用途

banana-sync-to-notion 用于将本地 Markdown 文件自动同步到 Notion，同时保留目录结构和完整的 Markdown 格式。适用于用户希望备份、同步或迁移文件到 Notion 的场景。

主要能力

递归扫描源目录（默认为项目根目录下的 Files/ 文件夹）。
将 Markdown 文件转换为 Notion 块。
将目录层级保留为嵌套页面。
根据文件名自动分配 emoji 图标。
跳过已存在的页面，实现增量同步。
显示详细的进度和统计信息。
支持清理目标页面下的所有子页面，以及重新同步（清理 + 同步）。

Markdown 支持

所有标准 Markdown 语法都会转换为原生 Notion 块，包括：粗体、斜体、粗斜体、行内代码、可点击链接（仅限 http/https）、代码块、无序列表、有序列表、引用块、标注（emoji 前缀的引用）、分隔线、Markdown 表格。

相对链接处理：

./file.md 或 ../folder/file.md → 转换为 Notion 页面链接。
./image.png → 保留为文本（不上传本地文件）。
http://... → 可点击的外部链接。

自动图标选择

脚本根据文件名模式分配 emoji 图标，例如：📖 章节、🎯 入门/基础、❓ FAQ/故障排除、💡 示例/案例、🔧 工具、📚 方法/教程、📊 数据/分析/报告、⚙️ 配置/设置、🏗️ 架构/系统、💻 脚本/代码、✍️ 写作/创意、📝 笔记/记录、🚀 高级/推荐、📋 指南、📘 README 文件、📦 下载/资源、🎨 演示文稿、📄 默认（无匹配）。可通过编辑 scripts/sync-notion.js 中的 selectIcon 函数自定义图标。

智能功能

重复检测：自动跳过已存在且标题相同的页面，实现无重复的增量同步。
智能分块：处理 Notion 每块 2000 字符的限制；支持超过 100 个块的文件；批量 API 请求以避免速率限制；临时失败时自动重试。
进度报告：同步期间显示详细统计，包括处理的文件数、创建与跳过的文件数、创建的文件夹数、耗时和错误。

使用方式

设置

在使用此技能前：

cd banana-sync-to-notion
npm install

通过创建 .env 文件配置环境变量：

NOTION_TOKEN=your_notion_integration_token
NOTION_ROOT_PAGE_ID=target_page_id

NOTION_TOKEN：从 Notion Integrations 获取。
NOTION_ROOT_PAGE_ID：文件将同步到的父页面 ID。
确保集成对目标页面具有读写权限。

同步文件到 Notion

在技能目录中运行：

npm run sync:notion

该命令会：递归扫描源目录（默认：项目根目录下的 Files/）；将 Markdown 文件转换为 Notion 块；将目录层级保留为嵌套页面；根据文件名分配 emoji 图标；跳过已存在的页面（增量同步）；显示详细进度和统计。

清理 Notion 页面

移除目标页面下的所有子页面：

npm run clean:notion

在全新重新同步之前使用此命令。

重新同步所有内容

清理现有内容并全新同步：

npm run resync:notion

结合了 clean:notion + sync:notion。

输出示例

🚀 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
==================================================

文件结构

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)

适用场景

将本地 Markdown 笔记、文档或知识库备份到 Notion。
在本地与 Notion 之间同步文件，保持目录结构。
将现有 Markdown 文件迁移到 Notion。

限制

图片支持：当前版本专注于文本/Markdown。图片需要托管 URL（图床）才能在 Notion 中显示。本地图片上传需要更复杂的认证。
缺失图标：不匹配任何图标模式的文件使用默认 📄 emoji。可在 scripts/sync-notion.js 中添加自定义模式。
速率限制：脚本包含针对 Notion API 速率限制的自动重试逻辑。大型同步（超过 100 个文件）可能需要几分钟。
相对链接不工作：确保链接的 Markdown 文件也已同步。链接仅对 Notion 中存在的页面有效。