Markdown-It-Py Plugin Extensions

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: MarkdownIt) → None[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: MarkdownIt, *, inline: bool = True, move_to_end: bool = True, always_match_refs: bool = False) → None[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.

Parameters:

inline – If True, also parse inline footnotes (^[…]).
move_to_end – If True, move footnote definitions to the end of the token stream.
always_match_refs – If True, match references, even if the footnote is not defined.

Definition Lists#

mdit_py_plugins.deflist.deflist_plugin(md: MarkdownIt) → None[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: MarkdownIt, enabled: bool = False, label: bool = False, label_after: bool = False) → None[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: MarkdownIt) → None[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.

Since the field marker may be quite long, the second and subsequent lines of the field body do not have to line up with the first line, but they must be indented relative to the field name marker, and they must line up with each other.

Heading Anchors#

mdit_py_plugins.anchors.anchors_plugin(md: MarkdownIt, min_level: int = 1, max_level: int = 2, slug_func: Callable[[str], str] | None = None, permalink: bool = False, permalinkSymbol: str = '¶', permalinkBefore: bool = False, permalinkSpace: bool = True) → None[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: ~collections.abc.Callable[[str], int] = <function basic_count>, store_text: bool = False) → None[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: MarkdownIt, name: str, marker: str = ':', validate: None | Callable[[str, str], bool] = None, render: None | Callable[[...], str] = None) → 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.admon.admon_plugin(md: MarkdownIt, render: None | Callable[[...], str] = None) → None[source]#

Plugin to use python-markdown style admonitions.

!!! note
    *content*

And mkdocs-style collapsible blocks.

???+ note
    *content*

Note, this is ported from markdown-it-admon.

Attributes#

mdit_py_plugins.attrs.attrs_plugin(md: MarkdownIt, *, after: Sequence[str] = ('image', 'code_inline', 'link_close', 'span_close'), spans: bool = False, span_after: str = 'link', allowed: Sequence[str] | None = None) → None[source]#

Parse inline attributes that immediately follow certain inline elements:

![alt](https://image.com){#id .a b=c}

This syntax is inspired by Djot spans.

Inside the curly braces, the following syntax is possible:

.foo specifies foo as a class. Multiple classes may be given in this way; they will be combined.
#foo specifies foo as an identifier. An element may have only one identifier; if multiple identifiers are given, the last one is used.
key=”value” or key=value specifies a key-value attribute.
Quotes are not needed when the value consists entirely of ASCII alphanumeric characters or _ or : or -. Backslash escapes may be used inside quoted values.
% begins a comment, which ends with the next % or the end of the attribute (}).

Multiple attribute blocks are merged.

Parameters:

md – The MarkdownIt instance to modify.
after – The names of inline elements after which attributes may be specified. This plugin does not support attributes after emphasis, strikethrough or text elements, which all require post-parse processing.
spans – If True, also parse attributes after spans of text, encapsulated by []. Note Markdown link references take precedence over this syntax.
span_after – The name of an inline rule after which spans may be specified.
allowed – A list of allowed attribute names. If not None, any attributes not in this list will be removed and placed in the token’s meta under the key “insecure_attrs”.

mdit_py_plugins.attrs.attrs_block_plugin(md: MarkdownIt, *, allowed: Sequence[str] | None = None) → None[source]#

Parse block attributes.

Block attributes are attributes on a single line, with no other content. They attach the specified attributes to the block below them:

{.a #b c=1}
A paragraph, that will be assigned the class ``a`` and the identifier ``b``.

Attributes can be stacked, with classes accumulating and lower attributes overriding higher:

{#a .a c=1}
{#b .b c=2}
A paragraph, that will be assigned the class ``a b c``, and the identifier ``b``.

This syntax is inspired by Djot block attributes.

Parameters:: allowed – A list of allowed attribute names. If not None, any attributes not in this list will be removed and placed in the token’s meta under the key “insecure_attrs”.

Math#

mdit_py_plugins.texmath.texmath_plugin(md: MarkdownIt, delimiters: str = 'dollars', macros: Any | None = None) → 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: MarkdownIt, *, allow_labels: bool = True, allow_space: bool = True, allow_digits: bool = True, allow_blank_lines: bool = True, double_inline: bool = False, label_normalizer: Callable[[str], str] | None = None, renderer: Callable[[str, dict[str, Any]], str] | None = None, label_renderer: Callable[[str], str] | None = 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.
allow_blank_lines – Allow blank lines inside $$. Note that blank lines are not allowed in LaTeX, executablebooks/markdown-it-dollarmath, or the Github or StackExchange markdown dialects. Hoever, they have special semantics if used within Sphinx ..math admonitions, so are allowed for backwards-compatibility.
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: MarkdownIt, *, renderer: Callable[[str], str] | None = None) → 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

Subscripts#

mdit_py_plugins.subscript.sub_plugin(md: MarkdownIt) → None[source]#

Markdown-it-py plugin to introduce <sub> markup using ~subscript~.

Ported from markdown-it/markdown-it-sub

Originally ported during implementation of hasgeek/funnel

Superscript#

mdit_py_plugins.superscript.superscript_plugin(md: MarkdownIt) → None[source]#

Superscript (<sup>) tag plugin for Markdown-It-Py.

This plugin is ported from markdown-it-sup. Markup is based on the Pandoc superscript extension.

Place superscripted text within caret ^ characters. You must escape any spaces in the superscripted text. Note that you cannot use newline or tab characters, and that nested markup is not supported.

Example usage:

>>> from markdown_it import MarkdownIt
>>> from mdit_py_plugins.superscript import superscript_plugin
>>> md = MarkdownIt().use(superscript_plugin)
>>> md.render("1^st^")
'<p>1<sup>st</sup></p>\n'
>>> md.render("this^text\\ has\\ spaces^")
'<p>this<sup>text has spaces</sup></p>\n'

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: MarkdownIt) → None[source]#: Parse {role-name}`content`

mdit_py_plugins.myst_blocks.myst_block_plugin(md: MarkdownIt) → None[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):

Markdown-It-Py Plugin Extensions

Contents

Markdown-It-Py Plugin Extensions#

Built-in#

mdit-py-plugins package#

Front-Matter#

Footnotes#

Definition Lists#

Task lists#

Field Lists#

Heading Anchors#

Word Count#

Containers#

Attributes#

Math#

Subscripts#

Superscript#

MyST plugins#

Write your own#