Attention
Version 3 is now the current version of MathJax. This document is for version 2.
MathJax Frequently Asked Questions¶
Which license is MathJax distributed under?¶
MathJax is distributed under the Apache License, Version 2.0.
Will MathJax make my page load slower even if there’s no math?¶
MathJax loads components only when needed so there is a big difference
between what is loaded on a page without mathematics and one that does
include mathematics. On a page with no mathematics, loading MathJax
requires two files: MathJax.js
and a configuration file. If taken from
a CDN, the actual (compressed) data transferred for MathJax.js
will be about 14.4KB. The configuration file can vary greatly in size
depending on what is included; minimal configurations can be as small as
3.7KB, reasonable configurations vary between 25KB and 40KB – bringing
us to a total of 18KB to 55KB, i.e., roughly a small to medium sized
image. To learn more about configuring MathJax, see our
documentation.
Mathematics is not rendering properly in IE. How do I fix that?¶
First, please open the MathJax homepage at www.mathjax.org in IE to see if that loads correctly. If it does, this indicates that there may be something wrong with the webpage you were trying to view initially. If appropriate, upgrade the website to the latest version of MathJax. If the MathJax homepage does not display mathematics properly, there may be an issue with your security settings in Internet Explorer. Please check the following settings:
- “Active Scripting” under the Scripting section should be enabled, as it allows JavaScript to run.
- “Run ActiveX controls and Plugins” should be enabled (or prompted) in the “ActiveX Controls and Plugins” section.
- “Script ActiveX controls marked safe for scripting” needs to be enabled (or prompted) in the same “ActiveX Controls and Plugins” section. Note that it requires a restart of IE if you change this setting.
- “Font Download” has to be enabled (or prompted) in the “Downloads” section. This is required for MathJax to use web-based fonts for optimal viewing experience.
You may need to select Custom Level security to make these changes. If
you have verified that the above settings are correct, tried clearing
your cache and restarting IE, and are still experiencing problems with
displaying mathematics on www.mathjax.org
, we would appreciate it if you
reported the problem to the MathJax User Group so we can look into it.
Please follow the guidelines for reporting
problems described below.
Some of my mathematics is too large or too small. How do I get it right?¶
MathJax renders mathematics dynamically so that formulas and symbols are
nicely integrated into the surrounding text — with matching font size,
margins, and baseline. So, in other words: it should look right. If your
mathematics is too large or too small in comparison to its surroundings,
you may be using the incorrect typesetting style. Following LaTeX
conventions, MathJax supports two typesetting styles: inline and
paragraph (or “display”) equations. For inline equations, MathJax tries
hard to maintain the inter-line spacing. This means things like
fractions and roots are vertically compressed, and smaller fonts are
used. Paragraph equations are shown as a separate paragraph and can be
displayed with more space and slightly larger fonts. The standard
delimiters for inline equations are \(...\)
, while for paragraph
equations they are $$...$$
or \[...\]
, but they can be
customized. For how to configure MathJax to scale all mathematics
relative to the surrounding text, check our documentation for the HTML
output and
the SVG output.
How do I access MathJax from a CDN using a https secure connection?¶
The CDNs serving MathJax can be accessed via https
. We advise you
to always use https
. For more information, see our
documentation.
My mathematics is private. Is it safe to use MathJax?¶
Yes. MathJax is JavaScript code that is run entirely within the browser
of the user, and so your site’s actual content never leaves the browser
while MathJax is rendering. If you are using MathJax from a CDN, it
interacts with a web server to get font data and MathJax code but this is all put
together in the browser of the reader. If you have concerns about
cross-site scripting, you can access the CDN service using the
secure https
protocol to prevent tampering with the code between the
CDN and a browser; or, if you prefer, you can
install MathJax on your own web server. MathJax does not reference
script codes on other websites. The code is, of course, open source
which means that you can review it and inspect its
integrity.
Does MathJax support Presentation and/or Content MathML?¶
MathML comes in two types: Presentation MathML, which describes what an
equation looks like, and Content MathML, which describes what an
equation means. By default, MathJax works with Presentation MathML
and offers an extension for Content MathML, see the
documentation on MathML
support.
You can also convert your Content MathML expressions to
Presentation MathML using xslt
, see for example David Carlisle’s web-xslt
collection. A more
detailed explanation of the difference between Content and Presentation
MathML can be found in the module “Presentation MathML Versus Content
MathML” at cnx.org
.
How do I create mathematical expressions for display with MathJax?¶
MathJax is a method to display mathematics. It is not an authoring environment, and so you will need another program to create mathematical expressions. The most common languages for mathematics on the computer are (La)TeX and MathML, and there are many authoring tools for these languages.
LaTeX code is essentially plain text, and so you do not need a special program to write it (although complete LaTeX authoring environments do exist). If you are not familiar with LaTeX, you will need some determination to learn and master the language due to its specialized nature and rich vocabulary of symbols. There are various good tutorials on the net, but there is no one-size-fits-all best one. A good starting point is the TeX User Group, or have a look at the LaTeX Wiki book.
MathML is an XML-based web format for mathematical expressions. MathML3, the latest version, has been an official W3C recommendation since October 2010. MathML is widely supported by Computer Algebra Systems and can be created with a choice of authoring tools, including Microsoft Office with the MathType equation editor. A list of software the supports MathML may be found in The W3C MathML software list.
I ran into a problem with MathJax. How do I report it?¶
If you come across a problem with MathJax, please report it so that the development team and other users are aware and can look into it. It is important that you report your problem following the steps outlined here because this will help us to rapidly establish the nature of the problem and work towards a solution effectively. If you are experiencing a problem, please follow these steps:
- Have you cleared your browser cache, quit your browser, and restarted it? If not, please do so first and check if the problem persists. These instructions tell you how to clear your cache on the major browsers.
- Have you turned off other extensions and plugins in your browser, and restarted it?
- Have a look at the math rendering examples on www.mathjax.org to see if you experience problems there as well. This might help you to determine the nature of your problem.
- If possible, check whether the problem has been solved in the latest MathJax release, cf. the installation instructions.
- Search through the MathJax User Group and the MathJax issue tracker to see if anyone else has come across the problem before.
- Found a real and new problem? Please report it to the MathJax issue
tracker including the
following information:
- A detailed description of the problem. What exactly is not working as you expected? What do you see?
- The MathJax version you are working with, your operating system, and full browser information including all version information.
- If at all possible, a pointer to a webpage that is publicly available and exhibits the problem. This makes sure that we can reproduce the problem and test possible solutions.
The MathJax font folder is too big. Is there any way to compress it?¶
No, there is no simple way to make the fonts folder smaller. We have tried to make the fonts folder as small as possible, but in order to render math on some older browsers, you need image fonts, which take up most of the space. This is because you need an individual image file for each character in each font in each of a dozen different sizes, and each file must be at least the block size of the hard drive it is stored on (usually 4 kb). With nearly 30,000 separate image files, this adds up to a lot. Some users have suggested using a “sprite font” that has all the characters in a single image, from which MathJax could show only the particular character it wants. This is a nice idea, but it does not work well in practice (at least not if you want it to work reliably across multiple browsers). Since the image fonts are intended as a last resort for browsers whose functionality is not well behaved, relying on fancy CSS tricks to clip large images is not going to be a viable strategy. This approach also has performance and printing problems.
The single-glyph-per-file approach has proven to be the only truly
reliable and maintainable approach that we have found. If you want to
disable image fonts altogether, however, in order to save space, you
can. Note: If you disable image fonts, MathJax might not work on
some users’ browsers. With image fonts disabled, users must either have
the MathJax or STIX fonts on their computer or their browser must
support the @font-face
CSS directive. This means IE6+, Chrome, Safari
3.1+, Firefox 3.5+, and Opera 10+, or other browsers based on their
rendering engines. On earlier browsers (without local fonts) or if
webfonts are blocked, MathJax will not be able to render math reliably (though
it will try its best).
To disable image fonts, use
MathJax.Hub.Config({
"HTML-CSS": {
imageFont: null
}
});
as part of your configuration. (See Configuring MathJax <using-in-line-configuration-options> for more details.)
This will tell MathJax that there are no image fonts available and it
will no longer look for them. You can then delete the
[MathJax]/fonts/HTML-CSS/TeX/png/
directory, which takes up the most
space in the fonts folder. Do not delete the other font directories,
as they are needed to handle @font-face for other browsers. For more
advanced reductions, see our MathJax-grunt-cleaner tool.
Why is MathJax using image fonts instead of web fonts?¶
Web fonts are supported by all popular browsers (IE, Firefox, Chrome, Safari, Opera…) and they are scalable, which means much better display and print quality. Clearly, you want to make sure this is working on your install of MathJax. Here are several reasons web fonts might not be working for you:
- Configuration not specifying web fonts: Web fonts are enabled by
default, but double check your MathJax configuration if you have done
any tweaking. Don’t forget that you might have
custom config in the
<script>
tag where you include MathJax in your template. In your configuration, make sure you setwebFont: "TeX"
. This will make MathJax try to load the TeX web font from the fonts folder. - MathJax times out waiting for fonts to arrive: You can tell by
entering
MathJax.Message.Log()
into your browser’s developer’s console (and pressing RETURN), and checking if there is a message about switching to image fonts. This can happen in particular if your network connection is relatively slow. In v2.0, the timeout was lengthened somewhat, and MathJax will switch only if the first font fails to arrive (if it succeeds in obtaining one font, it assumes it can get the rest). - Missing font files: In order for MathJax to send web font files
to the client, the font files need to be in the right place on the
server. Different browsers accept different font files, so there are
different folders for the various font files. Make sure that the
eot
,otf
,woff
, andsvg
folders are in the[MathJax]/fonts/HTML-CSS/TeX/
directory. - Firefox local @font-face feature: Firefox’s interpretation of the
same-origin security policy is more strict than most other browsers,
and it applies to fonts loaded with the
@font-face
CSS directive. Firefox will not load such fonts if they are stored outside the directory containing the page that requests the fonts. That means that if your MathJax directory is in a higher-level directory, Firefox wont be able to read the font files from it when you load the file locally (this does not affect MathJax when used from an actual web server). In order to fix this, you can install the MathJax TeX fonts in the system fonts folder on the computer where you are viewing the files locally, or you can put the MathJax folder in the same directory as (or a subdirectory of) the web page you are viewing. A symbolic link to a MathJax installation at another location should be sufficient, but that will depend on the operating system. Neither of these is an ideal solution. - Browser font preferences: Most browsers have a setting to disable the use of webfonts, which forces MathJax to fallback to image fonts. You can change these settings in the browser preferences, but how you do so depends on the browser.
- IIS configuration: Microsoft’s IIS web server by default doesn’t
recognize files with unknown extensions such as
.otf
and.svg
, and doesn’t know how to serve them. This results in a HTTP Error 404.3 - Not Found error message, causing MathJax to fall back to image fonts. If you are using IIS, you can enable the delivery of these file types by setting a custom mimetype configuration. See, for example, Mads Kristensen’s blog and Paul Irish’s blog for instructions on how to do this (as well as more background information). - Cross-domain access on shared installations: When you are using a shared installation, where MathJax is installed on a different server than the webpages using it, Firefox’s and IE’s same-origin security policy for cross-domain scripting may prevent MathJax from loading web fonts. This specific problem, and a possible resolution, are described in more detail in these installation instructions.
- Local pages in IE: IE’s same-origin security policy, which also
affects shared installations (see above), has implications for the
viewing of local files (with a
file://[filename]
URL). See these installation instructions for details and a suggested resolution.
Why doesn’t the TeX macro \something
work?¶
It really depends on what \something
is. We have a full list of the
supported TeX
commands. If the
command you want to use is not in this list, you may be able to define a
TeX macro for it, or if you want to get really advanced, you can define
custom JavaScript that implements it (see the files in the extensions
folder for some examples). Keep in mind that MathJax is meant for
typesetting math on the web. It only replicates the math
functionality of LaTeX and not the text formatting capabilities. Any
text formatting on the web should be done in HTML and CSS, not TeX. If
you would like to convert full TeX documents into HTML to publish
online, you should use a TeX to HTML converter like
LaTeXML,
Tralics, or
tex4ht, but you should
realize that TeX conversion tools will never produce results as good as
controlling the HTML and CSS source yourself.
What should IE’s X-UA-Compatible meta tag be set to?¶
We strongly suggest to follow Microsoft’s suggestion to use IE=edge
. That
is, in the document <head>
include
<meta http-equiv="X-UA-Compatible" content="IE=edge">
before any other tags in the <head>
.
This will force all IE versions to use their latest engine which is the
optimal setting for MathJax. For more information, see the Microsoft
documentation on compatibility modes.
Does MathJax support TeX macros?¶
Yes. You can define TeX macros in MathJax the same way you do in LaTeX
with \newcommand{cmd}{args}{def}
. An example is
\newcommand{\water}{H_{2}O}
, which will output the chemical formula
for water when you use the \water
command. \renewcommand
works
as well. You can also store macros in the MathJax configuration. For
more information, see the
documentation.