Markdown-it-py Plugins

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)