# Wiki

# Sphinx extension: mathjax / Home

## First, two important notes

- MathJax will be built into Sphinx from version 1.1 onwards, so no need for this extension anymore.
- But, you may like
of MathJax fonts file and Javascript at http://mathjax.connectmv.com**free hosting**

### 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.

### Installation

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

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 `'sphinx.ext.jsmath'`

; the `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
`pngmath`

: http://mathjax.connectmv.com/mathjax-extension/with-pngmath.html - Using the
`MathJax`

extension: http://mathjax.connectmv.com/mathjax-extension/with-mathjax.html

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: kgdunn@gmail.com

### 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.

Updated