Registry / serialization / mdit-py-plugins

mdit-py-plugins

library0.5.0pypypi✓ verified 49d ago

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.

serialization

pip install mdit-py-plugins

github ↗package ↗docs ↗

Install & Compatibility

Where this runs

tested against v0.6.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.197s · 19.3MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.8s · import 0.189s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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)

Debug

Known issues

breakingPython 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.

affects: >=0.4.0

breakingVersion 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`.

affects: >=0.4.0

gotchaIn 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)`.

affects: >=0.4.1

gotchaVersion 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.

affects: >=0.4.2

gotchaMultiple 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.

affects: >=0.3.5

Errors

Common errors & fixes

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

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)`.

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

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.

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

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.

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

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.`

Upgrade

Version history

0.6.1latest on PyPI

Audit

Dependencies

markdown-it-pyrequiredThis library provides plugins for markdown-it-py and requires it as the core Markdown parser.

Python >=3.10requiredRequires Python 3.10 or newer.

Agent activity

14 hits · last 30 days

ahrefsbot

seranking-bot

node

Amazon

chatgpt-user

Resources

githubhttps://github.com/executablebooks/mdit-py-plugins ↗

packagehttps://pypi.org/project/mdit-py-plugins/ ↗

docshttps://mdit-py-plugins.readthedocs.io ↗