mistletoe is a Markdown parser in pure Python, designed to be fast, modular and fully customizable.
- Python Markdown Syntax
- Python Markdown Syntax Interview
- Python Markdown Syntax
- Python Markdown Tutorial
mistletoe is not simply a Markdown-to-HTML transpiler. It is designed, from the start, to parse Markdown into an abstract syntax tree. You can swap out renderers for different output formats, without touching any of the core components.
Remember to spell mistletoe in lowercase!
Markdown is a lightweight Markup language with a plain text syntax. John Gruber developed the Markdown language in 2004 in a collaborative effort with Aaron Swartz, intending to enable people to.
Fast: mistletoe is as fast as the fastest implementation currently available: that is, over 4 times faster than Python-Markdown, and much faster than Python-Markdown2. Try the benchmarks yourself by running:
Modular: mistletoe is designed with modularity in mind. Its initial goal is to provide a clear and easy API to extend upon.
Customizable: as of now, mistletoe can render Markdown documents to LaTeX, HTML and an abstract syntax tree out of the box. Writing a new renderer for mistletoe is a relatively trivial task.
- Pydocmd can generate plain Markdown files from Python modules using the pydocmd simple command. Specify one or more module names on the command-line. Supports the + syntax to include members of the module (or to include members of the members, etc.) pydocmd simple mypackage+ mypackage.mymodule+ docs.md.
- The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text. For any markup that is not covered by Markdown’s syntax.
mistletoe requires Python 3.3 and above, including Python 3.7, the current development branch. It is also tested on PyPy 5.8.0. Install mistletoe with pip:
Alternatively, clone the repo:
See the contributing doc for how to contribute to mistletoe.
From the command-line
pip installation enables mistletoe's commandline utility. Type the following directly into your shell:
This will transpile
foo.md into HTML, and dump the output to stdout. To save the HTML, direct the output into a file:
mistletoe without specifying a file will land you in interactive mode. Like Python's REPL, interactive mode allows you to test how your Markdown will be interpreted by mistletoe:
Ctrl-D tells mistletoe to interpret your input.
Ctrl-C exits the program.
Here's how you can use mistletoe in a Python script:
mistletoe.markdown() uses mistletoe's default settings: allowing HTML mixins and rendering to HTML. The function also accepts an additional argument
renderer. To produce LaTeX output:
Finally, here's how you would manually specify extra tokens and a renderer for mistletoe. In the following example, we use
HTMLRenderer to render the AST, which adds
HTMLSpan to the normal parsing process.
Note: mistletoe 0.3 significantly simplifies the process of adding your custom tokens, but breaks backwards compatibility. Oh well.
Here's an example to add GitHub-style wiki links to the parsing process, and provide a renderer for this new token.
A new token
Python Markdown Syntax
GitHub wiki links are span-level tokens, meaning that they reside inline, and don't really look like chunky paragraphs. To write a new span-level token, all we need to do is make a subclass of
mistletoe uses regular expressions to search for span-level tokens in the parsing process. As a refresher, GitHub wiki looks something like this:
[[alternative text target]]. We define a class variable,
pattern, that stores the compiled regex:
For spiritual guidance on regexes, refer to xkcd classics. For an actual representation of this author parsing Markdown with regexes, refer to this brilliant meme by Greg Hendershott.
mistletoe's span-level tokenizer will search for our pattern. When it finds a match, it will pass in the first matching group as argument (
raw). In our case, this happens to be the entire link with enclosing brackets, so we still need to do some dirty string manipulation:
alt can also contain other span-level tokens. For example,
[[*alt* link]] is a GitHub link with an
Emphasis token as its child. To parse child tokens, simply pass it to the
super constructor, and save off all the additional attributes we need:
After some cleaning-up, this is what our new token class looks like:
A new renderer
Adding a custom token to the parsing process usually involves a lot of nasty implementation details. Fortunately, mistletoe takes care of most of them for you. Simply pass your custom token class to
super().__init__() does the trick:
We then only need to tell mistletoe how to render our new token:
Cleaning up, we have our new renderer class:
Take it for a spin?
For more info, take a look at the
base_renderer module in mistletoe. The docstrings might give you a more granular idea of customizing mistletoe to your needs.
For me, the question becomes: why not mistune? My original motivation really has nothing to do with starting a competition. Here's a list of reasons I created mistletoe in the first place:
- I am interested in a Markdown-to-LaTeX transpiler in Python.
- I want to write more Python. Specifically, I want to try out some bleeding edge features in Python 3.6, which, in turn, makes me love the language even more.
- I am stuck at home during summer vacation without an internship, which, in turn, makes me realize how much I love banging out software from scratch, all by myself. Also, global warming keeps me indoors.
- I have long wanted to write a static site generator, from scratch, by myself. One key piece of the puzzle is my own Markdown parser. 'How hard could it be?' (well, quite a lot harder than I expected.)
- 'For fun,' says David Beasley.
Here's two things mistune inspired mistletoe to do:
- Markdown parsers should be fast, and other parser implementations in Python leaves much to be desired.
- A parser implementation for Markdown does not need to restrict itself to one flavor (or, 'standard') of Markdown.
Here's two things mistletoe does differently from mistune:
- Per its readme, mistune will always be a single-file script. mistletoe breaks its functionality into modules.
- mistune, as of now, can only render Markdown into HTML. It is relatively trivial to write a new renderer for mistletoe.
- This might make mistletoe look a bit closer to MobileDoc, in that it gives simple Markdown additional power to deal with a variety of additional input and output demands.
Python Markdown Syntax Interview
The implications of these are quite profound, and there's no definite this-is-better-than-that answer. Mistune is near perfect if one wants what it provides: I have used mistune extensively in the past, and had a great experience. If you want more control, however, give mistletoe a try.
Python Markdown Syntax
Finally, to quote Raymond Hettinger:
If you make something successful, you don't have to make something else unsuccessful.
Messing around in Python and rebuilding tools that I personally use and love is an immensely more rewarding experience than competition.
Copyright & License
Python Markdown Tutorial
- mistletoe's logo uses artwork by Daniele De Santis, under CC BY 3.0.
- mistletoe is released under MIT.