Attention
Version 3 is now the current version of MathJax. This document is for version 2.
Installing and Testing MathJax¶
The easiest way to use MathJax is to link directly to the MathJax distributed network service (see Using a CDN). In that case, there is no need to install MathJax yourself, and you can begin using MathJax right away; skip this document on installation and go directly to Configuring 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. 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 command
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, as there was in v1.0, 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 update 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 version that contains all the latest changes to MathJax. Although we try to make sure this version is a stable and usable version of MathJax, it is under active development, and at times it 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), you will want to get one of the tagged releases. Use
cd MathJax
git tag -l
to see all tagged versions, and use
cd MathJax
git checkout <tag_name>
to checkout the indicated version of MathJax, where <tag_name>
is
the name of the tagged version you want to use. When you want to
upgrade to a new release, you will need to repeat this for the latest
release tag.
Each of the main releases also has a branch in which critical updates are applied (we try hard not to patch the stable releases, but sometimes there is a crucial change that needs to be made). If you want to use the patched version of a release, then check out the branch rather than the tag. Use
cd MathJax
git branch
to get a list of the available branches. There are separate branches
for the main releases, but with -latest
appended. These contain
all the patches for that particular release. You can check out one of
the branches just as you would a tagged copy. For example, the branch
for the v2.1
tagged release is v2.1-latest
. To get this
release, use
cd MathJax
git checkout v2.1-latest
and to update it when changes occur, use
cd MathJax
git pull origin v2.1-latest
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 command
svn checkout http://github.com/mathjax/MathJax/trunk MathJax
to obtain and set up a copy of MathJax. (Note that there is no longer
a fonts.zip
file as of v1.1, 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 update 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 version that contains all the latest changes to MathJax. Although we try to make sure this version is a stable and usable version of MathJax, it is under active development, and at times it may be less stable than the “release” version. If you prefer to use one of the tagged releases instead, then use
svn checkout https://github.com/mathjax/MathJax/branches/[name] MathJax
where [name]
is replaced by the name of the branch you want to
check out; e.g., 2.1-latest
. The branch names can be found on the
GitHub MathJax page under the
branches tab.
Obtaining MathJax via an archive¶
Release versions of MathJax are available in archive files from the MathJax download page or the MathJax GitHub page (via the “zip” button, or the “downloads” tab), where you can download the archive that you need.
You should download the v2.1 archive (which will get you a file with a
name like mathjax-MathJax-v2.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, you can also select
the Download .tar.gz
or Download .zip
buttons to get a copy of
the current development version of MathJax that contains all the
latest changes and bug-fixes.
If a packaged release receives any important updates, then those
updates will be part of the branch for that version. The link to
the .zip
file in the download list will be the original release
version, not the patched version. To obtain the patched version, use
the Branches drop down menu (at the far left of the menus within the
page) to select the release branch that you want (for example
v2.1-latest
), and then use the “zip” button just above it to get
the latest patched version of that release.
Obtaining MathJax via Bower¶
Starting with version 2.3, it is possible to use Bower to install MathJax. Assuming Bower is installed on your system, just execute the following command:
bower install MathJax
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
examples.html # Page with links to all sample pages
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, 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.
Firefox 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 directory 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.
One solution to this problem is to install the MathJax fonts locally, so
that Firefox will not have to use web-based fonts in the first place. To
do that, either install the STIX fonts, or copy
the fonts from MathJax/fonts/HTML-CSS/TeX/otf
into your systems fonts
directory and restart your browser (see the MathJax fonts help page for details).
IE9 and remote fonts¶
IE9’s same-origin policy affects its ability to load web-based fonts, as
described above. This has implications not ony to cross-domain loading of
MathJax, but also to the case where you view a local page (with a
file://
URL) that accesses MathJax from a remote site such as a
CDN service. In this case, IE9 does not honor the
Access-Control-Allow-Origin
setting of the remote server (as it would
if the web page came from an http://
URL), and so it never allows the
font to be accessed.
One solution to this problem is to install the MathJax fonts locally so that MathJax doesn’t have to use web-based fonts in the first place. Your best bet is to install the STIX fonts on your system (see the MathJax fonts help page for details).