mistletoe
mistletoe copied to clipboard
A fast, extensible and spec-compliant Markdown parser in pure Python.
mistletoe![](https://cdn.rawgit.com/miyuchina/mistletoe/master/resources/logo.svg)
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.
Remember to spell mistletoe in lowercase!
Features
-
Fast: mistletoe is the fastest implementation of CommonMark in Python. 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.
-
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.
You can even write a Lisp in it.
Output formats
Renderers for the following "core" output formats exist within the mistletoe module itself:
- HTML
- LaTeX
- AST (Abstract Syntax Tree; handy for debugging the parsing process)
Renderers for the following output formats are placed in the contrib folder:
- HTML with MathJax (mathjax.py)
- HTML with code highlighting (using Pygments) (pygments_renderer.py)
- HTML with TOC (for programmatical use) (toc_renderer.py)
- HTML with support for GitHub wiki links (github_wiki.py)
- Jira Markdown (jira_renderer.py)
- XWiki Syntax (xwiki20_renderer.py)
- Scheme (scheme.py)
Installation
mistletoe is tested for Python 3.5 and above. Install mistletoe with pip:
pip3 install mistletoe
Alternatively, clone the repo:
git clone https://github.com/miyuchina/mistletoe.git
cd mistletoe
pip3 install -e .
This installs mistletoe in "editable" mode (because of the -e
option).
That means that any changes made to the source code will get visible
immediately - that's because Python only makes a link to the specified
directory (.
) instead of copying the files to the standard packages
folder.
See the contributing doc for how to contribute to mistletoe.
Usage
Usage from Python
Here's how you can use mistletoe in a Python script:
import mistletoe
with open('foo.md', 'r') as fin:
rendered = mistletoe.markdown(fin)
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:
import mistletoe
from mistletoe.latex_renderer import LaTeXRenderer
with open('foo.md', 'r') as fin:
rendered = mistletoe.markdown(fin, LaTeXRenderer)
Finally, here's how you would manually specify extra tokens via a renderer.
In the following example, we use HTMLRenderer
to render
the AST. The renderer itself adds HTMLBlock
and HTMLSpan
tokens to the parsing
process. The result should be equal to the output obtained from
the first example above.
from mistletoe import Document, HTMLRenderer
with open('foo.md', 'r') as fin:
with HTMLRenderer() as renderer: # or: `with HTMLRenderer(AnotherToken1, AnotherToken2) as renderer:`
doc = Document(fin) # parse the lines into AST
rendered = renderer.render(doc) # render the AST
# internal lists of tokens to be parsed are automatically reset when exiting this `with` block
Important: As can be seen from the example above,
the parsing phase is currently tightly connected with initiation
and closing of a renderer. Therefore, you should never call Document(...)
outside of a with ... as renderer
block, unless you know what you are doing.
Usage from command-line
pip installation enables mistletoe's command-line utility. Type the following directly into your shell:
mistletoe foo.md
This will transpile foo.md
into HTML, and dump the output to stdout. To save
the HTML, direct the output into a file:
mistletoe foo.md > out.html
You can use a different renderer by including the full path to the renderer
class after a -r
or --renderer
flag. For example, to transpile into
LaTeX:
mistletoe foo.md --renderer mistletoe.latex_renderer.LaTeXRenderer
Note: The renderers inside the contrib
directory are not currently a part of
the mistletoe
module when mistletoe is installed as a regular package.
So if you want to use a renderer from the contrib
directory, you either
have to add that directory to Python's PYTHONPATH
or install mistletoe with the -e
switch (see Installation).
mistletoe interactive mode
Running 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:
mistletoe [version 0.7.2] (interactive)
Type Ctrl-D to complete input, or Ctrl-C to exit.
>>> some **bold** text
... and some *italics*
...
<p>some <strong>bold</strong> text
and some <em>italics</em></p>
>>>
The interactive mode also accepts the --renderer
flag:
mistletoe [version 0.7.2] (interactive)
Type Ctrl-D to complete input, or Ctrl-C to exit.
Using renderer: LaTeXRenderer
>>> some **bold** text
... and some *italics*
...
\documentclass{article}
\begin{document}
some \textbf{bold} text
and some \textit{italics}
\end{document}
>>>
Who uses mistletoe?
mistletoe is used by projects of various target audience. You can find some concrete projects in the "Used by" section on Libraries.io, but this is definitely not a complete list. Also a list of Dependents is tracked by GitHub directly.
Run mistletoe from CopyQ
One notable example is running mistletoe as a Markdown converter from the advanced clipboard manager called CopyQ. One just needs to install the Convert Markdown to ... custom script command and then run this command on any selected Markdown text.
Why mistletoe?
"For fun," says David Beazley.
Further reading
- Performance
- Developer's Guide