First, two important notes
- MathJax will be built into Sphinx from version 1.1 onwards, so no need for this extension anymore.
Principle of operation
I took the Sphinx 'jsmath.py' extension under /sphinx/ext/jsmath.py and merely modified it, as appropriate, to make it work with MathJax.
1. Create a Sphinx document in the usual way:
2. Download and add the
mathjax.py file to your project's root (copy and paste the code).
3. Edit your document's
conf.py file to remove any reference to
'sphinx.ext.pngmath' or to
mathjax.py extension you just downloaded will replace either of these.
4. Your document's
conf.py should appear similar to this:
import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.append(os.path.abspath('.')) # -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.todo', 'sphinx.ext.ifconfig'] extensions.append('mathjax') # or point to the ``mathjax.py`` file mathjax_path = 'http://mathjax.connectmv.com/MathJax.js'
The last line tells the extension where to find your MathJax installation by adding that string to the
<script> section of Sphinx's HTML output.
I run a MathJax installation at the above address, http://mathjax.connectmv.com/MathJax.js - please feel free to use it for your development and production servers (more details at http://mathjax.connectmv.com).
However, please replace that
mathjax_path with your own installation, if you prefer.
- For production servers: point it to your server's MathJax location.
- Please see this thread for how people use MathJax during document development.
Note: hopefully MathJax will be providing a publicly available installation via a CDN that you can use in your projects.
See it in action
To compare this extension to the built-in Sphinx 'pngmath' extension, please open these two links side-by-side:
- Using the
These two pages used RST code from the Sphinx documentation. Please note, I can't explain the reason for the missing equation numbers in MathJax.
I have used this extension on a number of websites:
- A course on numerical methods
- Commenting system for Sphinx documents that allows for math in comments.
License, copyright, and assistance
This extension is licensed under the new 3-clause BSD license. Please email the author for assistance or if there are any problems with these instructions: firstname.lastname@example.org
Cases when this code might not work for you
MathJax supports the vast majority of LaTeX's math markup. A few items that I find (annoyingly) don't work are
\dfrac. But on the whole I'm surprised by how much is actually supported! Thanks MathJax.