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 git to 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 the 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 node_modules/mathjax-full 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 compiled javascript files from the typescript source in node_modules/mathjax-full/js.

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 mathjax/es5 directory.

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 the following:

cd mathjax
npm install
npm run compile
npm run make-components
cd ..

This will compile the typescript source files from the mathjax/ts directory into javascript files in the mathjax/js directory, and then will build the component files from mathjax/components/src into the mathjax/es5 directory.

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 mathjax/ts directory is typescript source code for MathJax, and this is compiled into the javascript files found in the mathjax/js directory. But even these are not the files you want on your server. These javascript files are further processed into the MathJax components stored in the mathjax/es5 files using the data in the mathjax/components/src directory.

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 directory called mathjax, for example.

Linking to you Your Copy of MathJax

You can include MathJax in your web page by putting

<script src="path-to-MathJax/tex-chtml.js" id="MathJax-script" async></script>

in your document’s <head> block. Here, tex-chtml.js is the combined component that you are loading, and this is just an example; you will need to pick the one you want to use. See the section on Configuring and Loading MathJax for more details.

The path-to-MathJax should be replaced by the URL for the main MathJax directory, so if you have put the mathjax/es5 directory at the top level of you server’s web site and named it mathjax, you could use

<script src="/mathjax/tex-chtml.js" id="MathJax-script" async></script>

to load MathJax in your page. For example, your page could look like

<html>
    <head>
        ...
        <script src="/mathjax/tex-chtml.js" id="MathJax-script" async></script>
    </head>
    <body>
        ...
    </body>
</html>

Fonts on Shared Servers

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 important caveat — The same-origin security policy for cross-domain scripting.

Some browsers’ (e.g., 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’s CommonHTML output modes use this directive to load web-based math fonts into a page when the user doesn’t have them installed locally on their own computer. These browsers’ security policies, however, only allow 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, they won’t be able to access those web fonts. In this case, MathJax’s CommonHTML output mode will not show 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 software. In the remote server’s MathJax folder, create a file called .htaccess that contains the following lines:

<FilesMatch "\.(ttf|otf|eot|woff)$">
<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 those with graphical 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 (and the other browsers with similar same-origin policies that apply to fonts) 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.

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