Configuring and Loading MathJax
The configuration, loading, and startup processes for MathJax version
3 are different from those of version 2 in a number of ways. Where
version 2 had several different methods for configuring MathJax,
version 3 streamlines the process and has only one, as described
below. In version 2, you always loaded MathJax.js, and added a
config=... parameter to provide a combined configuration file, but
in version 3 you load one of several different files, depending on
your needs (so you can avoid multiple file transfers, and also use
MathJax synchronously, which was not possible in version 2).
If you use one of the combined component files in version 3, like
mml-chtml, you may not need to do any configuration at all.
Configuring MathJax
To configure MathJax, you use a global object named MathJax that
contains configuration data for the various components of MathJax.
For example, to configure the TeX input component to use single dollar
signs as in-line math delimiters (in addition to the usual \(...\)
delimiters) and the SVG output component to use a global font cache
for all expressions on the page, you would use
MathJax = {
tex: {
inlineMath: [['$', '$'], ['\\(', '\\)']]
},
svg: {
fontCache: 'global'
}
};
The sections below describe the different places you could put such a configuration. For information on the options that you can set for each of the components, see the Configuring MathJax pages.
Configuration Using an In-Line Script
The easiest way to configure MathJax is to place the MathJax
object in a <script> tag just before the script that loads MathJax
itself. For example:
<script>
MathJax = {
tex: {
inlineMath: [['$', '$'], ['\\(', '\\)']]
},
svg: {
fontCache: 'global'
}
};
</script>
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
</script>
This will configure the TeX input component to use single dollar
signs as in-line math delimiters, and the SVG output component to use
a global font cache (rather than a separate cache for each expression
on the page), and then loads the latest version of the tex-svg
component file from the jsdelivr CDN. This will typeset any TeX
mathematics on the page, producing SVG versions of the expressions.
Using a Local File for Configuration
If you are using the same MathJax configuration over multiple pages,
you may find it convenient to store your configuration in a separate
JavaScript file that you load into the page. For example, you could
create a file called mathjax-config.js that contains
window.MathJax = {
tex: {
inlineMath: [['$', '$'], ['\\(', '\\)']]
},
svg: {
fontCache: 'global'
}
};
and then use
<script src="mathjax-config.js" defer></script>
<script type="text/javascript" id="MathJax-script" defer
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
</script>
to first load your configuration file, and then load the tex-svg
component from the jsdelivr CDN.
Note that here we use the defer attribute on both scripts so that
they will execute in order, but still not block the rest of the page
while the files are being downloaded to the browser. If the async
attribute were used, there is no guarantee that the configuration
would run first, and so you could get instances where MathJax doesn’t
get properly configured, and they would seem to occur randomly.
Configuring and Loading in One Script
It is possible to have the MathJax configuration file also load
MathJax as well, which would be another way to handle the problem of
synchronizing the two scripts described above. For example, you could
make the file load-mathjax.js containing
window.MathJax = {
tex: {
inlineMath: [['$', '$'], ['\\(', '\\)']]
},
svg: {
fontCache: 'global'
}
};
(function () {
var script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js';
script.async = true;
document.head.appendChild(script);
})();
and then simply link to that file via
<script src="load-mathjax.js" async></script>
This script can be async because it doesn’t have to synchronize
with any other script. This will allow it to run as soon as it loads
(since it is small, there is little cost to that), meaning the script
to load MathJax itself will be inserted as soon as possible, so that
MathJax can begin downloading as early as possible. (If this script
were loaded with defer, it would not run until the page was ready,
so the script to load MathJax would not be inserted until then, and
you would have to wait for MathJax to be downloaded before it could
run.)
Converting Your v2 Configuration to v3
Because the version 3 configuration options are somewhat different
from their version 2 counterparts, we provide an automated
configuration conversion tool
to help you move from version 2 to version 3. Simply paste your
current MathJax.Hub.Config() call into the converter, press
Convert and you should get the equivalent version 3 configuration,
and comments about any options that could not be translated to version
3 (some options are not yet implements, others no longer make sense in
version 3). See the instructions on the linked page for more details.
Loading MathJax
Once you have configured MathJax, you then load the MathJax component
file that you want to use. Most often, this will mean you load a
combined component that loads everything you need to run MathJax with
a particular input and output format. For example, the tex-svg
component would allow you to process TeX input and produce SVG output.
To do so, use a script like the following
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
</script>
to get the latest (3.x.x) version of the tex-svg component in ES5
format (the only one currently available) from the jsdelivr CDN.
This takes advantage of the feature of jsdeliver that allows you
to get the latest version using the mathjax@3 notation. For a
specific version, you would use
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3.0.0/es5/tex-svg.js">
</script>
to always get the 3.0.0 version of the tex-svg component.
Other CDNs have slightly different formats for how to specify the
version number. For example, cdnjs uses the following:
<script type="text/javascript" id="MathJax-script" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.0.0/es5/tex-svg.js">
</script>
Some CDNs don’t provide a means of getting the latest version
automatically. For these, MathJax provides a latest.js file that
will do that for you. For example, cdnjs doesn’t have a mechanism
for getting the latest 3.x.x version automatically. If you want to do
that using cdnjs, then use
<script type="text/javascript" id="MathJax-script" async
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.0.0/es5/latest?tex-svg.js">
</script>
to obtain the latest (3.x.x) version of the tex-svg component.
See The MathJax Components for a list of the various components you can choose and descriptions of their contents. See the list of CDNs for the URLs for a number of CDNs that serve MathJax.
Note that the script that loads the MathJax component file should follow the script that configures MathJax (otherwise MathJax will not know what configuration you need). If you use one of the combined component files in version 3, you may not need to do any configuration at all.
Loading Components Individually
If none of the combined component files suits your needs, you can
specify the individual components you want by setting the load
array in the loader section of your MathJax configuration and
loading the startup component.
For example
<script>
MathJax = {
loader: {
load: ['input/tex-base', 'output/svg', 'ui/menu', '[tex]/require']
},
tex: {
packages: ['base', 'require']
}
};
</script>
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3.0.0/es5/startup.js">
</script>
would cause the base TeX input, the SVG output, the contextual menu
code, and the TeX \require macro extension components to be loaded
(and would tell TeX to use the require extension in addition to the
base TeX macros). In this way, you can load exactly the components
you want. Note, however, that each component will be loaded as a
separate file, so it is better to use a combined component file if
possible.
Loading Additional Components
You can use the load array described in the previous section to
load additional components even if you are using one of the combined
components. For example
<script>
MathJax = {
loader: {
load: ['[tex]/colorv2']
},
tex: {
packages: {'[+]': 'colorv2'},
autoload: {color: []}
}
};
</script>
<script type="text/javascript" id="MathJax-script" async
src="https://cdn.jsdelivr.net/npm/mathjax@3.0.0/es5/tex-chtml.js">
</script>
would load the version-2-compatible \color macro, inform TeX to
add that to the packages that it already has loaded, and not autoload
the default version 3 color (the LaTeX-compatible one). This is
done on top of the tex-chtml combined configuration file, so the
TeX input and CommonHTML output formats are already included (as are
the contextual menu, and several TeX packages; see
The MathJax Components for details).
Performing Actions During Startup
MathJax allows you several ways to hook into the MathJax startup
process so that you can do additional configuration, perform actions
after the initial typesetting, and so on. Because MathJax version 3
uses promises for its synchronization, they are what MathJax
provides in order for you to hook into the startup process. There are
two main hooks that you can set in the startup block of your
configuration: the ready() function and the
pageReady() function.
The ready() function is what MathJax calls when all the
components of MathJax have been loaded. It builds the internal
structures needed by MathJax, creates functions in the MathJax
object to make typesetting and format conversion easy for you,
performs the initial typesetting call, and sets up a promise for when
that is complete. You can override the ready() function with
one of your own to override the startup process completely, or to
perform actions before or after the usual initialization. For
example, you could do additional setup before MathJax created the
objects it needs, or you could hook into the typesetting promise to
synchronize other actions with the completion of the initial
typesetting. Examples of these are given below.
The pageReady() function is performed when MathJax is ready
(all its components are loaded, and the internal objects have been
created), and the page itself is ready (i.e., it is OK to typeset the
page). The default is for pageReady() to perform the initial
typesetting of the page, but you can override that to perform other
actions instead, such as delaying the initial typesetting while other
content is loaded dynamically, for example. The ready()
function sets up the call to pageReady() as part of its
default action.
The return value of pageReady() is a promise that is resolved
when the initial typesetting is finished (it is the return value of
the initial MathJax.typesetPromise() call). If you override
the pageReady() method, your function should return a promise
as well. If your function calls
MathJax.startup.defaultPageReady(), then you should return the
promise that it returns (or a promise obtained from its then()
or catch() methods). The MathJax.startup.promise will
resolve when the promise you return is resolved; if you don’t return a
promise, MathJax.startup.promise will resolve immediately,
which may mean that it resolves too early.
Using these two functions separately or in combination gives you full control over the actions that MathJax takes when it starts up, and allows you to customize MathJax’s startup process to suit your needs. Several examples are given below for common situations.
Performing Actions During Initialization
If you want to perform actions after MathJax has loaded all the needed
components, you can set the ready() function to a function that does
the needed actions, and then calls
MathJax.startup.defaultReady() to perform the usual
startup process.
Actions coming before the MathJax.startup.defaultReady()
call are run before any initialization has been done. In particular,
this is before any input or output jax are created, so this is where
customization of the MathJax object definitions could be performed.
For example, you could modify the configuration blocks at this point,
or you could create subclasses of the MathJax objects that override
some of their methods to produce custom behavior, and then register
those subclasses with MathJax so they will be used in place of the
originals.
Actions coming after the MathJax.startup.defaultReady()
call are run after initialization is complete. In particular, all the
internal objects used by MathJax (e.g., the input and output jax, the
math document, the DOM adaptor, etc) will have been created, and the
typesetting and conversion methods will have been created in the
MathJax object. Also the MathJax.startup.promise value
will hold a promise that is resolved when the initial typesetting is
complete, but note that the typesetting has not yet been performed at
this point.
window.MathJax = {
startup: {
ready: () => {
console.log('MathJax is loaded, but not yet initialized');
MathJax.startup.defaultReady();
console.log('MathJax is initialized, and the initial typeset is queued');
}
}
};
The next section shows how to use the MathJax.startup.promise
to synchronize with the initial typesetting action.
Performing Actions After Typesetting
Often, you may need to wait for MathJax to finish typesetting the page
before you perform some action. To accomplish this, you can override
the ready() function, having it perform the
MathJax.startup.defaultReady() action, and then use the
MathJax.startup.promise to queue your actions; these will be
performed after the initial typesetting is complete.
window.MathJax = {
startup: {
ready: () => {
MathJax.startup.defaultReady();
MathJax.startup.promise.then(() => {
console.log('MathJax initial typesetting complete');
});
}
}
};
As an alternative, you can override the pageReady() function,
and use the promise returned from the
MathJax.startup.defaultPageReady() function:
window.MathJax = {
startup: {
pageReady: () => {
return MathJax.startup.defaultPageReady().then(() => {
console.log('MathJax initial typesetting complete');
});
}
}
};
Be sure that you return the promise that you obtain from
then() method, otherwise MathJax.startup.promise will
resolve before the initial typesetting (and your code) has been
performed.
Configuring MathJax After it is Loaded
The global variable MathJax is used to store the configuration for
MathJax. Once MathJax is loaded, however, MathJax changes the
MathJax variable to contain the various methods needed to control
MathJax. The initial configuration that you provided is moved to the
MathJax.config property so that its contents doesn’t conflict
with the new values provides in MathJax. This occurs when the
MathJax component you have requested is loaded (and before the
ready() function is called).
Once MathJax has created the objects that it needs (like the input and
output jax), changes to the configuration may not have any effect, as
the configuration values were used during the creation of the objects,
and that is already complete. Most objects make a copy of their
configuration from your original MathJax object, so changing the
values in MathJax.config after the objects are created will
not change their configurations. (You can change
MathJax.config values for objects that haven’t been created
yet, but not for ones that have.)
For some objects, like input and output jax, document handlers, and
math documents, the local copies of the configuration settings are
stored in the options property of the object, and you may be
able to set the value there. For example,
MathJax.startup.output.options.scale is the scaling value for
the output, and you can set that at any time to affect any subsequent
typeset calls.
Note that some options are moved to sub-objects when the main object
is created. For example, with the TeX input jax, the inlineMath
and similar options are used to create a FindTeX object that is
stored at MathJax.startup.input[0].findTeX; but in this case, the
FindTeX object uses the configuration once when it is created, so
changing MathJax.startup.input[0].findTeX.options will not affect
it. (There is a getPatterns() method if the FindTeX
object that could be used to refresh the object if the options are
changed, however.)
If you need to change the configuration for an object whose options
can’t be changed once it is created, then you will need to create a
new version of that object after you change the configuration. For
example, if you change MathJax.config.tex.inlineMath after
MathJax has started up, that will not affect the TeX input jax, as
described above. In this case, you can call
MathJax.startup.getComponents() to ask MathJax to recreate all
the internal objects (like MathJax.startup.input). This will
cause them to be created using the new configuration options. Note,
however, that MathJax will no longer know about any mathematics that
has already been typeset, as that data was stored in the objects that
have been discarded when the new ones are created.