玩转Markdown(2)——抽象语法树的提取与操纵

yuyutoo 2024-12-24 16:33 3 浏览 0 评论

上一篇玩转Markdown —— 数据的分离存储与组件的原生渲染发布，转眼已经鸽了大半年了。最近在操纵 mdast 生成 md 文件的时候，心血来潮，把 玩转Markdown(2) 给补上了。

这一篇我们一起来聊聊 markdown 的抽象语法树(Abstract Syntax Tree): 以下简称 mdast

AST 不是银弹

这是必须先声明的一点。

若你的需求，仅仅是写一篇 md 文档，那么你仅仅只需要一个好用的 md 编辑器 (个人推荐 vscode with markdown plugin)。

若你的需求稍微复杂一点，比如涉及到数据映射来自动生成 md 文档，那么 一门编程语言 + 字符串操作 + 文件数据流 就适合你。

但是，假如你的需求更进一步，说要把 md 文件转换成 html，vue，react 组件，又或者说你要扩展 md 的语法，用 md 内嵌 silde 做成 ppt 。或者说你要把jsx 嵌入 md ，成为一种全新的文件格式 (mdx)。那么此时解析操纵 mdast 就显得相对合适了，虽说 mdast 也能解决上面 2 个问题，但是把简单的问题复杂化，不符合我们写代码的本意，你说是不？

普遍的 AST

我们经常拆解各种语言，比如用 acorn babel 解析 js,ts, 用 postcss 转换 css，scss，less 。

同样 html 也能变成 hast，markdown 也能解析成 mdast ,更不用说 /.+.(?:(?:(?:wx|ax|jx|ks|tt|q)ml)|swan)$/ 这类的变体了。

如果你写过 webpack，rollup，postcss 插件，一定对此不陌生。

它们通过各种形式，运行在我们的应用中，只是它们往往被封装了起来，我们感受不到它们的存在罢了。

Markdown AST

在看这段时，希望你对 markdown 语法了然于胸。

提到 mdast 就不得不提到 unifiedjs 和它的 rehype , retext , remark。它是一个语法树的统一解决方案，本篇文章不介绍它的用法。

让我们来看 syntax-tree 中关于 mdast 的定义。

它把 Nodes(节点) 大概分成了这些：

Parent: 父节点基类继承用，用于声明 children 数组
Literal: 字面量基类继承用，用于声明 value 值
Root: 继承 Parent，根节点
Paragraph: 最常用的承载内容的段落,对应 html里的 p
Heading: (h1,h2,h3,h4,h5,h6)
ThematicBreak: --- *** 语法，对应 html 里的 hr
Blockquote: > 语法，对应 html 里的 blockquote
List: 对应 html 里的 ul,ol，用于声明列表
ListItem: 对应 html 里的 li, 同字面意思 List 里的 Item
HTML: markdown 中可内嵌 html，所以内部的 html 被转换为 HTML节点，内部的 value 则为 html 字符串
Code: ``` 语法，用的超级多，最常见的就是给代码块染色，如 ```js,```html,```css 等等，通常需要配合代码高亮 lib 来染色
Definition: md变量定义，如: [Alpha]: https://example.com
Text: 最常用的节点类型，仅仅只是文本
Emphasis: *alpha* _bravo_ 对应 html 中的 <em>
Strong: **alpha** __bravo__ 对应 html 中的 <strong>
InlineCode: `InlineCode` => InlineCode
Break: (2个空格) or ··，一行的换行，它不像，这个换行还是在之前的 Paragraph 内的
Link: html 的 <a>，在熟悉不过了 [alpha](https://example.com "bravo")
Image: html 的 <img>,也是在熟悉不过了 ![alpha](https://example.com/favicon.ico "bravo")
LinkReference: 链接引用变量的节点，结合 Definition 使用，如 [alpha][Bravo]
ImageReference: 同上，不过只是图片引用变量的节点

这些节点，就是对经典的 markdown 语法的一层抽象，相比 js 来说，markdown语法和 ast 真的是太简单了。

构建

有了上列的基础，接下来我们自己来构建一棵 mdast

yarn add @types/mdast mdast-util-to-markdown

import type {
  Root,
  Paragraph,
  Heading,
  ThematicBreak,
  Blockquote,
  List,
  ListItem,
  HTML,
  Code,
  Definition,
  Text,
  Emphasis,
  Strong,
  InlineCode,
  Break,
  Link,
  Image,
  LinkReference,
  ImageReference
} from 'mdast'

// 存放你的内容
const children : Content[] = [] 
const astTree: Root = {
  type: 'root',
  children
}

这样 mdast 就构建成功了。

转化

import { toMarkdown } from 'mdast-util-to-markdown'
// 生成 markdwon 字符串
toMarkdown(astTree)

这样从 mdast 就转化到了 markdown 了，实在是非常简单。

解析

import { fromMarkdown } from 'mdast-util-from-markdown'
const doc = fs.readFileSync('example.md')
const astTree = fromMarkdown(doc)

添加目录TOC

import { toc } from 'mdast-util-toc'
const tocResult = toc(tree, {
  tight: true
})
if (tocResult.map) {
  // 把目录添加到第一个节点后
  tree.children.splice(1, 0, tocResult.map)
}

更多操作

mdast-util-* 还有很多工具包，同时 remark,unified,mdx,vfile,Syntax tree 生态也欣欣向荣，我们完全可以自由的组合它们，达成我们想要的目的。

实战自动生成

写一个包，自动拉取 Github 项目，生成带目录和语言分类的 README.md 文件。

能同时发布在 Github Action 和 npm 上，同时要对代码进行 tree-shaking, 避免 @actions/core , @actions/github 发布到 npm , @octokit/* 发布到 Github Action。

Github marketplace: 地址

npm: 地址

源码见: github-repository-distributor

markdown 语法