Attention

Version 3 is now the current version of MathJax. This document is for version 2.

The Core Configuration Options

The options below control the MathJax Hub, and so determine the code behavior of MathJax. They are given with their default values.

jax: ["input/TeX","output/HTML-CSS"]

A comma-separated list of input and output jax to initialize at startup. Their main code is loaded only when they are actually used, so it is not inefficient to include jax that may not actually be used on the page. These are found in the MathJax/jax directory.

extensions: []

A comma-separated list of extensions to load at startup. The default directory is MathJax/extensions. The tex2jax and mml2jax preprocessors can be listed here, as well as a FontWarnings extension that you can use to inform your user that mathematics fonts are available that they can download to improve their experience of your site.

config: []

A comma-separated list of configuration files to load when MathJax starts up, e.g., to define local macros, etc., and there is a sample config file named config/local/local.js. The default directory is the MathJax/config directory. The MMLorHTML.js configuration is one such configuration file, and there are a number of other pre-defined configurations (see Using a configuration file for more details).

styleSheets: []

A comma-separated list of CSS stylesheet files to be loaded when MathJax starts up. The default directory is the MathJax/config directory.

styles: {}

CSS styles to be defined dynamically at startup time. These are in the form selector:rules (see CSS Style Objects for complete details).

preJax: null and postJax: null

Patterns to remove from before and after math script tags. If you are not using one of the preprocessors, you need to insert something extra into your HTML file in order to avoid a bug in Internet Explorer. IE removes spaces from the DOM that it thinks are redundant, and since a <script> tag usually doesn’t add content to the page, if there is a space before and after a MathJax <script> tag, IE will remove the first space. When MathJax inserts the typeset mathematics, this means there will be no space before it and the preceding text. In order to avoid this, you should include some “guard characters” before or after the math SCRIPT tag; define the patterns you want to use below. Note that these are used as part of a regular expression, so you will need to quote special characters. Furthermore, since they are javascript strings, you must quote javascript special characters as well. So to obtain a backslash, you must use \\ (doubled for javascript). For example, "\\[" represents the pattern \[ in the regular expression, or [ in the text of the web page. That means that if you want an actual backslash in your guard characters, you need to use "\\\\" in order to get \\ in the regular expression, and \ in the actual text. If both preJax and postJax are defined, both must be present in order to be removed.

See also the preRemoveClass comments below.

Examples:

preJax: "\\\\\\\\\" makes a double backslash the preJax text

preJax: "\\[\\[", postJax: "\\]\\]" makes it so jax scripts must be enclosed in double brackets.

preRemoveClass: "MathJax_Preview"

This is the CSS class name for math previews that will be removed preceding a MathJax SCRIPT tag. If the tag just before the MathJax <script> tag is of this class, its contents are removed when MathJax processes the <script> tag. This allows you to include a math preview in a form that will be displayed prior to MathJax performing its typesetting. It also avoids the Internet Explorer space-removal bug, and can be used in place of preJax and postJax if that is more convenient.

For example

<span class="MathJax_Preview">[math]</span><script  type="math/tex">...</script>

would display “[math]” in place of the math until MathJax is able to typeset it.

See also the preJax and postJax comments above.

showProcessingMessages: true

This value controls whether the Processing Math: nn% messages are displayed in the lower left-hand corner. Set to false to prevent those messages (though file loading and other messages will still be shown).

messageStyle: "normal"

This value controls the verbosity of the messages in the lower left-hand corner. Set it to "none" to eliminate all messages, or set it to "simple" to show “Loading…” and “Processing…” rather than showing the full file name or the percentage of the mathematics processed.

displayAlign: "center" and displayIndent: "0em"

These two parameters control the alignment and shifting of displayed equations. The first can be "left", "center", or "right", and determines the alignment of displayed equations. When the alignment is not "center", the second determines an indentation from the left or right side for the displayed equations.

delayStartupUntil: "none"

Normally MathJax will perform its startup commands (loading of configuration, styles, jax, and so on) as soon as it can. If you expect to be doing additional configuration on the page, however, you may want to have it wait until the page’s onload handler is called. If so, set this to "onload". You can also set this to "configured", in which case, MathJax will delay its startup until you explicitly call MathJax.Hub.Configured(). See Configuring MathJax after it is loaded for more details.

skipStartupTypeset: false

Normally MathJax will typeset the mathematics on the page as soon as the page is loaded. If you want to delay that process, in which case you will need to call MathJax.Hub.Typeset() yourself by hand, set this value to true.

elements: []

This is a list of DOM element ID’s that are the ones to process for mathematics when any of the Hub typesetting calls (Typeset(), Process(), Update(), etc.) are called with no element specified, and during MathJax’s initial typesetting run when it starts up. This lets you restrict the processing to particular containers rather than scanning the entire document for mathematics. If none are supplied, the complete document is processed.

positionToHash: true

Since typesetting usually changes the vertical dimensions of the page, if the URL contains an anchor position, then after the page is typeset, you may no longer be positioned at the correct position on the page. MathJax can reposition to that location after it completes its initial typesetting of the page. This value controls whether MathJax will reposition the browser to the #hash location from the page URL after typesetting for the page.

showMathMenu: true

showMathMenuMSIE: true

These control whether to attach the MathJax contextual menu to the expressions typeset by MathJax. Since the code for handling MathPlayer in Internet Explorer is somewhat delicate, it is controlled separately via showMathMenuMSIE, but the latter is now deprecated in favor of the MathJax contextual menu settings for MathPlayer (see below).

If showMathMenu is true, then right-clicking (on Windows or Linux) or control-clicking (on Mac OS X) will produce a MathJax menu that allows you to get the source of the mathematics in various formats, change the size of the mathematics relative to the surrounding text, get information about MathJax, and configure other MathJax settings.

Set this to false to disable the menu. When true, the MathMenu configuration block determines the operation of the menu. See the MathMenu options for more details.

These values used to be listed in the separate output jax, but have been moved to this more central location since they are shared by all output jax. MathJax will still honor their values from their original positions, if they are set there.

menuSettings: { ... }

This block contains settings for the mathematics contextual menu that act as the defaults for the user’s settings in that menu. The possible values are:

zoom: "None"

This indicates when typeset mathematics should be zoomed. It can be set to "None", "Hover", "Click", or "Double-Click" to set the zoom trigger.

CTRL: false, ALT: false, CMD: false, Shift: false

These values indicate which keys must be pressed in order for math zoom to be triggered. For example, if CTRL is set to true and zoom is "Click", then math will be zoomed only when the user control-clicks on mathematics (i.e., clicks while holding down the CTRL key). If more than one is true, then all the indicated keys must be pressed for the zoom to occur.

zscale: "200%"

This is the zoom scaling factor, and it can be set to any of the values available in the Zoom Factor menu of the Settings submenu of the contextual menu.

context: "MathJax"

This controls what contextual menu will be presented when a right click (on a PC) or CTRL-click (on the Mac) occurs over a typeset equation. When set to "MathJax", the MathJax contextual menu will appear; when set to "Browser", the browser’s contextual menu will be used. For example, in Internet Explorer with the MathPlayer plugin, if this is set to "Browser", you will get the MathPlayer contextual menu rather than the MathJax menu.

texHints: true

This controls whether the “Show Math as” menu item includes special class names that help MathJax to typeset the mathematics that was produced by the TeX input jax. If these are included, then you can take the output from “Show Math as” and put it into a page that uses MathJax’s MathML input jax and expect to get the same results as the original TeX. (Without this, there may be some spacing differences.)

inTabOrder: true

This controls whether math elements should be included in the tabindex. If set to true, MathJax will add tabindex=0`to the output. If set to ``false`, it will add tabindex="-1". Developers are strongly discouraged from initially disabling this (by means of configuration) as it will render the menu inaccessible.

semantics: false

This controls whether the “Show Math as ⇒ MathML Code” menu item includes the TeX or AsciiMath input as annotations. If these are included, then you can take the output from “Show Math as ⇒ MathML” and put it into a page that uses MathJax’s MathML input jax and allow users to access the original input via “Show Math as ⇒ Annotation”.

There are also settings for format, renderer, font, mpContext, and mpMouse, but these are maintained by MathJax and should not be set by the page author.

errorSettings: { ... }

This block contains settings that control how MathJax responds to unexpected errors while processing mathematical equations. Rather than simply crash, MathJax can report an error and go on. The options you can set include:

message: ["[Math Processing Error]"]

This is an HTML snippet that will be inserted at the location of the mathematics for any formula that causes MathJax to produce an internal error (i.e., an error in the MathJax code itself). See the description of HTML snippets for details on how to represent HTML code in this way.

style: {color:"#CC0000", "font-style":"italic"}

This is the CSS style description to use for the error messages produced by internal MathJax errors. See the section on CSS style objects for details on how these are specified in JavaScript.

ignoreMMLattributes: { ... }

This block contains attributeName: boolean pairs that control which attributes should not be preserved from the original MathML. E.g., id:true will be ignored, while id:false will preserve all ids even if other criteria would normally prevent some ids from being copied to the output; use false carefully.

v1.0-compatible: true

This controls whether MathJax issues the warning about not having an explicit configuration in the event that the jax array is empty after configuration is complete. If you really intend that array to be empty, set this flag to false. Note that setting this to false does not cause a default configuration file to be loaded.