Markdown-it-py Plugins

0.5.0 verified Tue May 12 auth: no python install: verified quickstart: verified

mdit-py-plugins is a collection of plugins for markdown-it-py, the Python Markdown parser. It provides syntax extensions for footnotes, front matter, definition lists, task lists, heading anchors, math (LaTeX), and more. The current version is 0.5.0, and the library is actively maintained with regular releases.

pip install mdit-py-plugins

Common errors

error ModuleNotFoundError: No module named 'mdit_py_plugins.footnote' (or similar plugin name) ↓

cause You are trying to import a specific plugin directly as a module, but `mdit-py-plugins` uses individual plugin functions that need to be imported from the top-level `mdit_py_plugins` package and then used with the `MarkdownIt` instance.

fix

Import the specific plugin function directly from the mdit_py_plugins package and then apply it using .use() on your MarkdownIt instance. For example, for footnotes:

from markdown_it import MarkdownIt; from mdit_py_plugins.footnote import footnote_plugin; md = MarkdownIt().use(footnote_plugin)

error TypeError: 'MarkdownIt' object has no attribute 'inline' or other unexpected runtime errors after updating mdit-py-plugins ↓

cause This often indicates a version incompatibility between `mdit-py-plugins` and its core dependency, `markdown-it-py`. Newer versions of `mdit-py-plugins` may require a more recent version of `markdown-it-py` due to API changes.

fix

Update markdown-it-py to a compatible version, typically by running pip install --upgrade markdown-it-py or specifying a version like markdown-it-py>=3.0.0,<4.0.0 in your project dependencies.

error Math equations (e.g., $E=mc^2$) appear as raw LaTeX in the generated HTML instead of rendered mathematical symbols. ↓

cause The `mdit-py-plugins` math extensions (`dollarmath_plugin`, `texmath_plugin`, `amsmath_plugin`) only parse the LaTeX syntax into HTML elements with specific classes (e.g., `<span class="math inline">E=mc^2</span>`). The actual visual rendering of these mathematical expressions requires a client-side JavaScript library like MathJax or KaTeX.

fix

Include a JavaScript library like MathJax or KaTeX in your HTML output and initialize it to process the math elements. For example, link to KaTeX CSS and JS and then run katex.renderToString on the math content.

error Front matter (YAML metadata at the start of a Markdown file) is not parsed, or a parsing error like 'Missing required field' occurs. ↓

cause Front matter parsing errors are usually due to incorrect YAML syntax or missing the required `---` delimiters at the beginning and end of the front matter block.

fix

Ensure your front matter adheres to strict YAML syntax and is correctly enclosed by --- on its own lines, like so:

---
title: My Document
author: John Doe
---
Your Markdown content here.

Warnings

breaking Python 3.7 support was dropped in v0.4.0, and Python 3.9 support was dropped in v0.5.0. Users on older Python versions must upgrade to at least Python 3.10. ↓

fix Upgrade your Python environment to 3.10 or newer.

breaking Version 0.4.0 introduced compatibility with `markdown-it-py` v3. This included an internal API change from `state.srcCharCode` to `state.src`. If you have custom plugins or deep integrations that access `markdown-it-py`'s internal `state` object, this change may break your code. ↓

fix Review custom plugins or integrations that interact with `markdown-it-py`'s `state` object and update `state.srcCharCode` to `state.src`.

gotcha In v0.4.1, the `footnote_plugin` introduced an `always_match_refs` option. The default behavior for matching footnote references might have subtle changes. If footnote references are not behaving as expected, ensure this option is configured explicitly. ↓

fix When using `footnote_plugin`, explicitly set `always_match_refs=True` or `False` based on desired behavior: `.use(footnote_plugin, always_match_refs=True)`.

gotcha Version 0.4.2 added an `allowed` option for `attrs_plugin` and `attrs_block_plugin`. Attributes not in this allowed list are moved to `token.meta["insecure_attrs"]`. This could change how attributes are processed and might affect rendering if you rely on all attributes being directly present on tokens. ↓

fix If using attribute plugins, review the new `allowed` option and explicitly configure it if specific attribute handling is required. Check `token.meta["insecure_attrs"]` for attributes that might have been filtered.

gotcha Multiple fixes and improvements have been applied to `dollarmath` and `amsmath` plugins across versions (e.g., v0.3.5, v0.4.0, v0.4.2), particularly regarding parsing of nested math. If you heavily use LaTeX math, new versions might subtly change rendering or fix previous parsing issues, requiring careful review of output. ↓

fix Thoroughly test Markdown documents containing `dollarmath` or `amsmath` syntax after upgrading to ensure consistent rendering. Review changelogs for specific math-related fixes.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.17s 19.3M

3.10 alpine (musl) - - 0.17s 19.2M

3.10 slim (glibc) wheel 1.7s 0.15s 20M

3.10 slim (glibc) - - 0.15s 20M

3.11 alpine (musl) wheel - 0.25s 21.3M

3.11 alpine (musl) - - 0.28s 21.2M

3.11 slim (glibc) wheel 1.8s 0.22s 22M

3.11 slim (glibc) - - 0.21s 22M

3.12 alpine (musl) wheel - 0.22s 13.2M

3.12 alpine (musl) - - 0.23s 13.1M

3.12 slim (glibc) wheel 1.6s 0.24s 14M

3.12 slim (glibc) - - 0.23s 14M

3.13 alpine (musl) wheel - 0.20s 12.9M

3.13 alpine (musl) - - 0.21s 12.7M

3.13 slim (glibc) wheel 1.7s 0.21s 13M

3.13 slim (glibc) - - 0.24s 13M

3.9 alpine (musl) wheel - 0.14s 18.7M

3.9 alpine (musl) - - 0.14s 18.7M

3.9 slim (glibc) wheel 2.3s 0.13s 19M

3.9 slim (glibc) - - 0.12s 19M

Imports

front_matter_plugin

from mdit_py_plugins.front_matter import front_matter_plugin

footnote_plugin

from mdit_py_plugins.footnote import footnote_plugin

deflist_plugin

from mdit_py_plugins.deflist import deflist_plugin

dollarmath_plugin

from mdit_py_plugins.dollarmath import dollarmath_plugin

sub_plugin

from mdit_py_plugins.subscript import sub_plugin

Quickstart verified last tested: 2026-04-24

Initializes MarkdownIt with 'commonmark' preset and enables the front matter and footnote plugins, then renders a sample Markdown string to HTML.

from markdown_it import MarkdownIt
from mdit_py_plugins.front_matter import front_matter_plugin
from mdit_py_plugins.footnote import footnote_plugin

md = (
    MarkdownIt('commonmark', {'breaks': True, 'html': True})
    .use(front_matter_plugin)
    .use(footnote_plugin, always_match_refs=True)
    .enable('table')
)

markdown_input = """
---
title: My Document
---

# Hello World

This is some text with a footnote[^1] and a table.

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

[^1]: This is the footnote content.
"""

html_output = md.render(markdown_input)
print(html_output)