# notion-md-sync

**Repository Path**: bs6/notion-md-sync

## Basic Information

- **Project Name**: notion-md-sync
- **Description**: Notion Markdown 同步工具｜支持代码块/表格/图片完整转换，批量上传+增量同步，内置故障排查，开箱即用

- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# notion-md-sync

📝 将本地 Markdown 文件同步到 Notion 页面，支持完整语法。

## 特性

- ✅ **完整 Markdown 支持**：标题、段落、代码块、表格、图片、列表、引用等
- ✅ **多级标题**：H1-H3 原生支持，H4-H6 用其他 Block 模拟
- ✅ **图片上传**：自动上传图片到 Notion 文件存储
- ✅ **表格支持**：正确处理表格格式
- ✅ **代码高亮**：自动映射语言名称
- ✅ **清空页面**：可选参数，上传前清空页面

## 安装

### 方式一：通过 SkillHub（推荐）

```bash
npx skills add <owner/repo@notion-md-sync>
```

### 方式二：手动安装

```bash
# 克隆仓库
git clone https://github.com/<owner>/notion-md-sync.git

# 复制到技能目录
cp -r notion-md-sync ~/.openclaw/skills/
```

## 配置

### 1. 获取 Notion Token

详见 [SETUP_TOKEN.md](references/SETUP_TOKEN.md)

**快速配置（环境变量）**：
```powershell
$env:NOTION_TOKEN = "secret_your_token_here"
```

### 2. 获取页面 ID

**从 URL 复制**：
```
https://www.notion.so/your-workspace/PageName-1234567890abcdef
                                    ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑
                                    这就是页面 ID
```

**或使用搜索 API**：
```powershell
$token = $env:NOTION_TOKEN
irm "https://api.notion.com/v1/search" -Method POST -Headers @{
    "Authorization" = "Bearer $token"
    "Notion-Version" = "2025-09-03"
    "Content-Type" = "application/json"
} -Body '{"filter":{"property":"object","value":"page"}}'
```

### 3. 分享页面给 Integration

在 Notion 页面中：
1. 点击右上角 **...** → **Add connections**
2. 搜索并选择你的 Integration

## 使用

### 同步 Markdown 到 Notion

```powershell
.\scripts\sync-to-notion.ps1 -MdFile "C:\notes\SpringBoot.md" -PageId "your-page-id"
```

### 清空页面后上传

```powershell
.\scripts\sync-to-notion.ps1 -MdFile "C:\notes\SpringBoot.md" -PageId "your-page-id" -ClearPage
```

### 修复页面名称（解决"???"问题）

如果页面创建成功后标题显示为 "???"，使用重命名脚本修复：

```powershell
# 方式 1：修复单个页面
python .\scripts\rename-page.py "page-id" "新的标题"

# 方式 2：批量修复（预定义映射）
python .\scripts\rename-page.py
```

## 支持的 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` | 链接 |

## 文件结构

```
notion-md-sync/
├── SKILL.md                    # 技能主文档
├── README.md                   # 本文件
├── scripts/
│   ├── sync-to-notion.ps1      # 主脚本：同步 Markdown 到 Notion
│   ├── rename-page.py          # 重命名脚本：修复页面名称显示为???
│   └── get-token.ps1           # Token 获取脚本
└── references/
    ├── notion-api.md           # API 参考
    ├── troubleshooting.md      # 问题排查
    └── SETUP_TOKEN.md          # Token 配置指南
```

## 常见问题

### Q: 提示 "未找到 Notion Token"
**A**: 请先配置 Token，详见 [SETUP_TOKEN.md](references/SETUP_TOKEN.md)

### Q: 表格显示异常
**A**: 确保表格格式正确，每行以 `|` 开始和结束

### Q: 图片上传失败
**A**: 检查图片路径是否正确，确保是相对路径

### Q: 代码块不显示
**A**: 检查语言名称是否在 Notion 支持列表中

更多问题见 [troubleshooting.md](references/troubleshooting.md)

## 限制

- 单个 Block 最多 2000 字符（代码块会自动拆分）
- 每次请求最多 100 个 Block（自动分批）
- 仅支持 PowerShell（Windows）
- 需要 curl.exe（Windows 10+ 预装）
- **PowerShell 5.1 兼容**：图片上传已改用 curl.exe

## License

MIT