Attention
Version 3 is now the current version of MathJax. This document is for version 1.
Getting Started¶
MathJax allows you to include mathematics in your web pages, either using TeX and LaTeX notation, or as MathML, and you can even use both in the same document.
There are two ways to access MathJax: the easiest way is to use the
copy of MathJax available from our distributed network service at
cdn.mathjax.org, but you can also download and install a copy of
MathJax on your own server, or for use locally on your own hard disk
(with no need for network access). Both of these are described below,
with links to more detailed explanations. This page gives the
quickest and easiest ways to get MathJax up and running on your web
site, but you may want to read the details in order to customize the
setup for your pages.
Using the MathJax Content Delivery Network (CDN)¶
To use MathJax from our server, you need to do two things:
Link MathJax into the web pages that are to include mathematics.
Put mathematics into your web pages so that MathJax can display it.
You accomplish the first step by putting
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
into the <head> block of your document. (It can also go in the
<body> if necessary, but the head is to be preferred.) This will
load the latest version of MathJax from the distributed server, and
configure it to recognize mathematics in both TeX and MathML notation,
and ask it to generate its output using MathML if the browser supports
that, and otherwise use HTML-with-CSS to display the mathematics.
This is the most general configuration, and should suffice for most
people’s needs. Other configurations are available, however, and you
can also provide additional configuration parameters to taylor one of
the configurations to your needs. More details can be found in the
Loading and Configuring MathJax instructions.
The use of cdn.mathjax.org is governed by its terms of service, so be
sure to read that before linking to the MathJax CDN server.
To see how to enter mathematics in your web pages, see Putting mathematics in a web page below.
Installing Your Own Copy of MathJax¶
We recommend using the CDN service if you can, but you can also install MathJax on your own server, or locally on your own hard disk. To do so you will need to do the following things:
Obtain a copy of MathJax and make it available on your server.
Configure MathJax to suit the needs of your site.
Link MathJax into the web pages that are to include mathematics.
Put mathematics into your web pages so that MathJax can display it.
Obtaining and Installing MathJax¶
The easiest way to set up MathJax is to obtain the v1.1 archive from
the MathJax download page (you
should obtain a file named something like
mathjax-MathJax-v1.1-X-XXXXXXXX.zip, where the X’s are
random-looking letters and numbers). This archive includes both the
MathJax code and the MathJax webfonts, so it is the only file you
need. Note that this is different from earlier releases, which had
the fonts separate from the rest of the code.
Unpack the archive and place the resulting MathJax folder onto your
web server at a convenient location where you can include it into your
web pages. For example, making MathJax a top-level directory on
your server would be one natural way to do this. That would let you
refer to the main MathJax file via the URL /MathJax/MathJax.js
from within any page on your server.
Note: While this is the easiest way to set up MathJax initially, there is a better way to do it if you want to be able to keep your copy of MathJax up-to-date. That uses the Git version control system, and is described in the Installing MathJax document. If you prefer using Subversion, you can also use that to get a copy of MathJax (see Installing MathJax via SVN).
Once you have MathJax set up on your server, you can test it using the
files in the MathJax/test directory. Load them in your browser
using its web address rather than opening them locally (i.e., use an
http:// URL rather than a file:// URL). When you view the
index.html file, after a few moments you should see a message
indicating that MathJax appears to be working. If not, check that the
files have been transferred to the server completely and that the
permissions allow the server to access the files and folders that are
part of the MathJax directory. (Be sure to verify the MathJax
folder’s permissions as well.) Check the server log files for any
errors that pertain to the MathJax installation; this may help locate
problems in the permission or locations of files.
Configuring your copy of MathJax¶
When you include MathJax into your web pages as described below, it
will load the file config/TeX-AMS-MML_HTMLorMML.js (i.e., the file
named TeX-AMS-MML_HTMLorMML.js in the config folder of the
main MathJax folder). This file preloads all the most commonly-used
components of MathJax, allowing it to process mathematics that is in
the TeX or LaTeX format, or in MathML notation. It will produce
output in MathML form if the user’s browser supports that, and will use
HTML-with-CSS to render the mathematics otherwise.
There are a number of other prebuilt configuration files that you can
choose from as well, or you could use the config/default.js file and
customize the settings yourself. The combined configuration files are
described more fully in Common Configurations, and the configuration options are described in
Configuration Options.
Note: The configuration process has changed in MathJax v1.1, so if you have existing pages that use MathJax, you may need to modify the tag that loads MathJax so that it conforms with the new configuration process. See Installing and Configuring MathJax for more details.
Linking your copy of MathJax into a web page¶
You can include MathJax in your web page by putting
<script type="text/javascript" src="path-to-MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
in your document’s <head> block. Here, path-to-MathJax should
be replaced by the URL for the main MathJax directory, so if you have
put the MathJax directory at the top level of you server’s web
site, you could use
<script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
to load MathJax in your page. For example, your page could look like
<html>
<head>
...
<script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
</head>
<body>
...
</body>
</html>
If you have installed MathJax on a server that is in a different domain from the one serving the page that loads MathJax, be sure to read the Notes About Shared Servers for more details. In that case, you may wish to consider using the MathJax CDN rather than installing your own copy of MathJax.
Putting mathematics in a web page¶
To put mathematics in your web page, you can use either TeX and LaTeX notation or MathML notation or both within the same page; the MathJax configuration tells MathJax which you want to use, and how you plan to indicate the mathematics when you are using TeX notation. The configuration file used in the examples above tells MathJax to look for both TeX and MathML notation within your pages. These two formats are described in more detail below.
TeX and LaTeX input¶
Mathematics that is written in TeX or LaTeX format is indicated using math delimiters that surround the mathematics, telling MathJax what part of your page represents mathematics and what is normal text. There are two types of equations: ones that occur within a paragraph (in-line mathematics), and larger equations that appear separated from the rest of the text on lines by themselves (displayed mathematics).
The default math delimiters are $$...$$ and \[...\] for
displayed mathematics, and \(...\) for in-line mathematics. Note
in particular that the $...$ in-line delimiters are not used
by default. That is because dollar signs appear too often in
non-mathematical settings, which could cause some text to be treated
as mathematics unexpectedly. For example, with single-dollar
delimiters, “… the cost is $2.50 for the first one, and $2.00 for
each additional one …” would cause the phrase “2.50 for the first
one, and” to be treated as mathematics since it falls between dollar
signs. For this reason, if you want to use single-dollars for in-line
math mode, you must enable that explicitly in your configuration:
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}
});
</script>
<script type="text/javascript" src="path-to-mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
See the config/default.js file, or the tex2jax configuration
options page, for additional configuration
parameters that you can specify for the tex2jax preprocessor,
which is the component of MathJax that identifies TeX notation within
the page. See the TeX and LaTeX page for
more on MathJax’s support for TeX.
Here is a complete sample page containing TeX mathematics (also available
in the test/sample-tex.html file):
<!DOCTYPE html>
<html>
<head>
<title>MathJax TeX Test Page</title>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
</body>
</html>
Since the TeX notation is part of the text of the page, there are some caveats that you must keep in mind when you enter your mathematics. In particular, you need to be careful about the use of less-than signs, since those are what the browser uses to indicate the start of a tag in HTML. Putting a space on both sides of the less-than sign should be sufficient, but see TeX and LaTeX support for details.
There are a number of extensions for the TeX input processor that are
loaded by the TeX-AMS-MML_HTMLorMML configuration. These include:
TeX/AMSmath.js, which defines the AMS math environments and macros,
TeX/AMSsymbols.js, which defines the macros for the symbols in the msam10 and msbm10 fonts,
TeX/noErrors.js, which shows the original TeX code rather than an error message when there is a problem processing the TeX, and
TeX/noUndefined.js, which prevents undefined macros from producing an error message, and instead shows the macro name in red.
Other extensions may be loaded automatically when needed.
MathML input¶
For mathematics written in MathML notation, you mark your
mathematics using standard <math> tags, where <math
display="block"> represents displayed mathematics and <math
display="inline"> or just <math> represents in-line mathematics.
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.
Here is a complete sample page containing MathML mathematics (also
available in the test/sample-mml.html file):
<!DOCTYPE html>
<html>
<head>
<title>MathJax MathML Test Page</title>
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
When <math><mi>a</mi><mo>≠</mo><mn>0</mn></math>,
there are two solutions to <math>
<mi>a</mi><msup><mi>x</mi><mn>2</mn></msup>
<mo>+</mo> <mi>b</mi><mi>x</mi>
<mo>+</mo> <mi>c</mi> <mo>=</mo> <mn>0</mn>
</math> and they are
<math mode="display">
<mi>x</mi> <mo>=</mo>
<mrow>
<mfrac>
<mrow>
<mo>−</mo>
<mi>b</mi>
<mo>±</mo>
<msqrt>
<msup><mi>b</mi><mn>2</mn></msup>
<mo>−</mo>
<mn>4</mn><mi>a</mi><mi>c</mi>
</msqrt>
</mrow>
<mrow> <mn>2</mn><mi>a</mi> </mrow>
</mfrac>
</mrow>
<mtext>.</mtext>
</math>
</body>
</html>
When entering MathML notation in an HTML page (rather than an XHTML page), you should not use self-closing tags, but should use explicit open and close tags for all your math elements. For example, you should use
<mspace width="thinmathspace"></mspace>
rather than <mspace width="5pt" /> in an HTML document. If you use the
self-closing form, some browsers will not build the math tree properly, and
MathJax will receive a damaged math structure, which will not be rendered
as the original notation would have been. Unfortunately, there is nothing
MathJax can do about that, since the browser has incorrectly interpreted
the tags long before MathJax has a chance to work with them.
The component of MathJax that recognizes MathML notation is called the
mml2jax extension, and it has only a few configuration options; see the
config/default.js file or the mml2jax configuration options page for more details. See the MathML page for more on MathJax’s MathML support.
Where to go from here?¶
If you have followed the instructions above, you should now have MathJax installed and configured on your web server, and you should be able to use it to write web pages that include mathematics. At this point, you can start making pages that contain mathematical content!
You could also read more about the details of how to customize MathJax.
If you are trying to use MathJax in blog or wiki software or in some other content-management system, you might want to read about using MathJax in popular platforms.
If you are working on dynamic pages that include mathematics, you might want to read about the MathJax Application Programming Interface (its API), so you know how to include mathematics in your interactive pages.
If you are having trouble getting MathJax to work, you can read more about installing MathJax, or loading and configuring MathJax.
Finally, if you have questions or comments, or want to help support MathJax, you could visit the MathJax community forums or the MathJax bug tracker.