Markdown-It-Py Plugin Extensions
Contents
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")
See also
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: typing.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):