Installing and Testing MathJax

MathJax can be loaded from a public web server or privately from your hard drive or other local media. To use MathJax in either way, you will need to obtain a copy of MathJax and its font package. There are three ways to do this: via git, svn, or via a pre-packaged archive. We recommend git or svn, as it is easier to keep your installation up to date with these tools.

Obtaining MathJax via Git

The easiest way to get MathJax and keep it up to date is to use the Git version control system to access our GitHub repository. Use the commands

git clone git://github.com/mathjax/MathJax.git mathjax

to obtain and set up a copy of MathJax. Note that there is no longer a fonts.zip file, and that the fonts directory is now part of the repository itself.

Whenever you want to update MathJax, you can now use

cd mathjax
git remote show origin

to check if there are updates to MathJax (this will print several lines of data, but the last line should tell you if your copy is up to date or out of date). If MathJax needs updating, use

cd mathjax
git pull origin

to udpate your copy of MathJax to the current release version. If you keep MathJax updated in this way, you will be sure that you have the latest bug fixes and new features as they become available.

This gets you the current development copy of MathJax, which is the “bleeding-edge” version that contains all the latest changes to MathJax. At times, however, these may be less stable than the “release” version. If you prefer to use the most stable version (that may not include all the latest patches and features), use git tag -l to see all versions and use git checkout <tag_name> to checkout that version of MathJax. When you want to upgrade to a new release, you will need to repeat this for the latest release tag.

Obtaining MathJax via SVN

If you are more comfortable with the subversion source control system, you may want to use GitHub’s svn service to obtain MathJax. If you want to get the latest revision using svn, use the commands

svn checkout http://svn.github.com/mathjax/MathJax.git mathjax

to obtain and set up a copy of MathJax. Note that there is no longer a fonts.zip file, and that the fonts directory is now part of the repository itself.

Whenever you want to update MathJax, you can now use

cd mathjax
svn status -u

to check if there are updates to MathJax. If MathJax needs updating, use

cd mathjax
svn update

to udpate your copy of MathJax to the current release version. If you keep MathJax updated in this way, you will be sure that you have the latest bug fixes and new features as they become available.

This gets you the current development copy of MathJax, which is the “bleeding-edge” version that contains all the latest changes to MathJax. At times, however, these may be less stable than the “release” version. If you prefer to use one of the tagged releases instead, then either use git as described above, or one of the archive files as described below. You can use

svn checkout http://svn.github.com/mathjax/MathJax.git@nnn mathjax

to check out revision number nnn, but it is not easy to tell what svn revision number is associated with a particular release. GitHub’s svn service doesn’t appear to allow you to sepecify a particular tagged version.

Obtaining MathJax via an archive

Release versions of MathJax are available in archive files from the MathJax download page or the GitHub downloads (click the big download button on the right), where you can download the archive that you need.

You should download the v1.1 archive (which will get you a file with a name like mathjax-MathJax-v1.1-X-XXXXXXXX.zip, where the X’s are some sequence of random-looking letters and numbers), then simply unzip it. Once the MathJax directory is unpacked, you should move it to the desired location on your server (or your hard disk, if you are using it locally rather then through a web server). One natural location is to put it at the top level of your web server’s hierarchy. That would let you refer to the main MathJax file as /MathJax/MathJax.js from within any page on your server.

From the MathJax GitHub download link (the big download button at the right), you can also select the Download .tar.gz or Download .zip buttons to get a copy of the current “bleeding-edge” version of MathJax that contains all the latest changes and bug-fixes.

Testing your installation

Use the HTML files in the test directory to see if your installation is working properly:

test/
    index.html          # Tests default configuration
    index-images.html   # Tests image-font fallback display
    sample.html         # Sample page with lots of pretty equations

Open these files in your browser to see that they appear to be working properly. If you have installed MathJax on a server, use the web address for those files rather than opening them locally. When you view the index.html file, you should see (after a few moments) a message that MathJax appears to be working. If not, you should check that the files have been transferred to the server completely, that the fonts archive has been unpacked in the correct location, and that the permissions allow the server to access the files and folders that are part of the MathJax directory (be sure to verify the MathJax folder’s permissions as well). Checking the server logs may help locate problems with the installation.

Notes about shared installations

Typically, you want to have MathJax installed on the same server as your web pages that use MathJax. There are times, however, when that may be impractical, or when you want to use a MathJax installation at a different site. For example, a departmental server at www.math.yourcollege.edu might like to use a college-wide installation at www.yourcollege.edu rather than installing a separate copy on the departmental machine. MathJax can certainly be loaded from another server, but there is one imporant caveat — Firefox’s same-origin security policy for cross-domain scripting.

Firefox’s interpretation of the same-origin policy is more strict than most other browsers, and it affects how fonts are loaded with the @font-face CSS directive. MathJax uses this directive to load web-based math fonts into a page when the user doesn’t have them installed locally on their own computer. Firefox’s security policy, however, only allows this when the fonts come from the same server as the web page itself, so if you load MathJax (and hence its web fonts) from a different server, Firefox won’t be able to access those web fonts. In this case, MathJax will pause while waiting for the font to download (which will never happen) and will time out after about 15 seconds for each font it tries to access. Typically that is three or four fonts, so your Firefox users will experience a minute or so delay before mathematics is displayed, and then it will probably display incorrectly because the browser doesn’t have access to the correct fonts.

There is a solution to this, however, if you manage the server where MathJax is installed, and if that server is running the Apache web server. In the remote server’s MathJax/fonts/HTML-CSS/TeX/otf folder, create a file called .htaccess that contains the following lines:

<FilesMatch "\.(ttf|otf|eot)$">
<IfModule mod_headers.c>
Header set Access-Control-Allow-Origin "*"
</IfModule>
</FilesMatch>

and make sure the permissions allow the server to read this file. (The file’s name starts with a period, which causes it to be an “invisible” file on unix-based operating systems. Some systems, particularly graphic user interfaces, may not allow you to create such files, so you might need to use the command-line interface to accomplish this.)

This file should make it possible for pages at other sites to load MathJax from this server in such a way that Firefox will be able to download the web-based fonts. If you want to restrict the sites that can access the web fonts, change the Access-Control-Allow-Origin line to something like:

Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"

so that only pages at www.math.yourcollege.edu will be able to download the fonts from this site. See the open font library discussion of web-font linking for more details.

Forefox and Local Fonts

Firefox’s same-origin security policy affects its ability to load web-based fonts, as described above. This has implications not only to cross-domain loading of MathJax, but also to using MathJax locally from your hard disk. Firefox’s interpretation of the same-origin policy for local files is that the “same domain” for a page is the directory where that page exists, or any of its subdirectories. So if you use MathJax in a page with a file:// URL, and if MathJax is loaded from a diretory other than the one containing the original page, then MathJax will not be able to access the web-based fonts in Firefox. In that case, MathJax will fall back on image fonts to display the mathematics.

In order for Firefox to be able to load the fonts properly for a local file, your MathJax installation must be in a subdirectory of the one containing the page that uses MathJax. This is an unfortunate restriction, but it is a limitiation imposed by Firefox’s security model that MathJax can not circumvent. Currently, this is not a problem for other browsers.