The MathJax Processing Model

The purpose of MathJax is to bring the ability to include mathematics easily in web pages to as wide a range of browsers as possible. Authors can specify mathematics in a variety of formats (e.g., MathML, LaTeX, or AsciiMath), and MathJax provides high-quality mathematical typesetting even in those browsers that do not have native MathML support. This all happens without the need for special downloads or plugins, but rendering will be enhanced if high-quality math fonts (e.g., STIX) are available to the browser.

MathJax is broken into several different kinds of components: page preprocessors, input processors, output processors, and the MathJax Hub that organizes and connects the others. The input and output processors are called jax, and are described in more detail below.

When MathJax runs, it looks through the page for special tags that hold mathematics; for each such tag, it locates an appropriate input jax which it uses to convert the mathematics into an internal form (called an element jax), and then calls an output jax to transform the internal format into HTML content that displays the mathematics within the page. The page author configures MathJax by indicating which input and output jax are to be used.

Often, and especially with pages that are authored by hand, the mathematics is not stored (initially) within the special tags needed by MathJax, as that would require more notation than the average page author is willing to type. Instead, it is entered in a form that is more natural to the page author, for example, using the standard TeX math delimiters $...$ and $$...$$ to indicate what part of the document is to be typeset as mathematics. In this case, MathJax can run a preprocessor to locate the math delimiters and replace them by the special tags that it uses to mark the formulas. There are preprocessors for TeX notation, MathML notation, AsciiMath notation, and the jsMath notation that uses span and div tags.

For pages that are constructed programmatically, such as HTML pages that result from running a processor on text in some other format (e.g., pages produced from Markdown documents, or via programs like tex4ht), it would be best to use MathJax’s special tags directly, as described below, rather than having MathJax run another preprocessor. This will speed up the final display of the mathematics, since the extra preprocessing step would not be needed. It also avoids the conflict between the use of the less-than sign, <, in mathematics and as an HTML special character (that starts an HTML tag), and several other issues involved in having the mathematics directly in the text of the page (see the documentation on the various input jax for more details on this).

How mathematics is stored in the page

In order to identify mathematics in the page, MathJax uses special <script> tags to enclose the mathematics. This is done because such tags can be located easily, and because their content is not further processed by the browser; for example, less-than signs can be used as they are in mathematics, without worrying about them being mistaken for the beginnings of HTML tags. One may also consider the math notation as a form of “script” for the mathematics, so a <script> tag makes at least some sense for storing the math.

Each <script> tag has a type attribute that identifies the kind of script that the tag contains. The usual (and default) value is type="text/javascript", and when a script has this type, the browser executes the script as a javascript program. MathJax, however, uses the type math/tex to identify mathematics in the TeX and LaTeX notation, math/mml for mathematics in MathML notation, and math/asciimath for mathematics in AsciiMath notation. When the tex2jax, mml2jax, or asciimath2jax preprocessors run, they create <script> tags with these types so that MathJax can process them when it runs its main typesetting pass.

For example,

<script type="math/tex">x+\sqrt{1-x^2}</script>

represents an in-line equation in TeX notation, and

<script type="math/tex; mode=display">
  \sum_{n=1}^\infty {1\over n^2} = {\pi^2\over 6}
</script>

is a displayed TeX equation.

Alternatively, using MathML notation, you could use

<script type="math/mml">
  <math>
    <mi>x</mi>
    <mo>+</mo>
    <msqrt>
      <mn>1</mn>
      <mo>&#x2212;<!-- − --></mo>
      <msup>
        <mi>x</mi>
        <mn>2</mn>
      </msup>
    </msqrt>
  </math>
</script>

for in-line math, or

<script type="math/mml">
  <math display="block">
    <mrow>
      <munderover>
        <mo>&#x2211;<!-- ∑ --></mo>
        <mrow>
          <mi>n</mi>
          <mo>=</mo>
          <mn>1</mn>
        </mrow>
        <mi mathvariant="normal">&#x221E;<!-- ∞ --></mi>
      </munderover>
    </mrow>
    <mrow>
      <mfrac>
        <mn>1</mn>
        <msup>
          <mi>n</mi>
          <mn>2</mn>
        </msup>
      </mfrac>
    </mrow>
    <mo>=</mo>
    <mrow>
      <mfrac>
        <msup>
          <mi>&#x03C0;<!-- π --></mi>
          <mn>2</mn>
        </msup>
        <mn>6</mn>
      </mfrac>
    </mrow>
  </math>
</script>

for displayed equations in MathML notation. As other input jax are created, they will use other types to identify the mathematics they can process.

Page authors can use one of MathJax’s preprocessors to convert from math delimiters that are more natural for the author to type (e.g., TeX math delimiters like $$...$$) to MathJax’s <script> format. Blog and wiki software could extend their own markup languages to include math delimiters, which they could convert to MathJax’s <script> format automatically.

Note, however, that Internet Explorer (version 8 and belowhas a bug that causes it to remove the space before a <script> tag if there is also a space after it, which can cause serious spacing problems with in-line math in Internet Explorer. There are three possible solutions to this in MathJax. The recommended way is to use a math preview (an element with class MathJax_Preview) that is non-empty and comes right before the <script> tag. Its contents can be just the word [math], so it does not have to be specific to the mathematics script that follows; it just has to be non-empty (though it could have its style set to display:none). See also the preJax and postJax options in the Core Configuration Options document for another approach.

The components of MathJax

The main components of MathJax are its preprocessors, its input and output jax, and the MathJax Hub, which coordinates the actions of the other components.

Input jax are associated with the different script types (like math/tex or math/mml) and the mapping of a particular type to a particular jax is made when the various jax register their abilities with the MathJax Hub at configuration time. For example, the MathML input jax registers the math/mml type, so MathJax will know to call the MathML input jax when it sees math elements of that type. The role of the input jax is to convert the math notation entered by the author into the internal format used by MathJax (called an element jax). This internal format is essentially MathML (represented as JavaScript objects), so an input jax acts as a translator into MathML.

Output jax convert that internal element jax format into a specific output format. For example, the NativeMML output jax inserts MathML tags into the page to represent the mathematics, while the HTML-CSS output jax uses HTML with CSS styling to lay out the mathematics so that it can be displayed even in browsers that don’t understand MathML. MathJax also has an SVG output jax that will render the mathematics using scalable vector graphics. Output jax could be produced that render the mathematics using HTML5 canvas elements, for example, or that speak an equation for blind users. The MathJax contextual menu can be used to switch between the output jax that are available.

Each input and output jax has a small configuration file that is loaded when that input jax is included in the jax array in the MathJax configuration, and a larger file that implements the core functionality of that particular jax. The latter file is loaded the first time the jax is needed by MathJax to process some mathematics. Most of the combined configuration files include only the small configuration portion for the input and output jax, making the configuraiton file smaller and faster to load for those pages that don’t actually include mathematics; the combined configurations that end in -full include both parts of the jax, so there is no delay when the math is to be rendered, but at the expense of a larger initial download.

The MathJax Hub keeps track of the internal representations of the various mathematical equations on the page, and can be queried to obtain information about those equations. For example, one can obtain a list of all the math elements on the page, or look up a particular one, or find all the elements with a given input format, and so on. In a dynamically generated web page, an equation where the source mathematics has changed can be asked to re-render itself, or if a new paragraph is generated that might include mathematics, MathJax can be asked to process the equations it contains.

The Hub also manages issues concerning mouse events and other user interaction with the equation itself. Parts of equations can be made active so that mouse clicks cause event handlers to run, or activate hyperlinks to other pages, and so on, making the mathematics as dynamic as the rest of the page.