Markdown-It-Py Plugin Extensions

Built-in

The following plugins are embedded within the core package:

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

See also

See Using markdown_it

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