Notion Markdown 同步技能

将本地 Markdown 文件完整同步到 Notion 页面，保持图文排版顺序。

触发条件

当用户表达以下需求时，加载此技能：

• "把 Markdown 文件上传到 Notion"
• "同步本地笔记到 Notion"
• "导入 MD 文件到 Notion"
• "把 xxx.md 放到 Notion"
• "迁移笔记到 Notion"

核心脚本

# 基本用法
.\scripts\sync-to-notion.ps1 -MdFile "C:\path\to\file.md" -PageId "notion-page-id"

# 清空页面后上传
.\scripts\sync-to-notion.ps1 -MdFile "C:\path\to\file.md" -PageId "notion-page-id" -ClearPage

前置条件

1. Notion Token

用户必须先配置 Notion API Token。引导用户查看 references/SETUP_TOKEN.md。

快速检查：

$token = & "scripts\get-token.ps1"
if ($token) { Write-Host "Token 已配置" } else { Write-Host "请先配置 Token" }

2. 页面 ID

获取方式：

• 从 URL 复制：https://www.notion.so/workspace/PageName-1234567890abcdef
• 使用搜索 API 查询

3. 页面权限

页面必须分享给 Integration（Notion 页面设置 → Add connections）

支持的 Markdown 语法

| Markdown | Notion Block | 说明 | |----------|--------------|------| | # ~ ### | heading_1 ~ heading_3 | 原生支持 | | #### | callout + 📌 | 模拟 H4 | | ##### | paragraph + ▶ 加粗 | 模拟 H5 | | ###### | quote | 模拟 H6 | | ```lang ``` | code | 语言映射 + 超长拆分 | | | a | b | | table | 表格 | | ![alt](path) | image | 本地图片上传 | | - item | bulleted_list_item | 无序列表 | | 1. item | numbered_list_item | 有序列表 | | > quote | quote | 引用块 | | --- | divider | 分割线 | | **bold** | annotations.bold | 粗体 | | *italic* | annotations.italic | 斜体 | | `code` | annotations.code | 行内代码 | | [text](url) | link | 链接 |

关键坑点

1. 表格格式

{
  "type": "table",
  "table": {
    "table_width": 3,
    "has_column_header": true,
    "children": [{ "type": "table_row", "table_row": { "cells": [[{...}]] } }]
  }
}

• ❌ 用 rows 属性 → 报错
• ✅ 用 children 属性
• ✅ cells 是二维数组（rich_text 数组的数组）

2. rich_text 数组

• ❌ rich_text: [[...]] 双层数组 → 报错
• ✅ rich_text: [...] 单层数组

3. 代码块长度

• 单个 code Block 最多 2000 字符
• 脚本会自动拆分超长代码块

4. 页面 ID

• ❌ 用 workspace_id 作 parent → 404
• ✅ 用搜索 API 找有效页面

详细文档

• README.md — 安装和使用指南
• references/SETUP_TOKEN.md — Token 配置详解
• references/notion-api.md — Notion Block API 参考
• references/troubleshooting.md — 9 类常见问题排查

执行流程

1. 获取 Token — 检查环境变量/配置文件/平台托管
2. 验证文件 — 确认 MD 文件存在
3. 清空页面（可选）— 删除现有 Block
4. 预上传图片 — 上传本地图片到 Notion 文件存储
5. 构建 Block — 解析 Markdown，转换为 Notion 格式
6. 分批上传 — 每批 50 个 Block，避免 API 限制
7. 完成报告 — 显示成功/失败数量

错误处理

脚本会自动处理以下错误：

• Token 未配置 → 提示配置方法
• 文件不存在 → 提示路径
• API 限流 → 自动重试
• 超长代码块 → 自动拆分

更多错误排查见 references/troubleshooting.md