Yozora
🎉 什么是 "yozora" ?
yozora 是日语「よぞら」的罗马音,意为“夜空”,取自世界の終わり乐队的 『花鳥風月』中的歌词。
此项目是一个 monorepo,目的是实现一个高度可扩展的、可插拔式 Markdown 解析器。 它采用了中间件的思想,由核心算法 @yozora/core-parser 调度分词器(如 @yozora/tokenizer-autolink)完成解析工作。准确地说,yozora 是一个将 Markdown 语法或其扩展语法编写的字符串解析成抽象语法树(AST)的算法。
✨ Features
-
🔖 完整地支持了 GFM 规范 中提到的所有规则,并通过了几乎所有由规范 中的示例改造成的测试用例(除了由示例 https://github.github.com/gfm/#example-653 所展示的标签过滤规则, 因为我不打算让 Yozora AST 的 React 渲染器 支持原生的 HTML 标签,所以懒得做标签过滤,如果有需要可以自行做一下过滤)。
可参见 @yozora/parser-gfm or @yozora/parser-gfm-ex 以获得进一步信息。
-
🚀 健壮性:
- 所有代码都采用 Typescript 编写,拥有严格地静态类型检查的保障;
- 使用 eslint 和 prettier 约束编码风格,规避了偏僻语法及 shadow variables 之类 易于出错的问题;
- 使用了大量的测试用例进行测试;
-
💚 干净,零第三方依赖。
-
⚡️ 高性能
-
解析复杂度为字符串长度乘以分词器列表长度,已经达到了理论复杂度的下界;
-
解析器的 API 支持流式读入(采用生成器/迭代器进行输入),支持边读入边解析 (暂仅限于块级数据);
-
在读入字符串时,会将其预处理成字符编码及位置信息,使用 INodePoint 数据类型承载。在分词阶段通过扫描 INodePoint 的方式完成匹配, 虽然匹配过程更麻烦些,但理论上性能比正则表达式的匹配方式少一些常数;
-
小心地处理数组新建/连接操作,整个扫描阶段尽量复用数组,仅通过下标索引来圈定 匹配范围,并应用了不少策略减少重复匹配/解析操作。
-
-
🩹 兼容性,解析器解析出的 AST 与 [Mdast][mdast-homepage] 中定义的相兼容。即便 以后如果部分数据类型不兼容,也可以很容易通过 @yozora/ast-util 中提供的 API 去遍历 AST 以进行适配修改。
-
🎨 可扩展性,yozora 采用中间件的方式,由内部算法驱动分词器列表完成解析工作, 它带了如下能力:
- 易于创建并集成自定义的分词器
- 所有的分词器均可自由装载/卸载
此项目中已实现了一些 GFM 中未提到的数据类型的分词器,如 @yozora/tokenizer-admonition, @yozora/tokenizer-footnote 等,且均已默认内置于 @yozora/parser 中。如果 你不喜欢其中的某些,可以任意卸载它们。
📝 Usage
- YozoraParser
- GfmParser
- GfmExParser
@yozora/parser: (推荐)内置了所有分词器的 Markdown 解析器。
import YozoraParser from '@yozora/parser'
const parser = new YozoraParser()
parser.parse('source content')
@yozora/parser-gfm: 支持 GFM 规范 的 Markdown 解析器。内置 了支持 GFM 规范 中提到的所有语法(不包含规范中提到的扩展语法,如 table)的分词器。
import GfmParser from '@yozora/parser-gfm'
const parser = new GfmParser()
parser.parse('github flavor markdown contents')
@yozora/parser-gfm-ex: 支持 GFM 规范 的 Markdown 解析器。 内置 了支持 GFM 规范 中提到的所有语法(包括规范中提到的扩展语法,如 table)的分词器。
import GfmExParser from '@yozora/parser-gfm-ex'
const parser = new GfmExParser()
parser.parse('github flavor markdown contents (with gfm extensions enabled)')
💡 FAQ
-
如何在 gatsby 中使用 yozora?
-
如何实现自定义的分词器?
-
使用脚手架工具 @yozora/template-tokenizer 去创建一个由预定义模板生成的分 词器项目(或 monorepo 中的一个 package);
-
参见 @yozora/core-tokenizer 以获得分词器的生命周期函数细节;
-
参见 @yozora/jest-for-tokenizer 以获得测试自定义分词器相关的信息;
-
参考 @yozora/core-parser 和 @yozora/parser 以获得如何使用自定义分词 器的信息;
可参见现有的 分词器 以作参考。
-
💬 Contact
📄 License
Yozora 使用 MIT 许可证 进行授权。
Related
- ✨光和尘一直想要一个清爽博客: 为什么要写这个项目。
- @yozora/react-markdown: 一个用于将 Yozora AST 渲染成 React 组件的库。
- @yozora/html-markdown: 一个用于将 Yozora AST 渲染成 HTML 字符串的库。