此页面需要javascript支持,请在浏览器中启用javascript

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

ast
md
markdown
mdast
共1221个字,阅读时间 6 分钟
版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接: https://icebreaker.top/articles/2022/3/23-play-markdown-2-ast

Image

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

前言

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

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

AST 不是银弹

这是必须先声明的一点。

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

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

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

普遍的 AST

我们经常拆解各种语言,比如用 acorn babel 解析 js,ts, 用 postcss 转换 cssscssless

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

如果你写过 webpackrolluppostcss 插件,一定对此不陌生。

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

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 ··,一行的换行,它不像 \n,这个换行还是在之前的 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

有了上列的基础,接下来我们自己来构建一棵 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 就构建成功了。

转化 markdown 字符串

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

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

解析 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 生态也欣欣向荣,我们完全可以自由的组合它们,达成我们想要的目的。

实战自动生成 markdown 案例

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

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

Github marketplace: 地址

npm: 地址

源码见: github-repository-distributor