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 set webFont: "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, and svg 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.