markdown-it-py

Markdown parser done right. Fast and easy to extend.

• Follows the CommonMark spec + adds syntax extensions & sugar (URL autolinking, typographer).
• Configurable syntax! You can add new rules and even replace existing ones.
• High speed.
• Safe by default.
• Pluginable

This is a Python port of markdown-it, and some of its associated plugins. It is still under development, so for now should be used with caution.

For details on markdown-it itself, see:

• The Live demo
• The markdown-it README

Table of content

• markdown-it-py
  • The Port
  • Install
  • Basic usage
  • Benchmarking
  • Syntax extensions
  • Authors
  • References / Thanks
    • Related Links
    • Other Ports

The Port

Details of the port can be found in markdown_it/port.yaml and in port.yaml within the extension folders. But the driving design philosophy has been to change as little of the fundamental code structure (file names, function name, etc) as possible, just sprinkling in a little Python syntactic sugar. It is very simple to write complimentary extensions for both language implementations!

Install

conda install -c conda-forge markdown-it-py

or

pip install markdown-it-py

Basic usage

See also:

• Using markdown_it - for an executable notebook guide to the API
• Development info - for plugins writers.

from markdown_it import MarkdownIt
from markdown_it.extensions.front_matter import front_matter_plugin
from markdown_it.extensions.footnote import footnote_plugin

md = (
    MarkdownIt()
    .use(front_matter_plugin)
    .use(footnote_plugin)
    .disable('image')
    .enable('table')
)
text = ("""
---
a: 1
---

a | b
- | -
1 | 2

A footnote [^1]

[^1]: some details
""")
tokens = md.parse(text)
html_text = md.render(text)

Also you can use it from the command-line:

$ markdown-it
markdown-it-py [version 0.1.0] (interactive)
Type Ctrl-D to complete input, or Ctrl-C to exit.
>>> > **hallo** there!
...
<blockquote>
<p><strong>hallo</strong> there!</p>
</blockquote>

Benchmarking

markdown-it-py is the fastest CommonMark compliant parser written in python!

$ markdown-it-bench -n 30
Test document: spec.md
Test iterations: 30
Running 7 test(s) ...
=====================
[mistune         (0.8.4): 3.62 s]*
markdown-it-py   (0.1.0): 9.03 s
mistletoe        (0.10.0): 9.89 s
commonmark-py    (0.9.1): 20.82 s
pymarkdown       (3.2.1): 34.50 s
pymarkdown:extra (3.2.1): 41.86 s
panflute         (1.12.5): 35.02 s

As you can see, markdown-it-py doesn't pay with speed for it's flexibility.

*Note mistune is not CommonMark compliant, which is what allows for its faster parsing, at the expense of issues, for example, with nested inline parsing. See mistletoes's explanation for further details.

Syntax extensions

Embedded (enabled when using the "default" preset configuration):

• Tables (GFM)
• Strikethrough (GFM)

Via plugins:

A list of plugins that have/can be ported:

• subscript
• superscript
• footnote
• definition list
• abbreviation
• emoji
• custom container
• insert
• mark
• ... and others

Authors

• Chris Sewell github/chrisjsewell

References / Thanks

Big thanks to the authors of markdown-it

• Alex Kocharin github/rlidwka
• Vitaly Puzrin github/puzrin

Also John MacFarlane for his work on the CommonMark spec and reference implementations.

Related Links

• https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS, also contains latest spec & online demo.
• http://talk.commonmark.org - CommonMark forum, good place to collaborate developers' efforts.

Other Ports

• motion-markdown-it - Ruby/RubyMotion