Python-Markdown Math Extension

Warnings

• gotcha The extension only *transforms* Markdown math into MathJax-compatible HTML (`<script type="math/tex">` tags). It does not perform server-side rendering of the math itself. For the math to display correctly in a web browser, you *must* include the MathJax (or a similar JavaScript rendering library) in your HTML output. Without it, users will only see the raw LaTeX syntax enclosed in script tags.
  Fix: Ensure your HTML output includes the MathJax library. For example: `<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js"></script>` along with its configuration.
• gotcha The single dollar sign delimiter (`$...$`) for inline math is disabled by default to prevent conflicts with normal text that may contain dollar signs (e.g., currency values). If you intend to use `$...$` for inline math, you must explicitly enable it in the extension's configuration.
  Fix: Pass `extension_configs={'mdx_math': {'enable_dollar_delimiter': True}}` when initializing the Markdown parser: `markdown.Markdown(extensions=['mdx_math'], extension_configs={'mdx_math': {'enable_dollar_delimiter': True}})`.
• gotcha The documentation's default MathJax configuration examples are primarily for MathJax 2.x. If you are using MathJax 3.x, you will need to consult the MathJax upgrading documentation to ensure correct integration, as the 2.x configurations may not be directly compatible.
  Fix: Refer to the official MathJax documentation for the appropriate configuration when using MathJax 3.x with the generated HTML output.
• gotcha Python-Markdown's default parsing can interfere with LaTeX-like math syntax by interpreting characters like `*` (asterisk) and `_` (underscore) as formatting for italics or bold, or by incorrectly handling backslashes. While `python-markdown-math` is designed to prevent this within its recognized math delimiters, conflicts may arise if math is not properly delimited or if other Markdown extensions are poorly ordered.
  Fix: Always enclose your math expressions within the defined delimiters (`\(...\)`, `\[...\]`, `$$...$$`, or `$...$` if enabled). Ensure proper extension ordering if using multiple Markdown extensions that might process similar syntax.

Install

• pip install python-markdown-math Install from PyPI

Imports

• Markdown

  import markdown
  md = markdown.Markdown(extensions=['mdx_math'])

  The 'mdx_math' string is used to enable the extension with the Python-Markdown parser. There isn't a direct Python symbol import from the `python-markdown-math` package for runtime use.

Quickstart

The quickstart demonstrates how to initialize the Python-Markdown parser with the `mdx_math` extension. It also shows how to enable the single dollar sign delimiter for inline math, which is disabled by default. The critical point is that the extension only generates MathJax-compatible HTML; actual visual rendering requires including the MathJax JavaScript library in your final HTML document.

import markdown

# Basic usage with default delimiters (\( ... \) for inline, $$ ... $$ for display)
md = markdown.Markdown(extensions=['mdx_math'])
html_output = md.convert('This is inline math: \(E=mc^2\) and a display equation: $$x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$$')
print(html_output)

# To enable single dollar sign for inline math (e.g., $E=mc^2$)
md_dollar = markdown.Markdown(extensions=['mdx_math'], extension_configs={'mdx_math': {'enable_dollar_delimiter': True}})
html_output_dollar = md_dollar.convert('Inline math with single dollar: $E=mc^2$')
print(html_output_dollar)

# Important: The generated HTML requires a client-side MathJax (or similar) library to render the math visually.
# Example of how the output will look (not fully rendered math without MathJax JS in browser):
# <p>This is inline math: <script type="math/tex">E=mc^2</script> and a display equation: <script type="math/tex; mode=display">x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}</script></p>