Attention
Version 3 is now the current version of MathJax. This document is for version 1.
Loading and Configuring MathJax¶
You load MathJax into a web page by including its main JavaScript file
into the page. That is done via a <script>
tag that links to the
MathJax.js
file. Place the following line in the <head>
section of your document:
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
where path-to-MathJax
is replaced by the URL of the MathJax
directory on your server, or (if you are using MathJax locally rather
than through a server) the location of that directory on your hard
disk. For example, if the MathJax directory is at the top level of
your web server’s directory hierarchy, you might use
<script type="text/javascript" src="/MathJax/MathJax.js"></script>
to load MathJax.
Although it is possible to load MathJax from a site other than your
own web server, there are issues involved in doing so that you need to
take into consideration. See the Notes About Shared Servers for more details. Please do not link to
the copy of MathJax at www.mathjax.org
, as we do not have the
resources to act as a web service for all the sites on the web that
would like to display mathematics. If you are able to run MathJax
from your own server, please do so (this will probably give you better
response time in any case).
It is best to load MathJax in the document’s <head>
block, but it
is also possible to load MathJax into the <body>
section, if
needed. If you do this, load it as early as possible, as
MathJax will begin to load its components as soon as it is included in
the page, and that will help speed up the processing of the
mathematics on your page. MathJax does expect there to be a
<head>
section to the document, however, so be sure there is one
if you are loading MathJax in the <body>
.
It is also possible to load MathJax dynamically after the page has been prepared, for example, via a GreaseMonkey script, or using a specially prepared bookmarklet. This is an advanced topic, however; see Loading MathJax Dynamically for more details.
Configuring MathJax¶
There are several ways to configure MathJax, but the easiest is to use
the config/MathJax.js
file that comes with MathJax. See the
comments in that file, or the configuration details section, for explanations of the meanings of the various
configuration options. You can edit the config/MathJax.js
file to
change any of the settings that you want to customize. When you
include MathJax in your page via
<script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>
it will load config/MathJax.js
automatically as one of its
first actions.
Alternatively, you can configure MathJax efficiently by calling
MathJax.Hub.Config()
when you include MathJax in your page, as
follows:
<script type="text/javascript" src="path-to-MathJax/MathJax.js">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX", "output/HTML-CSS"],
tex2jax: {
inlineMath: [ ['$','$'], ["\\(","\\)"] ],
displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
},
"HTML-CSS": { availableFonts: ["TeX"] }
});
</script>
This example includes the tex2jax
preprocessor and configures it
to use both the standard TeX and LaTeX math delimiters. It uses the
TeX input processor and the HTML-CSS output processor, and forces the
HTML-CSS processor to use the TeX fonts rather that other locally
installed fonts (e.g., STIX fonts). See the
configuration options section (or the comments
in the config/MathJax.js
file) for more information about the
configuration options that you can include in the
MathJax.Hub.Config()
call. Note that if you configure MathJax
using this in-line approach, the config/MathJax.js
file is not
loaded.
Finally, if you would like to use several different configuration
files (like config/MathJax.js
, but with different settings in each
one), you can copy config/MathJax.js
to config/MathJax-2.js
,
or some other convenient name, and use
<script type="text/javascript" src="path-to-MathJax/MathJax.js">
MathJax.Hub.Config({ config: "MathJax-2.js" });
</script>
to load the alternative configuration file config/MathJax-2.js
from the MathJax config
directory. In this way, you can have as
many distinct configuration files as you need.
Common Configurations¶
The following examples show configurations that are useful for some
common situations. This is certainly not an exhaustive list, and
there are variations possible for any of them. Again, the comments in
the config/MathJax.js
file can help you decide what settings to
include, even if you are using the in-line configuration method.
The TeX setup¶
This example calls the tex2jax
preprocessor to identify
mathematics in the page by looking for TeX and LaTeX math delimiters.
It uses $...$
and \(...\)
for in-line mathematics, while
$$...$$
and \[...\]
mark displayed equations. Because dollar
signs are used to mark mathematics, if you want to produce an actual
dollar sign in your document, you must “escape” it using a slash:
\$
. This configuration also loads the AMSmath
and
AMSsymbols
extensions so that the macros and environments they
provide are defined for use on the page.
MathJax.Hub.Config({
extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
jax: ["input/TeX","output/HTML-CSS"],
tex2jax: {
inlineMath: [['$','$'],["\\(","\\)"]],
processEscapes: true,
},
});
Other extensions that you may consider adding to the extensions
array include: TeX/noErrors.js
, which shows the original TeX code
if an error occurs while processing the mathematics (rather than an
error message), TeX/noUndefined.js
, which shows undefined
macros names in red (rather than producing an error), and
TeX/autobold.js
, which automatically inserts \boldsymbol{...}
around your mathematics when it appears in a section of your page that
is in bold. Most of the other TeX extensions are loaded automatically
when needed, and so do not need to be included explicitly in your
extensions array.
See the tex2jax configuration section for
other configuration options for the tex2jax
preprocessor, and the
TeX input jax configuration section for options
that control the TeX input processor.
The MathML setup¶
This example calls the mml2jax
preprocessor to identify
mathematics in the page that is in MathML format, which uses
<math display="block">
to indicate displayed equations, and
<math display="inline">
or simply <math>
to mark in-line
formulas.
MathJax.Hub.Config({
extensions: ["mml2jax.js"],
jax: ["input/MathML","output/HTML-CSS"]
});
Note that this will work in HTML files, not just XHTML files (MathJax
works with both), and that the web page need not be served with any
special MIME-type. Also note that, unless you are using XHTML rather
than HTML, you should not include a namespace prefix for your
<math>
tags; for example, you should not use <m:math>
except
in a file where you have tied the m
namespace to the MathML DTD.
See the mml2jax configuration section for
other configuration options for the mml2jax
preprocessor, and the
MathML input jax configuration section for
options that control the MathML input processor.
Both TeX and MathML¶
This example provides for both TeX and MathML input in the same file.
It calls on both the tex2jax
and mml2jax
preprocessors and the
TeX and MathML input jax to do the job.
MathJax.Hub.Config({
extensions: ["tex2jax.js", "mml2jax.js"],
jax: ["input/TeX", "input/MathML", "output/HTML-CSS"],
});
Notice that no tex2jax
configuration section is included, so it
uses its default options (no single dollar signs for in-line math).
The majority of the code for the TeX and MathML input processors are not loaded until they are actually needed by the mathematics on the page, so if this configuration is used on a page that include only MathML, the TeX input processor will not be loaded. Thus it is reasonably efficient to specify both input processors even if only one (or neither one) is used.
TeX input with MathML output¶
This example configures MathJax to use the tex2jax
preprocessor
and TeX input processor, but the choice of output format is determined
by MathJax depending on the capabilities of the user’s browser. The
is performed by the MMLorHTML.js
configuration file that is loaded
in the config` array.
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
extensions: ["tex2jax.js"],
jax: ["input/TeX"]
});
With this setup, Firefox or Internet Explorer with the MathPlayer plugin installed will use the NativeMML output processor, while all other browsers will use the HTML-CSS output processor. Since native MathML support is faster than MathJax’s HTML-CSS processor, this will mean that the web pages will display faster for Firefox and IE than they would otherwise. This speed comes at the cost, however, as you are now relying on the native MathML support to render the mathematics, and that is outside of MathJax’s control. There may be spacing or other display differences (compared to MathJax’s HTML-CSS output) when the NativeMML output processor is used.
See MathJax Output Formats for more
information on the NativeMML and HTML-CSS output processors. See the
MMLorHTML configuration section for
details on the options that control the MMLorHTML
configuration.
MathML input and output in all browsers¶
This example configures MathJax to look for MathML within your page, and to display it using the browser’s native MathML support, if possible, or its HTML-CSS output if not.
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
extensions: ["mml2jax.js"],
jax: ["input/MathML"]
});
Using this configuration, MathJax finally makes MathML available in all modern browsers.
See the MMLorHTML configuration section
for details on the options that control the MMLorHTML
configuration file, the MathML configuration
section for the options that control the MathML output processor, and
the mml2jax configuration section for the
options that control the mml2jax
preprocessor.
Configuration Objects¶
The various components of MathJax, including its input and output
processors, its preprocessors, its extensions, and the MathJax core,
all can be configured through the config/MathJax.js
file, or via a
MathJax.Hub.Config()
call (indeed, if you look closely, you
will see that config/MathJax.js
is itself one big call to
MathJax.Hub.Config()
). Anything that is in
config/MathJax.js
can be included in-line to configure MathJax.
The structure that you pass to MathJax.Hub.Config()
is a
JavaScript object that includes name-value pairs giving the names of
parameters and their values, with pairs separated by commas. Be
careful not to include a comma after the last value, however, as some
browsers (namely Internet Explorer) will fail to process the
configuration if you do.
The MathJax components, like the TeX input processor, have their own sections in the configuration object, labeled by the component name, and using an configuration object as its value. The object is itself a configuration object made up of name-value pairs that give the configuration options for the component.
For example,
MathJax.Hub.Config({
showProcessingMessages: false,
jax: ["input/TeX", "output/HTML-CSS"],
TeX: {
TagSide: "left",
Macros: {
RR: '{\\bf R}',
bold: ['{\\bf #1}',1]
}
}
});
is a configuration that includes two settings for the MathJax Hub (one
for showProcessingMessages and one of the jax array), and a
configuration object for the TeX input processor. The latter includes
a setting for the TeX input processor’s TagSide option (to set tags
on the left rather than the right) and a setting for Macros, which
defines new TeX macros (in this case, two macros, one called \RR
that produces a bold “R”, and one called \bold
that puts is
argument in bold face).
The config/MathJax.js
file is another example that shows nearly
all the configuration options for all of MathJax’s components.
Configuration Options by Component¶
The individual options are explained in the following sections, which are categorized by the component they affect.