Clone wiki

Sphinx extension: mathjax / Home

First, two important notes

  1. MathJax will be built into Sphinx from version 1.1 onwards, so no need for this extension anymore.
  2. But, you may like free hosting of MathJax fonts file and Javascript at

Principle of operation

I took the Sphinx '' extension under /sphinx/ext/ and merely modified it, as appropriate, to make it work with MathJax.


1. Create a Sphinx document in the usual way: sphinx-quickstart

2. Download and add the file to your project's root (copy and paste the code).

3. Edit your document's file to remove any reference to 'sphinx.ext.pngmath' or to 'sphinx.ext.jsmath'; the extension you just downloaded will replace either of these.

4. Your document's 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.

    # -- 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 ```` file
    mathjax_path = ''

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, - please feel free to use it for your development and production servers (more details at

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:

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:

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:

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 \intertext and \dfrac. But on the whole I'm surprised by how much is actually supported! Thanks MathJax.