构建一个 mdx-remark 插件

什么是 MDX?

MDX 是MarkDown的超集, 在支持MarkDown语法的基础上, 允许我们引入jsx, 以使用更丰富的组件

同时 MDX 提供了 remark 和 rehype 的插件机制, 使得可以在 MDX 中处理MarkDown标签, 使我们可以更加自由的渲染页面

什么是 remark 和 rehype?

remark 用于处理md的AST, rehype 用于处理html的AST

要想理解他们, 首先我们要了解AST(Abstract Syntax Tree): 抽象语法树

它通过树状结构描述了代码的语法结构, 使我们可以对代码进行分析和处理, 可以参考如下文件:

1
# 标题
2

3
```js
4
const a = 1
5
```

1
{
2
  "type": "root",
3
  "children": [
4
        {
5
              "type": "heading",
6
              "depth": 1,
7
              "children": [
8
                    {
9
                      "type": "text",
10
                      "value": "标题"
11
                    }
12
              ]
13
        },
14
        {
15
              "type": "code",
16
              "lang": "js",
17
              "value": "const a = 1"
18
        }
19
  ]
20
}

1
<h1>标题</h1>
2
<pre><code class="language-js">const a = 1</code></pre>

开始编写一个 remark 插件

安装好必要的依赖后, 首先在配置中引入插件 (以 astro 为例)

1
import { defineConfig } from "astro/config";
2
import { unified } from "@astrojs/markdown-remark";
3
import { pluginFunc } from "./remark-plugin.mjs";
4

5
export default defineConfig({
6
      markdown: {
7
            processor: unified({
8
                  remarkPlugins: [pluginFunc],
9
                  rehypePlugins: [],
10
            }),
11
      }
12
})

其中remark-plugin.mjs是自定义的插件

pluginFunc是一个返回(tree)=>{...}的闭包函数

其最简示例如下:

1
export function remarkContainer() {
2
  return (tree) => {
3
    const { children } = tree;
4
    let index = 0;
5

6
    while (index < children.length) {
7
      const node = children[index];
8

9
      // 寻找起始标记 :::name
10
      if (
11
        node.type === "paragraph" &&
12
        node.children.length === 1 &&
13
        node.children[0].type === "text"
14
      ) {
15
        const marker = node.children[0].value.match(/^:::(\w+)\s*$/);
16

17
        if (marker) {
18
          const name = marker[1];
19
          let closeIndex = -1;
20

21
          // 寻找闭合标记
22
          for (let i = index + 1; i < children.length; i++) {
23
            const c = children[i];
24
            if (
25
              c.type === "paragraph" &&
26
              c.children.length === 1 &&
27
              c.children[0].type === "text" &&
28
              c.children[0].value.trim() === ":::"
29
            ) {
30
              closeIndex = i;
31
              break;
32
            }
33
          }
34

35
          // 修改内容
36
          if (closeIndex !== -1) {
37
            const containerChildren = children.slice(index + 1, closeIndex);
38
            const newNode = {
39
              type: "newContainer",
40
              name: name,
41
              children: containerChildren,
42
            };
43
            children.splice(index, closeIndex - index + 1, newNode);
44
            index++;
45
            continue;
46
          }
47
        }
48
      }
49
      index++;
50
    }
51
  };
52
}

重点分为两个步骤, 1.寻找标记, 2.修改内容

以上函数会将:::name ... :::打包到新的节点

代码演示

1
# 标题
2

3
:::warning
4
这是**警告**
5
:::

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "heading",
6
      "depth": 1,
7
      "children": [ { "type": "text", "value": "标题" } ]
8
    },
9
    {
10
      "type": "paragraph",
11
      "children": [ { "type": "text", "value": ":::warning" } ]
12
    },
13
    {
14
      "type": "paragraph",
15
      "children": [
16
        { "type": "text", "value": "一个" },
17
        { "type": "strong", "children": [ { "type": "text", "value": "警告" } ] }
18
      ]
19
    },
20
    {
21
      "type": "paragraph",
22
      "children": [ { "type": "text", "value": ":::" } ]
23
    }
24
  ]
25
}

1
{
2
  "type": "root",
3
  "children": [
4
    {
5
      "type": "heading",
6
      "depth": 1,
7
      "children": [ { "type": "text", "value": "标题" } ]
8
    },
9
    {
10
      "type": "newContainer",
11
      "name": "warning",
12
      "children": [
13
        {
14
          "type": "paragraph",
15
          "children": [
16
            { "type": "text", "value": "一个" },
17
            { "type": "strong", "children": [ { "type": "text", "value": "警告" } ] }
18
          ]
19
        }
20
      ]
21
    }
22
  ]
23
}

1
<h1>标题</h1>
2
<div class="warning">
3
    <p>这是一个<strong>警告</strong></p>
4
</div>