在 Notion 里点"导出为 Markdown & CSV"之后，下载 ZIP 解压，每个 .md 文件名末尾都拖着一串 32 位十六进制页面 ID；Callout 块原封不动地输出为裸 HTML；Toggle 的折叠结构散开，变成并排段落。也有人直接把页面内容粘贴到编辑器，结果得到满屏带 style 属性的 span 标签。去除这类 span 和内联样式的方法见 HTML 粘贴 Markdown 化。从 Notion 拿到干净的 Markdown 其实有两条路径，选对路径能省下大量手动整理的时间。
如果只需要把一两页保密内容立刻变成干净 Markdown，在 Notion 里选"•••"→"导出"→"HTML"，把导出的 HTML 粘贴到 HTML to Markdown 运行即可。转换完全在浏览器内完成，不产生任何上传。ZIP 批量整理和 API 自动化的完整说明见下文。
该选哪条路径
两条路径最终到达的地方相同——Obsidian、静态站点生成器、README、LLM 提示词都能直接使用的、可移植性强的 Markdown。区别在于起点不同，以及事后需要修正的范围。
- 路径 A — Markdown & CSV ZIP 导出：需要整体迁移工作区或整棵页面树时使用。UUID 混入的文件名、Callout 的 HTML、同步块的重复，可以用脚本批量处理。往下看 路径 A。
- 路径 B — 导出 HTML 后在浏览器内转换：目标只有一到几页，且包含不可上传到外部服务器的保密内容。希望一开始就得到干净输出。把 HTML 粘贴到浏览器端的 HTML to Markdown 即可。往下看 路径 B。
如果正在搭建自动化流水线，2026 年 3 月正式上线的 Notion 官方 Markdown Content API 是第三个选项。放在两条路径之后介绍。
Notion 是怎么生成 Markdown 的
Notion 是基于块的编辑器。一个页面由段落、标题、列表项、数据库、Callout、Toggle、同步块、公式、嵌入等块组成的树状结构构成，其中能一对一映射到标准 Markdown 语法的只是少数。选择"导出为 Markdown"后，Notion 遍历这棵树，输出它能表达的最接近形式。没有 Markdown 对应语法的块要么被丢弃，要么扁平化为纯文本，要么原样保留为 HTML 标签。
Notion 官方帮助中心明确说明，Callout 块"由于 Markdown 没有对应语法，因此以 HTML 形式导出"（原文在新标签页中打开）。同一页面还警告在 Windows 上可能触及默认 MAX_PATH 260 字符的路径长度限制，并建议使用 7-Zip 解压。除此之外的其他行为并未列出，往往要打开 ZIP 之后才能发现。
原生 Markdown & CSV 导出的操作步骤
无论选哪条路径，Notion 内的导出操作本身是相同的。点击页面右上角"•••"菜单，选择"导出"，格式指定为"Markdown & CSV"。Business 和 Enterprise 套餐下可以开启"包含子页面"选项，将该页面下整棵页面树打包进一个 ZIP。整个工作区的导出在"Settings → Workspace → General"中操作，大型工作区可能需要数小时。
路径 A — 整理 Markdown & CSV 的 ZIP 导出
解压 ZIP 后，会反复遇到 8 个固定的问题。逐一说明原因和实际的处理方法。
文件名和页面链接中附带 32 位页面 ID
导出的 .md 文件名末尾通常是"文档标题 + 空格 + 32 位十六进制页面 ID"，Markdown 内部的 [页面引用] 链接也指向带 ID 的文件名。手动改文件名会导致所有内部链接失效。常规解法是两步脚本处理：先收集全部文件名建立"页面 ID → 干净标题"的映射表，再替换所有 Markdown 文件中的链接地址，最后把文件名本身改为干净标题。社区文章 Notion's Markdown Export Quirks在新标签页中打开 也涵盖了相同的模式。
Windows 的 260 字符路径长度限制
Notion 的深层嵌套页面结构会生成 My Team's Handbook a1b2c3.../Onboarding e4f5g6.../Week 1 tasks h7i8j9....md 这样极长的路径。Windows 默认 MAX_PATH 为 260 字符，很容易超出。Notion 官方帮助建议"关闭创建文件夹选项"或"使用支持长路径的 7-Zip 解压"。macOS 和大多数 Linux 文件系统没有同样的 260 字符限制。
Callout 块以裸 HTML 输出
带 emoji 和背景色的 Notion Callout 不是以 Markdown 引用块形式输出，而是以行内 HTML 输出。许多 Markdown 渲染器会原样透传行内 HTML，所以在 Notion 里看到的带背景色的方框不会保留，变成平淡的默认样式文本。实际处理有两种选择：把 Callout 改写为 > 引用块（emoji 和背景色丢失），或者如果目标渲染器支持 GFM Admonition（> [!NOTE]），就转换为该语法。
Toggle 丢失折叠属性
Notion 的 Toggle 是"标题下折叠内容"的结构，但在 Markdown & CSV 导出中，折叠包裹层可能丢失，标题和正文变成并排的普通段落。如果需要在 GitHub 或静态站点中保留折叠功能，需要手动用 <details><summary>标题</summary>正文</details> 包裹。两者都是 Markdown 允许的行内 HTML。
同步块在多个文件中重复
同步块在 Notion 内部是多个页面共享同一个实体的机制，但导出时每个页面各自独立解析，相同内容被写入所有引用它的文件。如果把这个状态直接投入 RAG 流水线或搜索索引，会产生大量近似重复的块，降低检索质量。处理方式是：为每个同步块指定一个权威（canonical）页面，其余文件中的重复内容用手动或脚本删除。
公式和嵌入变成纯文本
Notion 的 LaTeX 公式以 $...$ 或 $$...$$ 纯文本形式输出。Obsidian 会将其渲染为公式，GitHub 从 2022 年起也原生支持 $…$ 和 $$…$$ 的公式渲染在新标签页中打开。其他渲染器中则显示为纯文本。视频、Figma、X（原 Twitter）嵌入通常只输出一行 URL，既不是 Markdown 图片也不是 <iframe>。
图片路径依赖导出文件夹结构
图片文件存储在各 .md 文件旁边的附件文件夹中，Markdown 内的链接以相对路径指向该文件夹。如果只把单个 .md 文件移到新位置，旁边的附件文件夹不会跟随，所有图片链接都会断裂。两种解法：文件和附件文件夹一起移动，或者把图片路径统一改写为 /assets/ 等中央目录并移动文件。
数据库导出为 CSV 而非 Markdown 表格
整页数据库以 CSV 文件形式导出，每行对应的子页面以同名文件夹内的独立 .md 文件保存。不会生成 Markdown 表格，数据库视图的筛选、排序、分组设置以及关系（Relation）、汇总（Rollup）、公式（Formula）属性也全部丢失。如果要把数据库内容用作 Markdown 表格，把 CSV 文件粘贴到 CSV to Markdown 即可立即生成管道表格。大量使用数据库的工作区，仅这一步就能大幅缩短迁移时间。
路径 B — 导出 HTML 后在浏览器内转换
页数不多，且内容属于产品规划、合同、内部知识库等严格禁止上传到外部服务器的文档时，走 HTML 导出是最快也最安全的路径。
Notion 的导出选项有 Markdown & CSV、HTML、PDF 三种。其中 HTML 对格式保留最完整：Callout 以行内 HTML 保持结构，Toggle 的包裹层保留，内部链接也保留。
操作步骤：
- 在 Notion 中打开目标页面，右上角"•••"→"导出"→"HTML"（需要时勾选包含子页面）。
- 打开生成的 .html 文件，或复制其内容。
- 粘贴到 HTML to Markdown 并点击运行。
- 将输出的 Markdown 复制到 Obsidian、CMS 或 LLM 提示词中。
所有转换处理均在用户浏览器内通过 JavaScript 执行，不产生任何外部网络请求。不需要注册账号、OAuth 授权或工作区令牌。一般的服务器上传型在线转换工具在文件上传的瞬间就把文档控制权交给了外部，而浏览器本地转换不存在网络请求，因此是安全的。
转换后保留的内容：标题、列表、链接、表格、代码块、粗体、斜体。被移除的内容：行内 style 属性、class 名、多余的包裹 <div> 标签、data-* 属性等 Markdown 没有对应语法的视觉标记。Notion Callout 标签以行内 HTML 形式保留，但 Notion 应用内的背景色等样式不会附带。如果目的是将结果交给 LLM，去除多余 HTML 标签后的 Markdown 在 token 消耗上远优于 HTML。两种格式的 token 消耗实测对比见 LLM 输入用 Markdown 还是 HTML。
路径 C — Notion Markdown Content API（API 版本 2026-03-11）
Notion 在 2026 年新增了官方 Markdown 内容端点。官方开发者文档在新标签页中打开描述了接口规格，请求时必须指定 API 版本头 2026-03-11。无需逐块遍历并转换块树，一次请求即可获取页面的 Markdown 表示。
GET /v1/pages/{id}/markdown— 以 Markdown 获取页面内容POST /v1/pages（body 含markdown）— 用 Markdown 创建新页面PATCH /v1/pages/{id}/markdown— 用 Markdown 更新已有页面内容
Notion 将这种格式称为 Enhanced Markdown。标题、列表、链接、强调遵循标准 Markdown 语法，CommonMark 没有对应语法的块用 XML 风格标签表示：Callout 为 <callout>...</callout>，Toggle 为 <details><summary>...</summary>...</details>，数据库为引用标签 <database>。下游工具如果能解析这些标签，就能保留路径 A 中丢失的信息；如果不能，在脚本中用正则表达式去除或转换即可。Public Integration 以及 Internal 和 Personal 令牌均可使用。
使用 API 时两个需要注意的点：
- 文件块（图片、PDF）返回的是带签名的临时 URL。Markdown 文本单独保存的话，之后图片链接会过期。需要在同一个任务流水线内下载文件原件。
- 超过约 20,000 个块的超大文档响应会被截断，返回
unknown_block_ids列表。剩余内容需要分批请求获取。
单次文档或不可对外共享的保密文档，路径 B（HTML 导出后浏览器转换）最快。API 在 Notion 与内部 CMS 联动、Notion 文档自动同步到 RAG 索引等自动化系统搭建时才能发挥真正价值。
对比 — 从 Notion 提取 Markdown 的四种方式
| 方式 | 适用场景 | Callout / Toggle | 是否含 UUID | 浏览器内完成 |
|---|---|---|---|---|
| 原生 Markdown & CSV 导出 | 工作区整体迁移、批量脚本整理 | Callout 为裸 HTML，Toggle 包裹层可能丢失 | 包含（文件名及链接） | 是（ZIP 本地保存） |
| Notion HTML 导出 → HTML to Markdown | 保密文档的少量页面快速转换 | Callout 保留行内 HTML，Toggle 保留 <details> | 不包含 | 是 |
| notion-to-md在新标签页中打开 npm 库 | 按块自定义转换规则 | 可按块配置 | 可配置 | 是（Node / CLI） |
Notion Markdown Content API（版本 2026-03-11） | API 令牌驱动的定期自动化流水线 | <callout> / <details> Enhanced Markdown 标签 | 不包含（无文件输出） | 否（服务端调用） |
常见问题
为什么 Notion 在导出文件名末尾附带 32 位页面 ID？
Notion 内部所有块和页面都有唯一 ID。导出时，同名页面（例如多个"会议纪要"）在同一文件夹内会冲突，因此在文件名末尾附加 32 位十六进制页面 ID。代价是文件名可读性差，以及可能触发 Windows 路径长度限制。HTML 导出和 Markdown Content API 分别以单个 HTML 文件或 API 响应处理，不存在这个问题。
把保密文档粘贴到在线转换工具安全吗？
取决于该工具是浏览器本地型还是服务器处理型。浏览器本地型（如 FormatArc 的 HTML to Markdown）在用户设备的 JavaScript 引擎中处理粘贴内容，不产生任何外发请求。服务器处理型 SaaS 会接收文件。处理产品规划、合同、未公开技术文档时，建议在浏览器开发者工具的 Network 面板中确认是否有实际请求发出，以验证数据安全。粘贴敏感数据前的验证清单见 在线工具安全检测。
应该用 API 还是导出？
定期重复的自动化任务（Notion 页面接入静态站点构建、RAG 索引自动同步、大规模定期备份等）适合用 API。一次性批量迁移且可以接受事后脚本整理的话，Markdown & CSV 导出足够。不经过服务器、把少量保密文档立刻变成干净 Markdown 的场景，HTML 导出加浏览器转换工具最高效。
Notion Markdown Content API 能保留 Callout 和 Toggle 吗？
能。以 Enhanced Markdown 标签形式保留：Callout 为 <callout>...</callout>，Toggle 为 <details><summary>...</summary>...</details>。两者都是 CommonMark 允许的行内 HTML，GitHub 等平台会将 <details> 渲染为可用的折叠块。Callout 标签在 Notion 以外的平台没有默认样式，需要自行添加 CSS 或改写为普通引用块（> ）。
导出时数据库怎么处理？
原生 Markdown & CSV 导出时，每个数据库在 ZIP 顶层生成 CSV 文件，每行对应的详细页面以 .md 文件保存在同名文件夹中。数据库的筛选、排序、分组视图以及公式、关系属性不会保留。需要把数据库内容作为 Markdown 表格使用时，把 CSV 文件粘贴到 CSV to Markdown 中即可生成管道表格。
总结
Notion 的 Markdown 导出不是"坏了"，而是有损转换。路径 A 一次获取整个工作区，代价是需要批量修正 8 种格式问题。路径 B 通过 HTML to Markdown 在浏览器内将保密文档安全转换为干净 Markdown，不需要注册账号或授权。需要自动化流水线时，Notion Markdown Content API（API 版本 2026-03-11）是实用的第三选择。需要把数据库表格转成 Markdown 时，CSV to Markdown 可以配合使用。HTML 转 Markdown 的通用方法见 HTML 转 Markdown 指南。