Contents

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.

Field Lists

mdit_py_plugins.field_list.fieldlist_plugin(md: markdown_it.main.MarkdownIt)[source]

Field lists are mappings from field names to field bodies, based on the reStructureText syntax.

:name *markup*:
:name1: body content
:name2: paragraph 1

        paragraph 2
:name3:
  paragraph 1

  paragraph 2

A field name may consist of any characters except colons (“:”). Inline markup is parsed in field names.

The field name is followed by whitespace and the field body. The field body may be empty or contain multiple body elements. The field body is aligned either by the start of the body on the first line or, if no body content is on the first line, by 2 spaces.

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, label_normalizer: Optional[Callable[[str], str]] = None, renderer: Optional[Callable[[str, Dict[str, Any]], str]] = None, label_renderer: Optional[Callable[[str], str]] = None) → 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

  • label_normalizer – Function to normalize the label, by default replaces whitespace with -

  • renderer – Function to render content: (str, {“display_mode”: bool}) -> str, by default escapes HTML

  • label_renderer – Function to render labels, by default creates anchor

mdit_py_plugins.amsmath.amsmath_plugin(md: markdown_it.main.MarkdownIt, *, renderer: Optional[Callable[[str], str]] = None)[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*}
Parameters

renderer – Function to render content, by default escapes HTML

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