{"id":778,"library":"mdit-py-plugins","title":"Markdown-it-py Plugins","description":"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.","status":"active","version":"0.5.0","language":"python","source_language":"en","source_url":"https://github.com/executablebooks/mdit-py-plugins","tags":["markdown","parser","plugins","markup","markdown-it"],"install":[{"cmd":"pip install mdit-py-plugins","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This library provides plugins for markdown-it-py and requires it as the core Markdown parser.","package":"markdown-it-py","optional":false},{"reason":"Requires Python 3.10 or newer.","package":"Python >=3.10","optional":false}],"imports":[{"symbol":"front_matter_plugin","correct":"from mdit_py_plugins.front_matter import front_matter_plugin"},{"symbol":"footnote_plugin","correct":"from mdit_py_plugins.footnote import footnote_plugin"},{"symbol":"deflist_plugin","correct":"from mdit_py_plugins.deflist import deflist_plugin"},{"symbol":"dollarmath_plugin","correct":"from mdit_py_plugins.dollarmath import dollarmath_plugin"},{"symbol":"sub_plugin","correct":"from mdit_py_plugins.subscript import sub_plugin"}],"quickstart":{"code":"from markdown_it import MarkdownIt\nfrom mdit_py_plugins.front_matter import front_matter_plugin\nfrom mdit_py_plugins.footnote import footnote_plugin\n\nmd = (\n    MarkdownIt('commonmark', {'breaks': True, 'html': True})\n    .use(front_matter_plugin)\n    .use(footnote_plugin, always_match_refs=True)\n    .enable('table')\n)\n\nmarkdown_input = \"\"\"\n---\ntitle: My Document\n---\n\n# Hello World\n\nThis is some text with a footnote[^1] and a table.\n\n| Header 1 | Header 2 |\n|----------|----------|\n| Cell 1   | Cell 2   |\n\n[^1]: This is the footnote content.\n\"\"\"\n\nhtml_output = md.render(markdown_input)\nprint(html_output)","lang":"python","description":"Initializes MarkdownIt with 'commonmark' preset and enables the front matter and footnote plugins, then renders a sample Markdown string to HTML."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Review custom plugins or integrations that interact with `markdown-it-py`'s `state` object and update `state.srcCharCode` to `state.src`.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"When using `footnote_plugin`, explicitly set `always_match_refs=True` or `False` based on desired behavior: `.use(footnote_plugin, always_match_refs=True)`.","message":"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.","severity":"gotcha","affected_versions":">=0.4.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.4.2"},{"fix":"Thoroughly test Markdown documents containing `dollarmath` or `amsmath` syntax after upgrading to ensure consistent rendering. Review changelogs for specific math-related fixes.","message":"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.","severity":"gotcha","affected_versions":">=0.3.5"}],"env_vars":null,"last_verified":"2026-05-12T18:57:40.574Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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)`.","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.","error":"ModuleNotFoundError: No module named 'mdit_py_plugins.footnote' (or similar plugin name)"},{"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.","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.","error":"TypeError: 'MarkdownIt' object has no attribute 'inline' or other unexpected runtime errors after updating mdit-py-plugins"},{"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.","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.","error":"Math equations (e.g., $E=mc^2$) appear as raw LaTeX in the generated HTML instead of rendered mathematical symbols."},{"fix":"Ensure your front matter adheres to strict YAML syntax and is correctly enclosed by `---` on its own lines, like so: `---\ntitle: My Document\nauthor: John Doe\n---\nYour Markdown content here.`","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.","error":"Front matter (YAML metadata at the start of a Markdown file) is not parsed, or a parsing error like 'Missing required field' occurs."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"0.6.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":3.7,"disk_size":"19.3M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":3.7,"disk_size":"19.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.15,"mem_mb":3.7,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":3.7,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.25,"mem_mb":4.1,"disk_size":"21.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":4.1,"disk_size":"21.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.22,"mem_mb":4.1,"disk_size":"22M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":4.1,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":4,"disk_size":"13.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":4,"disk_size":"13.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.24,"mem_mb":4,"disk_size":"14M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":4,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":4.6,"disk_size":"12.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":4.6,"disk_size":"12.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.21,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.24,"mem_mb":4.5,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.6,"disk_size":"18.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.6,"disk_size":"18.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.13,"mem_mb":3.6,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.6,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}