一個純python、快速、可擴展的Markdown解釋器

Python部落(python.freelycode.com)組織翻譯，禁止轉載，歡迎轉發。

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中到處瞎混，和重建我自己使用和喜歡的工具，是一個極其有益的經驗，比競爭重要的多。

英文原文：https://github.com/miyuchina/mistletoe

譯者：南北丶

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！