轻松记录您
灵感和创意

一个纯python、快速、可扩展的Markdown解释器

mistletoe

mistletoe是一个纯Python的Markdown解释器,设计成为快速、模块化和完全可定制的。

mistletoe不单单是一个Markdown-to-HTML转译器。从一开始,就设计成将Markdown解析为抽象语法树(AST)。你可以为不同的输出格式置换渲染器,而不用触碰任何核心组件。

记得用小写拼写mistletoe。

特性

快速:mistletoe与当前可获得的最快实现一样快:就是说,它比Python-Markdown快四倍,并且比Python-Markdown2快得多。通过运行以下代码来自己测试一下:

模块化:mistletoe的设计考虑了模块化。它的初始目标包含提供一个清晰易用的可扩展的API。

可定制:截止到目前,mistletoe可以将Markdown文档渲染为LaTeX,HTML和一个抽象语法树。为mistletoe写一个渲染器是一个比较容易的工作。

安装

mistletoe需要Python3.3及以上,包括Python3.7。它也在PyPy5.8.0上被测试过。

用pip安装mistletoe:

另外,clone数据仓库:

查看贡献文档,了解如何帮助mistletoe。

用法

命令行

pip安装使mistletoe在命令行有效。直接在你的shell里键入如下代码:

这会将foo.md转译成HTML,并将输出为标准输出。为了保存HTML,直接把输出转为文件:

在不指定文件的情况下运行mistletoe会以交互模式登录。就像Python的REPL,交互模式允许你测试你的Markdown如何被mistletoe解析执行:

按下Ctrl-D是告诉mistletoe去解析你的输入。Ctrl-C是退出程序。

基础用法

这是如何在你的Python脚本中使用mistletoe:

mistletoe.markdown()使用mistletoe默认的设置:允许HTML混入和渲染为HTML。该函数也接受一个附加参数:渲染器。来产生LaTeX输出:

最终,这里介绍了如何手动制定额外的token和用于mistletoe的渲染器。在下面的例子中,我们使用HTMLRenderer来渲染AST,它将HTMLBlock和HTMLSpan加入正常的解析过程中。

开发人员指南

注:mistletoe0.3显着的简化了添加自定义token的过程,但破坏了向后的兼容性。

这是一个添加Github wiki链接到解析过程的例子,并且给这个新的token提供一个渲染器。

一个新的token

Github wiki链接是跨级元素token,意味着它们是内联的,并且看起来不像大块的段落。为了写一个新的跨级元素token,我们所需要做的是创建一个SpanToken的子类:

mistletoe在解析过程中使用正则表达式搜索跨级token。作为一个复习,Github wiki看起来像这样:[[alternative text | target]]。我们定义了一个类变量,pattern,存储编译的正则表达式:

对于正则表达式的精神指导,请查看经典的xkcd(译者注:一个四格漫画)。对于这个,作者实际上使用正则表达式解析Markdown的表现,请在Greg Hendershott查看这个经典的表情包。

mistleloe的跨级token生成器会搜索我们的模式。当它找到一个匹配时,它会把匹配对象作为参数传递到我们的构造函数中。我们已经定义了我们的正则表达式,所以第一个匹配组是备选文本,第二个是链接目标。

注意,备选文本也能包含其他的跨级token。例如,[[*alt*|link]]是一个GitHubl链接,包含一个Emphasis作为其子token。为了解析子token,只需要把match_obj传递给super构造函数(假设子token放在match_obj.group(1)中),并且节省了我们需要的所有其他属性:

就这样:一个七行代码的新token。

一个新的渲染器

将一个自定义token添加到解析过程中通常会包含许多讨厌的实现细节。幸运的是,mistletoe为你考虑到了大部分细节。简单地将自定义token类传递到super().__init__()可以做到这一点:

之后我们只需要告诉mistlotoe如何去渲染我们的新token:

整理一下,我们有了新渲染器了:

试用一下?

有关更多信息,请查看mistlotoe中的base_renderer模块。文档可能会给你更多有关于定制你需要的mistlotoe的灵感。

为什么是mistlotoe?

对我来说,问题变成了:为什么不是mistune?我初始的动机真的不是想要开始一场竞争。这里有一个我最开始创建mistlotoe原因的列表:

我对在Python中Markdown-to-LaTeX转译非常感兴趣。

我想要写更多的Python。特别地,我想要尝试一些Python3.6中最前沿的东西,这反过来,让我更加的喜欢这门语言。

我暑假呆在家,没有实习,这反过来让我意识到我有多喜欢自己一个人从头编写软件。而且,全球变暖让我只能呆在屋子里。

我一直想要自己一个人从头开始写一个静态站点生成器。难题的一个关键部分就是我自己的Markdown解释器。“这能有多难?”(好吧,比我预期的要难得多。)

“为了好玩。”David Beasley这样说。

这是两件mistune启发mistlotoe去做的事:

Markdown解释器应该很快,并且比其他Python中的解释器实现要快得多。

一个Markdown解释器的实现不需要被Markdown的风格(或者说标准)所限制。

这是两件mistlotoe与mistune做的不同的地方:

根据它的自述文档,mistune始终是单文件脚本。mistlotoe将它的功能加入到了模组中。

mistune,到目前为止,只能将Markdown渲染为HTML。为mistletoe写一个渲染器相对来说比较简单。这可能会让mistlotoe看起来有一点接近MobileDoc,因为它提供了简单的Markdown附加能力,来处理各种额外的输入和输出需求。

这些影响非常的深刻,而且没有明确的这个比那个好的答案。如果有人想要使用Mistune提供的功能,它几乎是完美的:我曾经广泛地使用mistune,而且体验非常良好。如果你想要定制更多,那么,试一试mistletoe吧。

最终,引用Raymond Hettinger的话:

如果你做了一些成功的事情,你就不需要做其他不成功的事情。

在Python中到处瞎混,和重建我自己使用和喜欢的工具,是一个极其有益的经验,比竞争重要的多。

未经允许不得转载:坚果之云 Markdown » 一个纯python、快速、可扩展的Markdown解释器
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍