Sphinx Contrib JSMath

1.0.1 · active · verified Sun Mar 29

Sphinxcontrib-jsmath is a Sphinx extension that enables rendering of display math in HTML output via JavaScript, utilizing the older jsMath library. It is often chosen for its smaller JavaScript package size compared to newer alternatives like MathJax. The current version is 1.0.1, last released in January 2019, but it continues to receive compatibility updates for newer Sphinx versions through various distribution packages.

Warnings

gotcha The underlying jsMath library, on which this Sphinx extension relies, is no longer actively developed. This means new math rendering features or bug fixes specific to the JavaScript rendering engine are unlikely to be implemented.
Fix: Be aware of the limitations of an older rendering engine. For more actively maintained math rendering, consider `sphinx.ext.mathjax`.
breaking The import path for this extension changed. For Sphinx versions 4.0 and newer, `sphinx.ext.jsmath` is no longer a valid entry for `extensions` in `conf.py`.
Fix: Always use `'sphinxcontrib.jsmath'` in your `extensions` list in `conf.py`. This change was introduced in Sphinx 2.0, with the alias for the old path removed in 4.0.
gotcha The `jsmath_path` configuration variable has no default value. You must explicitly set this path in your `conf.py` to the location of the `jsMath/easy/load.js` file. Failure to do so will result in math not being rendered in your HTML output.
Fix: Ensure `jsmath_path` is correctly configured in `conf.py` to point to the `jsMath/easy/load.js` file, typically within your `_static` directory or an external URL.
gotcha Due to the `jsMath` library's age, it may have known bugs or suboptimal rendering with very old or specific browser versions (e.g., Opera 9.5, MSIE). While these browsers are largely obsolete, it highlights the legacy nature of the underlying technology.
Fix: Modern browsers should render correctly, but be aware of potential issues with extremely old or niche browser environments.

Install

pip install sphinxcontrib-jsmath Install with pip

Imports

Extension Configuration
```
extensions = ['sphinxcontrib.jsmath']
```
The old 'sphinx.ext.jsmath' path was moved to 'sphinxcontrib.jsmath' in Sphinx 2.0 and the alias removed in Sphinx 4.0. Always use 'sphinxcontrib.jsmath' for modern Sphinx versions.

Quickstart

To enable sphinxcontrib-jsmath, add 'sphinxcontrib.jsmath' to the `extensions` list in your Sphinx project's `conf.py` file. Additionally, you must configure `jsmath_path` to point to the `jsMath/easy/load.js` file, which typically resides in your Sphinx project's `_static` directory after you've manually downloaded the jsMath library.

# conf.py

# Add 'sphinxcontrib.jsmath' to the list of extensions
extensions = [
    'sphinxcontrib.jsmath',
    # ... other extensions
]

# Set the path to the jsMath library.
# This example assumes jsMath is placed in your Sphinx project's _static directory,
# e.g., <your_project_root>/_static/jsMath/easy/load.js
# You need to download the jsMath library separately and place it there.
# If jsMath is hosted externally, provide the full URL.
jsmath_path = 'jsMath/easy/load.js'

view raw JSON →