Skip to content

Latest commit

 

History

History
498 lines (436 loc) · 28.2 KB

README-zh.md

File metadata and controls

498 lines (436 loc) · 28.2 KB
Raw

Yozora
logo.png


参见 Yozora 文档 （或 备用地址） 以获得更多信息。

yozora.demo.mp4

🎉 什么是 "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 支持流式读入（采用生成器/迭代器进行输入），支持边读入边解析（暂仅限于块级数据）；

    • 在读入字符串时，会将其预处理成字符编码及位置信息，使用 NodePoint 数据类型承载。 在分词阶段通过扫描 NodePoint 的方式完成匹配，虽然匹配过程更麻烦些，但理论上性能 比正则表达式的匹配方式少一些常数；

    • 小心地处理数组新建/连接操作，整个扫描阶段尽量复用数组，仅通过下标索引来圈定匹配范围，并应用了不 少策略减少重复匹配/解析操作。

  • 🩹 兼容性，解析器解析出的 AST 与 Mdast 中定义的相兼容。即便以后如果部分数据类型 不兼容，也可以很容易通过 @yozora/ast-util 中提供的 API 去遍历 AST 以进行适配修改。

  • 🎨 可扩展性，yozora 采用中间件的方式，由内部算法驱动分词器列表完成解析工作，它带了如下能力：

    • 易于创建并集成自定义的分词器
    • 所有的分词器均可自由装载/卸载

    此项目中已实现了一些 GFM 中未提到的数据类型的分词器，如 @yozora/tokenizer-admonition, @yozora/tokenizer-footnote 等，且均已默认内置于 @yozora/parser 中。如果你不喜欢其中的某些，可以任意卸载它们。

Usage

  • @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)')

  • 将 AST 转换成标记语言（类似markdown）内容

    import { DefaultMarkupWeaver } from '@yozora/markup-weaver'

const weaver = new DefaultMarkupWeaver()
weaver.weave({
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "emphasis: "
        },
        {
          "type": "strong",
          "children": [
            {
              "type": "text",
              "value": "foo \""
            },
            {
              "type": "emphasis",
              "children": [
                {
                  "type": "text",
                  "value": "bar"
                }
              ]
            },
            {
              "type": "text",
              "value": "\" foo"
            }
          ]
        }
      ]
    }
  ]
})
// => emphasis: **foo "*bar*" foo**

Overview

💡 FAQ

💬 Contact

📄 License

Yozora 使用 MIT 许可证 进行授权。

Related