{"id":4101,"library":"markdown-katex","title":"markdown-katex","description":"markdown-katex is an extension for Python Markdown that adds KaTeX support. It processes LaTeX math formulas within Markdown text and converts them into HTML that can be rendered by KaTeX, often including bundled KaTeX binaries for server-side rendering, thus reducing reliance on client-side JavaScript. It primarily supports GitLab-style math delimiters. The current version is 202406.1035, with a release cadence that often aligns with KaTeX binary updates and bug fixes.","status":"active","version":"202406.1035","language":"en","source_language":"en","source_url":"https://github.com/mbarkhau/markdown-katex","tags":["markdown","latex","math","katex","extension","python-markdown"],"install":[{"cmd":"pip install markdown-katex","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This is a Python-Markdown extension, requiring the base `markdown` library to function.","package":"markdown","optional":false}],"imports":[{"symbol":"KatexExtension","correct":"from markdown_katex import KatexExtension"}],"quickstart":{"code":"import markdown\nfrom markdown_katex import KatexExtension\n\nmarkdown_text = '''\n# My Document with Math\n\nInline math: $`E=mc^2`$\n\nDisplay math:\n```math\nx = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}\n```\n'''\n\nmd = markdown.Markdown(extensions=[KatexExtension()])\nhtml = md.convert(markdown_text)\n\nprint(html)\n\n# For complete rendering, remember to include KaTeX CSS in your HTML:\n# ","lang":"python","description":"Initialize the `Markdown` parser with `KatexExtension` and convert Markdown text containing GitLab-style math formulas. The output HTML will contain the necessary KaTeX-generated markup. Note that for visual rendering, the KaTeX CSS must be linked in the final HTML document."},"warnings":[{"fix":"Ensure your Markdown content uses the GitLab-style delimiters. If you require other delimiters, you might need a different Python Markdown extension or a custom preprocessor.","message":"The `markdown-katex` extension specifically supports GitLab-style math delimiters: $`...`$ for inline math and ````math...```` for display math. Other common LaTeX delimiters like `$...$` or `$$...$$` will *not* be processed as math by this extension and will often be rendered as plain text or Markdown emphasis.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Where possible, escape problematic Markdown characters within your LaTeX (e.g., `\\_` instead of `_`). Consider adding additional Markdown extensions that handle math syntax more robustly (e.g., `pymdownx.arithmatex` in 'generic' mode, though `markdown-katex` provides its own parsing). For Python strings, use raw strings (e.g., `r'\\frac{1}{2}'`) to avoid Python's backslash escaping interfering with LaTeX.","message":"Markdown processors can interfere with LaTeX syntax. Characters like underscores (`_`), asterisks (`*`), or backslashes (`\\`) within LaTeX math formulas might be interpreted by Python Markdown (e.g., as emphasis) before `markdown-katex` can process them, leading to incorrect rendering.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always include the KaTeX CSS in your HTML `` section. Ensure your HTML files have the `` declaration at the very top.","message":"For KaTeX to render correctly in the browser, the generated HTML must include the KaTeX CSS stylesheet, typically from a CDN or a local copy. Additionally, the HTML document *must* start with `` to prevent browsers from rendering in 'quirks mode,' which can cause display issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To ensure consistent rendering, manage your `katex-cli` installation (e.g., via `npm`) carefully or ensure it matches the bundled version. If specific behavior is required, you may need to control your `PATH` environment variable or explicitly manage the `katex-cli` executable used.","message":"The `markdown-katex` extension bundles KaTeX binaries for server-side rendering, but it will prioritize using a globally installed `katex-cli` if found on the system. This can lead to unexpected behavior or version mismatches if your system's `katex-cli` is older or configured differently than the version bundled with the Python package.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}