Markdown-it-py Plugins

Common errors

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

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

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

• 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

• pip install mdit-py-plugins Install with pip

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

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)