Plugin extensions

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

Other plugins are then available via the mdit_py_plugins.


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>
  • 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
  • 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}$

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.

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

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.

  • 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):