Markdown-It-Py Plugin Extensions¶

Built-in¶

The following plugins are embedded within the core package:

tables (GFM)
strikethrough (GFM)

These can be enabled individually:

from markdown_it import MarkdownIt
md = MarkdownIt("commonmark").enable('table')

or as part of a configuration:

from markdown_it import MarkdownIt
md = MarkdownIt("gfm-like")

mdit-py-plugins package¶

The mdit_py_plugins, contains a number of common plugins. They can be chained and loaded via:

from markdown_it import MarkdownIt
from mdit_py_plugins import plugin1, plugin2
md = MarkdownIt().use(plugin1, keyword=value).use(plugin2, keyword=value)
html_string = md.render("some *Markdown*")

Front-Matter¶

mdit_py_plugins.front_matter.front_matter_plugin(md: markdown_it.main.MarkdownIt)[source]¶

Plugin ported from markdown-it-front-matter.

It parses initial metadata, stored between opening/closing dashes:

---
valid-front-matter: true
---

Footnotes¶

mdit_py_plugins.footnote.footnote_plugin(md: markdown_it.main.MarkdownIt)[source]¶

Plugin ported from markdown-it-footnote.

It is based on the pandoc definition:

Normal footnote:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

Definition Lists¶

mdit_py_plugins.deflist.deflist_plugin(md: markdown_it.main.MarkdownIt)[source]¶

Plugin ported from markdown-it-deflist.

The syntax is based on pandoc definition lists:

Term 1
: Definition 1 long form

  second paragraph

Term 2 with *inline markup*
~ Definition 2a compact style
~ Definition 2b

Task lists¶

mdit_py_plugins.tasklists.tasklists_plugin(md: markdown_it.main.MarkdownIt, enabled: bool = False, label: bool = False, label_after: bool = False)[source]¶

Plugin for building task/todo lists out of markdown lists with items starting with [ ] or [x] .. Nothing else

For example::

[ ] An item that needs doing
[x] An item that is complete

The rendered HTML checkboxes are disabled; to change this, pass a truthy value into the enabled property of the plugin options.

Parameters

enabled – True enables the rendered checkboxes
label – True wraps the rendered list items in a <label> element for UX purposes,
label_after – True – adds the <label> element after the checkbox.

Heading Anchors¶

mdit_py_plugins.anchors.anchors_plugin(md: markdown_it.main.MarkdownIt, min_level: int = 1, max_level: int = 2, slug_func: Optional[Callable[[str], str]] = None, permalink: bool = False, permalinkSymbol: str = '¶', permalinkBefore: bool = False, permalinkSpace: bool = True)[source]¶

Plugin for adding header anchors, based on markdown-it-anchor

# Title String

renders as:

<h1 id="title-string">Title String <a class="header-anchor" href="#title-string">¶</a></h1>

Parameters

min_level – minimum header level to apply anchors
max_level – maximum header level to apply anchors
slug_func – function to convert title text to id slug.
permalink – Add a permalink next to the title
permalinkSymbol – the symbol to show
permalinkBefore – Add the permalink before the title, otherwise after
permalinkSpace – Add a space between the permalink and the title

Note, the default slug function aims to mimic the GitHub Markdown format, see:

Word Count¶

mdit_py_plugins.wordcount.wordcount_plugin(md: markdown_it.main.MarkdownIt, *, per_minute: int = 200, count_func: Callable[[str], int] = <function basic_count>, store_text: bool = False)[source]¶

Plugin for computing and storing the word count.

Stores in the env e.g.:

env["wordcount"] = {
  "words": 200
  "minutes": 1,
}

If “wordcount” is already in the env, it will update it.

Parameters

per_minute – Words per minute reading speed
store_text – store all text under a “text” key, as a list of strings

Containers¶

mdit_py_plugins.container.container_plugin(md: markdown_it.main.MarkdownIt, name: str, marker: str = ':', validate: Optional[Callable[[str, str], bool]] = None, render=None)[source]¶

Plugin ported from markdown-it-container.

It is a plugin for creating block-level custom containers:

:::: name
::: name
*markdown*
:::
::::

Parameters

name – the name of the container to parse
marker – the marker character to use
validate – func(marker, param) -> bool, default matches against the name
render – render func

Math¶

mdit_py_plugins.texmath.texmath_plugin(md: markdown_it.main.MarkdownIt, delimiters='dollars', macros: Optional[dict] = None)[source]¶

Plugin ported from markdown-it-texmath.

It parses TeX math equations set inside opening and closing delimiters:

$\alpha = \frac{1}{2}$

Parameters: delimiters – one of: brackets, dollars, gitlab, julia, kramdown

mdit_py_plugins.dollarmath.dollarmath_plugin(md: markdown_it.main.MarkdownIt, allow_labels: bool = True, allow_space: bool = True, allow_digits: bool = True, double_inline: bool = False) → None [source]¶

Plugin for parsing dollar enclosed math, e.g. inline: $a=1$ , block: $$b=2$$

This is an improved version of texmath; it is more performant, and handles \ escaping properly and allows for more configuration.

Parameters

allow_labels – Capture math blocks with label suffix, e.g. $$a=1$$ (eq1)
allow_space – Parse inline math when there is space after/before the opening/closing $, e.g. $ a $
allow_digits – Parse inline math when there is a digit before/after the opening/closing $, e.g. 1$ or $2. This is useful when also using currency.
double_inline – Search for double-dollar math within inline contexts

mdit_py_plugins.amsmath.amsmath_plugin(md: markdown_it.main.MarkdownIt)[source]¶

Parses TeX math equations, without any surrounding delimiters, only for top-level amsmath environments:

\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}

MyST plugins¶

myst_blocks and myst_role plugins are also available, for utilisation by the MyST renderer

mdit_py_plugins.myst_role.myst_role_plugin(md: markdown_it.main.MarkdownIt)[source]¶: Parse {role-name}`content`

mdit_py_plugins.myst_blocks.myst_block_plugin(md: markdown_it.main.MarkdownIt)[source]¶: Parse MyST targets ((name)=), blockquotes (% comment) and block breaks (+++).

Write your own¶

Use the mdit_py_plugins as a guide to write your own, following the markdown-it design principles.

There are many other plugins which could easily be ported from the JS versions (and hopefully will):