sphinxcontrib-katex

0.9.11 verified Mon Apr 27 auth: no python

A Sphinx extension for rendering LaTeX math in HTML pages using KaTeX. Current version is 0.9.11, compatible with Python >=3.9. Released irregularly.

pip install sphinxcontrib-katex

Common errors

error Extension error: Could not import extension sphinxcontrib.katex (exception: No module named 'sphinxcontrib') ↓

cause Missing sphinxcontrib package or incorrect import path.

fix

Install sphinxcontrib-katex via pip: pip install sphinxcontrib-katex

error WARNING: katex_version '0.15.0' is not supported. Minimum required is 0.16.0 ↓

cause KaTeX version too old for this extension version.

fix

Set katex_version to >=0.16.0 in conf.py, e.g., katex_version = '0.16.9'

Warnings

breaking In v0.9.0+, the extension requires KaTeX >=0.16.0. Older KaTeX versions are not supported and will fail to render. ↓

fix Update katex_version to >=0.16.0 in conf.py or let it default.

gotcha The extension does not automatically download KaTeX. It expects KaTeX JS/CSS to be present in the _static directory or served via CDN. If you see blank pages, you may need to install KaTeX manually or adjust the path. ↓

fix Set katex_css_path and katex_js_path in conf.py to point to your KaTeX assets.

deprecated The option 'katex_css_host' was deprecated in v0.8.0 and removed in v0.9.0. Use 'katex_css_path' and 'katex_js_path' instead. ↓

fix Replace katex_css_host with katex_css_path and katex_js_path.

Imports

katex

wrong

extensions = ['sphinxcontrib-katex']

correct

extensions = ['sphinxcontrib.katex']

Uses dot notation, not hyphen

Quickstart

Enable the extension in Sphinx conf.py and optionally specify KaTeX version (defaults to latest available).

# conf.py
extensions = ['sphinxcontrib.katex']
katex_version = '0.16.9'