Martian: Markdown 到 Notion 解析器

将 Markdown 和 GitHub 风格的 Markdown 转换为 Notion API 块和富文本。

Martian 是一个 Markdown 解析器，可以将任何 Markdown 内容转换为 Notion API 块或富文本对象。它使用 unified 创建 Markdown 抽象语法树（AST），然后将 AST 转换为 Notion 对象。

旨在使 Notion SDK 和 API 的使用更加简便。适用于 Notion API 1.0 版本。

支持的 Markdown 元素

所有内联元素（斜体、粗体、删除线、内联代码、超链接、方程式）
列表（有序、无序、复选框）- 支持任意深度
所有标题（3级及以上的标题都被视为3级标题）
代码块，支持语言高亮
引用块
表格
方程式
图片
- 内联图片会从段落中提取并在后面添加（因为 Notion 不支持内联图片）
- 图片 URL 会进行验证，如果不符合 Notion 外部规范，将以文本形式插入，供您手动修复

使用方法

基本用法：

该包导出两个函数，您可以按以下方式导入：

// JS
const {markdownToBlocks, markdownToRichText} = require('@tryfabric/martian');
// TS
import {markdownToBlocks, markdownToRichText} from '@tryfabric/martian';

以下是两个函数的使用示例：

markdownToRichText(`**Hello _world_**`);

<details> <summary>结果</summary> <pre> [ { "type": "text", "annotations": { "bold": true, "strikethrough": false, "underline": false, "italic": false, "code": false, "color": "default" }, "text": { "content": "Hello " } }, { "type": "text", "annotations": { "bold": true, "strikethrough": false, "underline": false, "italic": true, "code": false, "color": "default" }, "text": { "content": "world" } } ] </pre> </details>

markdownToBlocks(`
hello _world_ 
*** 
## heading2
* [x] todo
`);

<details> <summary>结果</summary> <pre> [ { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [ { "type": "text", "annotations": { "bold": false, "strikethrough": false, "underline": false, "italic": false, "code": false, "color": "default" }, "text": { "content": "你好 " } }, { "type": "text", "annotations": { "bold": false, "strikethrough": false, "underline": false, "italic": true, "code": false, "color": "default" }, "text": { "content": "世界" } } ] } }, { "object": "block", "type": "heading_2", "heading_2": { "rich_text": [ { "type": "text", "annotations": { "bold": false, "strikethrough": false, "underline": false, "italic": false, "code": false, "color": "default" }, "text": { "content": "二级标题" } } ] } }, { "object": "block", "type": "to_do", "to_do": { "rich_text": [ { "type": "text", "annotations": { "bold": false, "strikethrough": false, "underline": false, "italic": false, "code": false, "color": "default" }, "text": { "content": "待办事项" } } ], "checked": true } } ] </pre> </details>

处理Notion的限制

有时，Markdown输入可能会导致输出被Notion API拒绝：以下是一些处理这种情况的选项。

项目超出子项或字符限制

默认情况下，该包会尝试通过将内容重新分配到多个块来解决此类问题：当无法做到这一点时，martian会截断输出以避免您的请求导致错误。如果您想禁用这种行为，可以使用以下选项：

const options = {
  notionLimits: {
    truncate: false,
  },
};

markdownToBlocks('输入', options);
markdownToRichText('输入', options);

手动处理与Notion限制相关的错误

您可以为结果项超出Notion限制时设置回调函数。请注意，无论最终输出是否会被截断，此函数都会被调用。

const options = {
  notionLimits: {
    // truncate: true, // 默认值
    onError: (err: Error) => {
      // 发生了某些情况！
      console.error(err);
    },
  },
};

markdownToBlocks('输入', options);
markdownToRichText('输入', options);

处理图片

如果图片的URL无效，Notion API将拒绝整个请求：martian通过将无效链接的图片转换为文本来防止这个问题，这样请求就能成功，您以后可以修复链接。如果您想禁用这种行为，可以使用以下选项：

const options = {
  strictImageUrls: false,
};

默认行为：

markdownToBlocks('![](https://raw.githubusercontent.com/tryfabric/martian/master/InvalidURL)');

禁用strictImageUrls：

markdownToBlocks('![](https://raw.githubusercontent.com/tryfabric/martian/master/InvalidURL)', {
  strictImageUrls: false,
});

<details> <summary>结果</summary> <pre> [ { "object": "block", "type": "image", "image": { "type": "external", "external": { "url": "无效URL" } } } ] </pre> </details>

解析富文本时的非内联元素

默认情况下，如果提供给markdownToRichText的文本会产生一个或多个非内联元素，该包会忽略这些元素，只解析段落。你可以通过将nonInline选项设置为'throw'来使包在检测到非内联元素时抛出错误。

默认行为：

markdownToRichText('# 标题\nAbc', {
  // nonInline: 'ignore', // 默认
});

<details> <summary>结果</summary> <pre> [ { type: 'text', annotations: { bold: false, strikethrough: false, underline: false, italic: false, code: false, color: 'default' }, text: { content: 'Abc', link: undefined } } ] </pre> </details>

抛出错误：

markdownToRichText('# 标题\nAbc', {
  nonInline: 'throw',
});

<details> <summary>结果</summary> <pre> 错误：不支持的markdown元素：{"type":"heading","depth":1,"children":[{"type":"text","value":"标题","position":{"start":{"line":1,"column":3, "offset":2},"end":{"line":1,"column":9,"offset":8}}}],"position":{"start":{"line":1,"column":1,"offset":0},"end":{"line":1,"column":9,"offset":8}}} </pre> </details>

由Fabric背后的团队用💙构建。