UI组件前端【免费下载链接】react-notion-xFast and accurate React renderer for Notion. TS batteries included. ⚡️项目地址https://gitcode.com/gh_mirrors/re/react-notion-x点击查看免费下载导读在 react-notion-x 生态中notion-x-to-md 负责把 Notion 页面转换为 GitHub Flavored MarkdownGFM是让 Notion 内容进入 LLM 上下文、构建知识库或静态博客的常用桥梁。本文以仓库中的 Checklists 转换示例 为线索完整讲解 Notion 待办清单to_do块如何被渲染为- [x]/- [ ]任务列表并深入源码剖析其判定逻辑、类型约束与快照测试最后给出可直接运行的调用与 CLI 方案。读完你将掌握待办清单块的转换规则、notionPageToMarkdown的完整调用链以及如何用一条命令把任意公开 Notion 页面转成 Markdown。一、示例文档还原to_do块的转换输出仓库中的 38fa73d49b8f40aab1f3f8c82332e518.md 是一个专门用于验证待办清单转换能力的示例页面其转换结果如下# Checklists This block type is called to_do - [x] Pretty URLs - [x] Custom domains - [x] Google Fonts - [x] Page title/description for SEO - [x] Custom scripts - [x] A setup wizard to customize the script (instead of having to change the raw code) - [ ] Stop random pages from showing up under custom domain - [ ] Hide the Whats New banner这个输出揭示了三条关键事实页面标题被渲染为 H1# Checklists来自页面的 title 属性引用块被渲染为 GFM 引用 This block type is called to_do对应 Notion 中的 quote 块每个待办项都被渲染为 GFM 任务列表项已勾选输出- [x]未勾选输出- [ ]。该页面在 readme.md 的示例索引表 中被标记为Checklists / Supported ✅页面 ID 为38fa73d49b8f40aab1f3f8c82332e518与当前文档文件名一致。二、源码级剖析to_do块如何变成- [x]2.1 渲染入口renderBlock的to_do分支notion-x-to-md 的核心渲染函数是 src/block.ts 中的renderBlock它接收(blockId, recordMap, level)先从recordMap.block中取出原始块数据再根据块的type字段分发到对应分支。待办清单的分支位于 src/block.ts#L98-L102case to_do: { const checked (block as any).properties?.checked?.[0]?.[0] Yes const checkbox checked ? - [x] : - [ ] return ${checkbox} ${getTitle(block, recordMap)} }这段实现非常简洁却包含了完整的状态判定逻辑取勾选状态block.properties?.checked是一个二维数组[0][0]取到的是单元格中的第一个 token。当该值严格等于字符串Yes时判定为已勾选映射为 GFM 语法已勾选输出- [x]未勾选输出- [ ]这是 GitHub Flavored Markdown 任务列表task list的标准写法拼接标题文本getTitle在 src/block.ts#L398-L400 中实现它调用decorationsToMarkdown(block.properties?.title ?? [], recordMap)将标题的富文本 decoration 还原为 Markdown 文本粗体、斜体、链接、提及等都会被正确还原。2.2 类型约束TodoBlock的数据结构to_do块的类型定义位于 packages/notion-types/src/block.ts#L244-L251// TODO export interface TodoBlock extends BaseTextBlock { type: to_do properties: { title: Decoration[] checked: ([Yes] | [No])[] } }可以看到BlockType联合类型中注册了to_do见 packages/notion-types/src/block.ts#L15checked属性被严格建模为([Yes] | [No])[]这与渲染端 Yes的判定完全吻合每个待办项都拥有独立的titleDecoration 数组与checked状态因此同一个清单里已勾选与未勾选项可以混合出现正如示例文档展示的 6 项[x] 2 项[ ]。2.3 与 React 渲染端的对照验证同一块类型在 react-notion-x 的 React 渲染端 src/block.tsx#L800-L821 中也有对应实现case to_do: { const isChecked block.properties?.checked?.[0]?.[0] Yes return ( div className{cs(notion-to-do, blockId)} div classNamenotion-to-do-item components.Checkbox blockId{blockId} isChecked{isChecked} / ...两个渲染端采用了完全相同的判定表达式checked?.[0]?.[0] Yes可以确认这是 react-notion-x 生态中处理待办状态的事实标准。差别只在于输出形态React 端渲染为带勾选框的 DOM样式见 packages/react-notion-x/src/styles.css#L2199 的notion-to-do-checked规则Markdown 端则映射为- [x]/- [ ]。三、调用链与用法如何复现这份输出3.1 编程方式调用示例输出的完整生成链路是NotionAPI.getPage拉取页面 →notionPageToMarkdown递归渲染所有块。notionPageToMarkdown定义在 src/notion-page-to-markdown.ts#L17-L25export async function notionPageToMarkdown( recordMap: ExtendedRecordMap ): Promisestring { const rootBlockId Object.keys(recordMap.block)[0] if (!rootBlockId) return const markdown await renderBlock(rootBlockId, recordMap) return markdown.trim() }函数以recordMap.block的第一个 key 作为根页面块调用renderBlock递归渲染整棵块树最后trim()去除首尾空白。值得注意的是它必须为async——因为渲染过程中可能拉取远程资源如 tweet 嵌入见 tweet 分支。子块通过renderBlockChildren以p-map并发concurrency: 4渲染见 src/block.ts#L379-L396。完整的可运行示例摘自 packages/notion-x-to-md/readme.md#L27-L40import { NotionAPI } from notion-client import { notionPageToMarkdown } from notion-x-to-md const api new NotionAPI() // fetch a notion pages content const page await api.getPage(38fa73d49b8f40aab1f3f8c82332e518) // convert the page to a markdown string const markdown await notionPageToMarkdown(page) console.log(markdown)要点无需 API Key不要求创建 Notion 官方 API 集成只要页面是公开可访问的即可见 readme.md 的 Notes输出为 GFMnotion-x-to-md明确输出 GitHub Flavored Markdown这对 LLM 的解析尤为友好Node 版本要求engines.node 18见 package.json。3.2 CLI 一行命令除编程调用外包还内置了 CLIbin字段指向 src/cli.ts由 commander 实现。直接用npx运行即可npx -y notion-x-to-md https://notion.so/38fa73d49b8f40aab1f3f8c82332e518或直接传页面 IDnpx -y notion-x-to-md 38fa73d49b8f40aab1f3f8c82332e518CLI 的完整用法摘自 readme.mdUsage: notion-x-to-md [options] page Converts a Notion page to Markdown Arguments: page Notion page ID or URL (must be publicly accessible) Options: -h, --help display help for commandpage参数既支持完整 URL也支持不带连字符的 32 位页面 ID由NotionAPI.getPage统一解析。3.3 安装方式npm install notion-x-to-md该包以notion-client、notion-types、notion-utils为 workspace 依赖见 package.json构建工具为 tsdown测试使用 vitest typecheck。四、测试与快照示例文档是持续集成的产物examples/38fa73d49b8f40aab1f3f8c82332e518.md并非手写文档而是测试管线自动生成的产物。src/notion-page-to-markdown.test.ts 中的测试会用new NotionAPI().getPage(id)拉取真实公开页面调用notionPageToMarkdown转换断言输出非空、首尾无多余空白并与快照比对。测试文件中的writeExamples开关test 文件 L32-L49在开启时会把转换结果写入examples/pageId.md因此该目录下的每个.md文件都可以视为一个渲染正确性快照。对应的快照位于 src/snapshots/index.test.ts.snap#L469-L483exports[notionPageToMarkdown success 38fa73d49b8f40aab1f3f8c82332e518 1] # Checklists This block type is called \to_do\ - [x] Pretty URLs ...快照内容与 examples 目录 完全一致从测试角度再次证实只要 Notion 页面结构不变to_do块的 Markdown 输出就是稳定、可预期的。五、相关设计细节与注意事项5.1 状态语义Yes字符串的来由Notion 私有 API 中勾选框类属性的原始值就是字符串Yes/No这一点在集合database属性渲染中同样成立见 src/property.ts#L35-L38 中 checkbox 属性渲染为✓/✗的逻辑。因此转换器直接与原始数据比对不经过任何布尔转换判定唯一且无歧义。5.2 待办项的富文本to_do分支中的getTitle复用了通用标题渲染逻辑因此待办项文本内可以包含粗体、斜体、删除线、行内代码、链接、页面引用、 提及、日期等所有 text.ts 支持的 decoration 类型它们都会被还原为对应 Markdown 语法后再拼接到- [x]/- [ ]之后。5.3 适用范围与限制仅支持公开可访问的 Notion 页面Notion 托管的临时图片 URL 在一段时间后会失效与官方 Notion 应用行为一致如需永久链接可对getPage返回的ExtendedRecordMap做后处理将临时图片上传至永久 URL 并保存 block ID 到 URL 的映射见 readme.md 的 Notes集合database会被统一渲染为 Markdown 表格所有视图类型一视同仁。六、小结围绕 Checklists 示例 这一最小但完整的样例可以梳理出一条清晰的转换链路数据来源NotionAPI.getPage拉取ExtendedRecordMap其中to_do块携带title与checkedYes/No属性判定规则checked?.[0]?.[0] Yesblock.ts#L99 与 notion-types block.ts#L249 双重印证输出形态- [x] 文本/- [ ] 文本即标准 GFM 任务列表天然被 GitHub 与主流 LLM 良好解析可验证性快照测试保证了输出的确定性examples 目录即测试产物。对于任何需要把 Notion 待办清单接入 AI 工作流的开发者npx -y notion-x-to-md 页面ID已经是一条足够可靠的最小路径而当你需要把勾选状态、富文本样式或自定义映射融入业务逻辑时renderBlock的to_do分支则是理想的改造锚点。赞分享UI组件前端【免费下载链接】react-notion-xFast and accurate React renderer for Notion. TS batteries included. ⚡️项目地址https://gitcode.com/gh_mirrors/re/react-notion-x点击查看免费下载相关推荐notion-x-to-md 代码块转换全解析从 Notion Code Block 到 GitHub 风格 Markdownnotion x to md 代码块转换全解析从 Notion Code Block 到 GitHub 风格 Markdown 本篇指南以 react notUI组件前端react-notion-x 的 notion-x-to-md 集合数字格式化渲染实战从 Notion 数据到 Markdown 表格react notion x 的 notion x to md 集合数字格式化渲染实战从 Notion 数据到 Markdown 表格 导读 本文围绕 notUI组件前端react-notion-x 系列实战用 notion-x-to-md 将 Notion 页面转换为 Markdown喂给 LLM 的完整方案react notion x 系列实战用 notion x to md 将 Notion 页面转换为 Markdown喂给 LLM 的完整方案 这篇指南围绕UI组件前端上一篇FreeRTOS OTA 回滚机制3 步看懂升级失败如何恢复下一篇终极指南解决ESP32 Arduino开发中NetworkClientSecure库SSL编译失败的完整方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考