mistletoe is a Markdown parser in pure Python, designed to be fast, spec-compliant and fully customizable.

Apart from being the fastest CommonMark-compliant Markdown parser implementation in pure Python, mistletoe also supports easy definitions of custom tokens. Parsing Markdown into an abstract syntax tree also allows us to swap out renderers for different output formats, without touching any of the core components.


This is a version of mistletoe maintained by the Excutable Book Project (EBP). It contains many improvements (see the myst branch of ExecutableBookProject/mistletoe for details) which eventually, it is hoped, will be merged into mistletoe itself.


  • Fast: mistletoe is the fastest implementation of CommonMark in Python, that is, 2 to 3 times as fast as Commonmark-py, and still roughly 30% faster than Python-Markdown. Running with PyPy yields comparable performance with mistune. See the Performance section for details.

  • Spec-compliant: CommonMark is a useful, high-quality project. mistletoe follows the CommonMark specification to resolve ambiguities during parsing. Outputs are predictable and well-defined.

  • Clear API: Documents can be built and assessed programatically, in an object-orientated manner. See Programmatic Use and Syntax API for details.

  • Extensible: Strikethrough and tables are supported natively, and custom block-level and span-level tokens can easily be added. Writing a new renderer for mistletoe is a relatively trivial task. See the Developer section for details.

  • LSP compliant: mistletoe-ebp aims to make it easy to use in implementations of the Language Server Protocol, the requirements being that; (a) it is thread-safe for asynchronous parsing, and (b) the line and character ranges of the source text are recorded for each element in the syntax tree.

Some alternative output formats:

Why mistletoe?

“For fun,” says David Beazley.