Hosting Your Own Copy of MathJax — MathJax 4.0 documentation (original) (raw)
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
This will install MathJax in node_modules/mathjax subdirectory of your current directory.
If you need access to the source code, as well, then instead use
npm install @mathjax/src@4
which installs MathJax in the node_modules/@mathjax/srcsubdirectory, with the webpacked component files in thenode_modules/@mathjax/src/bundle directory. The Typescript source code files are in node_modules/@mathjax/src/ts, and pre-compiled versions of this are available in two formats: as ES modules in thenode_modules/@mathjax/src/mjs directory, and as CommonJS modules in node_modules/@mathjax/src/cjs. See the Getting Started with Nodesection for more details about how to use the MathJax source code in your own javascript projects.
Note
Version 4 of MathJax has moved to using scoped npm packages. The version 3 package name mathjax-full is now @mathjax/src.
Getting MathJax via git
To obtain a copy of MathJax from the GitHub source repository, use the command
git clone https://github.com/mathjax/MathJax.git mathjax
This will install a copy of MathJax in the mathjax directory.
If you need access to the source code as well as the webpacked components, then instead use
git clone https://github.com/mathjax/MathJax-src.git mathjax
which will install the source code for MathJax in the mathjaxsub-directory of your current directory. In this case, 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 pnpm install pnpm -s build-all cd ..
This will compile the typescript source files from the@mathjax/src/ts directory into javascript files in the@mathjax/src/mjs and @mathjax/src/cjs directories, and then will build the component files from @mathjax/src/components/mjsinto the @mathjax/src/bundle directory.
Note
MathJax version 4 has switched to using pnpm rather thannpm, so you will need to install that if you don’t have it installed already, as the build scripts rely on it. To do so, use
If you don’t want to build both cjs and mjs versions, then you can use
to build just the mjs versions, or
to build just the cjs versions.
Note
The directory structure and build process for MathJax version 4 has been significantly updated. See the Release notes for 4.0.0-beta.2for a discussion of the new dual mjs/cjs structure.
Making 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 source distribution are not needed on the server. For example, the@mathjax/src/ts directory is typescript source code for MathJax, and this is compiled into the javascript files found in the@mathjax/src/mjs or @mathjax/src/cjs 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/src/bundle directory using the data in the@mathjax/src/components/mjs directory.
It is the contents of the @mathjax/src/bundle directory that you want to make available on your server, as these are the files that are served from the CDNs that provide MathJax. If you installed the plainmathjax@4 npm package, that is the set of files you will have obtained, as the mathjax package is just these bundled files.
You should move those files to a convenient location on your server. This might be a top-level directory called mathjax, for example, or something like assets/mathjax in your application directory.
Linking to Your Copy of MathJax
You can include MathJax in your web page by putting
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 onLoading 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 mathjaxdirectory at the top level of you server’s web site and named itmathjax, you could use
to load MathJax in your page. For example, your page could look like
... ...Obtaining the Needed Fonts
In version 3, there was only one font (mathjax-tex) and it was bundled with MathJax itself, so there when you installed MathJax, you also git that font. That is no longer the case with version 4, since there is a choice of fonts, and they are made available in separate packages. Installing MathJax via npm or pnpm will get you the default mathjax-newcm font, but if you plan to use a different font and have that served from your server, you will need to load its font package as well. E.g.,
pnpm install @mathjax/mathjax-stix2-font@4
to install the mathjax-stix2 font.
You will need to move the node_modules/@mathjax/mathjax-stix2-fontdirectory to a suitable location on your server, as you have the MathJax files themselves.
In order to use the font you have loaded, you will need to configure MathJax to tell it the font you need, and where the font files are located on your server. For example:
MathJax = { output: { font: 'mathjax-stix2', fontPath: '', } };
where <path-to-mathjax-stix2-font> is the URL for where you have places the @mathjax/mathjax-stix2-font folder.
In this case, your page might look like
... ...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 atwww.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 other browsers, and it affects how fonts are loaded with the @font-face CSS directive. MathJax’s CommonHTML output mode uses this directive to load web-based math fonts into the web page when needed. These browsers’ security policies, however, may 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 ".(woff|woff2)$"> Header set Access-Control-Allow-Origin "*"
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 "https://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.
Note that the CDNs that host MathJax already have these settings in place, so you can load fonts from them into your own pages without having to worry about these issues.
For web servers other than Apache, you will need to consult the server’s documentation to determine how to specify the needed header line for fonts on your system.
Using MathJax Locally
You can use MathJax locally without a connection to the internet by following the basic outline above, and using file:// URLs to access your local files. Note, however, that some browsers have additional cross-origin restrictions for file:// URLs, and that may limit where you can place the MathJax files and font files.
In that case, you may need to run a local webserver for MathJax and its files. For example, if you have placed the mathjax andmathjax-newcm-font files in a directory called assets, then if do
cd assets node serve --cors
and configure your page like
... ...then you should be able to load this file using a file:// URL and have MathJax served from the local server without the need for any access to the internet.