Plugin extensions¶

The following plugins are embedded within the core package (enabled when using the "default" preset configuration):

tables (GFM)
strikethrough (GFM)

Other plugins are then available via the mdit_py_plugins.

Important

markdown_it.extensions is now deprecated and plugins have been moved to mdit_py_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*")

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:

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.

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
---

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

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

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=True, allow_space=True, allow_digits=True)[source]

Plugin for parsing dollar enclosed math, e.g. $a=1$ .

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.

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*}

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.

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

There are also many other plugins which could easily be ported (and hopefully will be):

markdown-it-py

Plugin extensions¶