Notion 到 Markdown 转换器

使用官方 Notion API 将 Notion 页面和数据库转换为干净、可读的 Markdown 格式。

⚠️ 安全性与凭证

必需凭证：

• NOTION_API_KEY - 你的个人 Notion 集成令牌（必需）

安全最佳实践：

1. 创建专用集成 - 访问 [notion.so/my-integrations](https://www.notion.so/my-integrations) 并为此工具单独创建一个集成
2. 使用只读权限 - 为集成授予“读者”权限，而非“编辑者”
3. 选择性共享 - 仅将特定页面或数据库共享给该集成，不要共享整个工作区
4. 保护你的令牌 - 永远不要将包含 NOTION_API_KEY 的 .env 文件提交到版本控制系统
5. 使用临时令牌 - 考虑为令牌设置轮换策略，或使用临时令牌
6. 代码审查 - 本工具仅使用官方 @notionhq/client 库，并且仅与 Notion API 通信。数据不会发送至其他地方

网络访问：

• 仅连接至：https://api.notion.com（官方 Notion API）
• 不调用任何外部 API 或数据源
• 不发送遥测或日志至其他位置

要求

• Node.js: 14.0.0 或更高版本
• npm: 6.0.0 或更高版本
• Notion API 令牌： 必需（从 [notion.so/my-integrations](https://www.notion.so/my-integrations) 获取）

检查 Node 版本：

node --version  # 应为 v14.0.0 或更高版本
npm --version

快速开始

1. 获取你的 Notion API 密钥

参见 [Notion API 设置](references/notion-api-setup.md) 获取完整说明：

• 在 [notion.so/my-integrations](https://www.notion.so/my-integrations) 创建集成
• 复制你的 API 令牌（格式如 notioneq_...）
• 将你的 Notion 页面分享给该集成
• 设置环境变量：export NOTION_API_KEY="your_token"

2. 安装依赖项

cd scripts
npm install

3. 转换页面

单个页面：

NOTION_API_KEY=your_token node convert.js <page-id> > output.md

数据库导出：

NOTION_API_KEY=your_token node convert.js <database-id> --database ./exports

使用模式

转换单个 Notion 页面

提取一个页面并输出到文件：

node scripts/convert.js a1b2c3d4e5f6g7h8 > my-page.md

转换器自动执行以下操作：

• 从 Notion 获取页面
• 将所有块转换为 Markdown
• 保留格式（加粗、斜体、链接等）
• 输出至标准输出或文件

批量导出数据库

将 Notion 数据库中的所有页面转换为文件：

node scripts/convert.js a1b2c3d4e5f6g7h8 --database ./notion-export

为每个页面生成独立的 Markdown 文件：

notion-export/
├── page-one.md
├── page-two.md
└── page-three.md

提取页面元数据

转换器会保留页面属性：

const result = await convertPageToMarkdown(pageId);
console.log(result.title);      // 来自 Notion 的页面标题
console.log(result.markdown);   // 转换后的 Markdown 内容
console.log(result.pageId);     // 原始页面 ID

支持的转换内容

支持的块类型

✅ 文本、标题和段落

✅ 加粗、斜体、下划线、删除线、行内代码

✅ 链接（内部和外部）

✅ 列表（有序和无序）

✅ 带语法高亮的代码块

✅ 表格

✅ 引用和提示框

✅ 图片（以 Markdown 图像语法表示）

✅ 分隔符和分隔线

✅ 数据库属性作为前端信息（frontmatter）

保留的格式

• 标题层级（H1、H2、H3 等）
• 列表嵌套
• 代码块语言
• 链接的 URL 和文本
• 强调和样式

不保留的内容

• Notion 数据库（尽可能转换为表格）
• 一些高级格式（上标、下标）
• 画布块（Canvas blocks）
• 嵌入式网页内容（转换为链接）

环境设置

设置 API 密钥

**选项 1：使用 .env 文件（推荐）**

在 scripts 目录中创建 .env 文件：

# scripts/.env
NOTION_API_KEY=ntn_your_api_key_here

然后正常运行转换器：

node convert.js <page-id> > output.md

脚本会通过 dotenv 包自动加载 .env 中的环境变量。

选项 2：导出环境变量

永久设置于你的 shell 配置中：

# ~/.bashrc, ~/.zshrc, 或 ~/.config/fish/config.fish
export NOTION_API_KEY="notioneq_..."

选项 3：为单个命令设置

NOTION_API_KEY=your_token node convert.js <page-id>

安全提示： 将 .env 添加到 .gitignore，防止意外提交你的 API 密钥：

echo ".env" >> .gitignore

查找 ID

从 URL 获取页面 ID

Notion URL 格式：

https://www.notion.so/Workspace-Name/Page-Title-abc123def456?v=xyz
                                                    ↑ 页面 ID

复制 ID 部分（URL 中不含连字符的部分）。

数据库 ID

与页面 URL 相同 —— 在数据库的 URL 中查找 ID。

故障排除

“NOTION_API_KEY 未设置”

确保环境变量已正确导出：

export NOTION_API_KEY="notioneq_..."
echo $NOTION_API_KEY  # 验证是否已设置

“页面未找到或不可访问”

• 确认页面 ID 正确
• 检查是否已将页面共享给你的 Notion 集成
• 确保集成对该工作区具有访问权限

“无效的页面 ID 格式”

• Notion 页面 ID 是 32 位字母数字字符串
• 从 URL 中移除连字符
• 示例有效 ID：a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Markdown 输出不完整

• 可能因 API 限流导致请求被限制
• 等待片刻后重试
• 对批量导出，添加延迟：sleep 0.5 在每次转换之间

高级用法

自定义输出处理

修改 scripts/convert.js 以在保存前处理 Markdown 内容：

let markdown = result.markdown;
// 添加自定义处理
markdown = markdown.replace(/\n{3,}/g, '\n\n');  // 清理多余空行
fs.writeFileSync('output.md', markdown);

批量处理

在循环中转换多个页面：

for pageId in page1 page2 page3; do
  node convert.js $pageId > "$pageId.md"
done

与其他工具的集成

生成的 Markdown 文件为纯文本格式，兼容以下工具：

• 静态网站生成器（Hugo、Jekyll、Next.js）
• 文档平台（Docusaurus、Doclify）
• 版本控制工具（git、GitHub）
• 发布工具（WordPress、Medium）

API 参考

如需高级用法，请参阅 [notion-to-md 文档](https://github.com/souvikinator/notion-to-md) 和 [Notion API 参考文档](https://developers.notion.com/)。

安全注意事项

• 请妥善保管您的 NOTION_API_KEY
• 不要将 API 密钥提交到版本控制系统
• 使用 .gitignore 忽略 .env 文件
• 若密钥泄露，请立即更换
• 仅在必要时与集成共享 Notion 页面权限

相关链接

• [Notion API 设置指南](references/notion-api-setup.md) - 完整的设置说明
• [notion-to-md GitHub 仓库](https://github.com/souvikinator/notion-to-md) - 源代码库
• [Notion API 文档](https://developers.notion.com/) - 官方 API 文档