Hosting Your Own Copy of MathJax¶
We recommend using a CDN service if you can, but you can also install MathJax on your own server, or locally on your own hard disk. You may need to do this if you are creating a custom build of MathJax, for example, or if you wish to use MathJax off-line.
Acquiring the MathJax Code¶
In order to host your own version of MathJax, you must first obtain a
copy of the MathJax code. That can be done in several ways, the
easiest being to use
npm (the node package manager), or
get MathJax from its GitHub development repository.
Getting MathJax via npm¶
To include MathJax in your project, use the command
npm install mathjax@3
This will install MathJax in
node_modules/mathjax subdirectory of
your current directory. It will include the pre-built components in
node_modules/mathjax/es5 directory. (Note that it is
important to use
mathjax@3, as we are still making v2 releases,
and so the latest mathjax npm package may not be the v3 one. The
latest version on
npmjs.com appears to be chronological rather
than by version number.)
If you need access to the source code, as well. Then use
npm install mathjax-full@3
which installs MathJax in the
subdirectory, the source files for the components in
node_modules/mathjax-full/components/src, the typescript source
files for MathJax in
node_modules/mathjax-full/ts, and the
Getting MathJax via git¶
To obtain a copy of MathJax from the GitHub component repository, use the command
git clone https://github.com/mathjax/MathJax.git mathjax
This will install a copy of MathJax in the
If you need access to the source code as well, then use
git clone https://github.com/mathjax/MathJax-src.git mathjax
which will install the source code for MathJax in the
mathjax sub-directory of your current directory. You will need to
compile the typescript source files and build the component files by
hand, as they are not part of the repository itself. To do this, do
cd mathjax npm install npm run compile npm run make-components cd ..
This will compile the typescript source files from the
mathjax/js directory, and
then will build the component files from
Make the Files Available¶
Once you have acquired the MathJax files by one of the methods
described above, you need to make the proper files available on your
web server. Note that most of the files in the MathJax distribution
are not needed on the server. For example, the
directory is typescript source code for MathJax, and this is compiled
mathjax/js directory. But
even these are not the files you want on your server. These
stored in the
mathjax/es5 files using the data in the
It is the contents of the
mathjax/es5 directory that
you want to make available on your server, as these are the files that
are served from the CDNs that provide MathJax. You should move them
to a convenient location on your server. This might be a top-level
mathjax, for example.
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 used to be that the “same domain” for a page is the directory where that page exists, or any of its subdirectories. This allowed MathJax to be loaded from a subdirectory of the director where the web page was loaded.
This is no longer the case with Firefox starting with version 68 and
going forward (see their documentation).
Now there is no same origin for a
file:// URL (the origin for a
page loaded from a
file:// URL is unique).
This means there are limited options for using MathJax in Firefox with a local copy of MathJax. The easiest option is to use the SVG output renderer rather than the CommonHTML output, as that does not require fonts to be loaded, so avoids the same-origin issue. Alternatively, you could install the MathJax TeX fonts as system fonts so that Firefox doesn’t hav to try to load them as web fonts.
This is an unfortunate restriction for MathJax (though we understand their reasoning), but it is a limitation imposed by Firefox’s security model that MathJax can not circumvent. Currently, this is not a problem for other browsers, though there is no guarantee that it won’t be in the future.