Typesetting and Converting Mathematics

There are two main uses for MathJax:

Typesetting all the mathematics within a web page, and
Converting a string containing mathematics into another form.

In version 2, MathJax could perform the first function very well, but it was much harder to do the second. MathJax version 3 makes both easy to do. Both these tasks are described below.

Typesetting Math in a Web Page

MathJax makes it easy to typeset all the math in a web page, and in fact it will do this automatically when it is first loaded unless you configure it not to. So this is one of the easiest actions to perform in MathJax; if your page is static, there is nothing to do but load MathJax.

If your page is dynamic, and you may be adding math after the page is loaded, then you will need to tell MathJax to typeset the mathematics once it has been inserted into the page. There are two methods for doing that: MathJax.typeset() and MathJax.typesetPromise().

The first of these, MathJax.typeset(), typesets the page, and does so immediately and synchronously, so when the call finishes, the page will have been typeset. Note, however, that if the math includes actions that require additional files to be loaded (e.g., TeX input that uses require, or that includes autoloaded extensions), then an error will be thrown. You can use the try/catch command to trap this condition.

The second, MathJax.typesetPromise(), performs the typesetting asynchronously, and returns a promise that is resolved when the typesetting is complete. This properly handles loading of external files, so if you are expecting to process TeX input that can include require or autoloaded extensions, you should use this form of typesetting. It can be used with await as part of a larger async function.

Both functions take an optional argument, which is an array of elements whose content should be processed. An element can be either an actual DOM element, or a CSS selector string for an element or collection of elements. Supplying an array of elements will restrict the typesetting to the contents of those elements only.

Handling Asynchronous Typesetting

It is generally a bad idea to try to perform multiple asynchronous typesetting calls simultaneously, so if you are using MathJax.typesetPromise() to make several typeset calls, you should chain them using the promises they return. For example:

MathJax.typesetPromise().then(() => {
  // modify the DOM here
  MathJax.typesetPromise();
}).catch((err) => console.log(err.message));

This approach can get complicated fast, however, so you may want to maintain a promise that can be used to chain the later typesetting calls. For example,

let promise = Promise.resolve();  // Used to hold chain of typesetting calls

function typeset(code) {
  promise = promise.then(() => MathJax.typesetPromise(code()))
                   .catch((err) => console.log('Typeset failed: ' + err.message));
  return promise;
}

Then you can use typeset() to run code that changes the DOM and typesets the result. The code() that you pass it does the DOM modifications and returns the array of elements to typeset, or null to typeset the whole page. E.g.,

typeset(() => {
  const math = document.querySelector('#math');
  math.innerHTML = '$$\\frac{a}{1-a^2}$$';
  return [math];
});

would replace the contents of the element with id="math" with the specified fraction and have MathJax typeset it (asynchronously). Because the then() call returns the result of MathJax.typesetPromise(), which is itself a promise, the then() will not resolve until that promise is resolved; i.e., not until the typesetting is complete. Finally, since the typeset() function returns the promise, you can use await in an async function to wait for the typesetting to complete:

await typeset(...);

Note that this doesn’t take the initial typesetting that MathJax performs into account, so you might want to use MathJax.startup.promise in place of promise above. I.e., simply use

function typeset(code) {
  MathJax.startup.promise = MathJax.startup.promise
    .then(() => MathJax.typesetPromise(code()))
    .catch((err) => console.log('Typeset failed: ' + err.message));
  return MathJax.startup.promise;
}

This avoids the need for the global promise variable, and makes sure that your typesetting doesn’t occur until the initial typesetting is complete.

Resetting Automatic Equation Numbering

The TeX input jax allows you to automatically number equations. When modifying a page, this can lead to problems as numbered equations may be removed and added; most commonly, duplicate labels lead to issues.

You can reset equation numbering using the command

MathJax.texReset([start])

where start is the number at which to start equation numbering.

Updating Previously Typeset Content

MathJax keeps track of all the math that it has typeset within your page. This is so that if you change the output renderer (using the MathJax contextual menu), it can be changed to use the new format, for example; or if you change the accessibility settings, say to enable the expression explorer, all the math can be updated to include the speech strings that it uses. If you modify the page to include new mathematics and call MathJax.typeset() or MathJax.typesetPromise(), the newly typeset mathematics will be added to the list of already typeset mathematics, as you would expect.

If you modify the page to remove content that contains typeset mathematics, you will need to tell MathJax about that so that it knows the typeset math that you are removing is no longer on the page. You do this by using the MathJax.typesetClear() method.

When called with no arguments, MathJax.typesetClear() tells MathJax to forget about all the math that has been typeset so far. Note that the math will remain in the page as typeset math, but MathJax will no longer know anything about it. For example, that means that changes to the output renderer or accessibility settings will not affect any of the math that was typeset previously.

If you remove math from only a portion of the page, you can call MathJax.typesetClear() passing it an array of container elements that have been (or will be) removed, and MathJax will forget about the math that is within those containers, while remembering the rest of the math on the page. For example, if you have an element with id="has-math" that you have previously typeset, and you are planning to replace the contents of this element with new content (stored in a variable new_html) that needs to be typeset, you might use something like:

const node = document.getElementById('has-math');
MathJax.typesetClear([node]);
node.innerHTML = new_html;
MathJax.typesetPromise([node]).then(() => {
  // the new content is has been typeset
});

The argument passed to MathJax.typsetClear() can be an actual DOM element, as in the example above, or a CSS selector string (e.g., '#has-math'), or an array of these. The selector can specify more than one container element (e.g., via a class selector).

If you are using automatic equation numbers and insert new content in the middle of the page, that may require the equation numbers to be adjusted throughout the page. In that case, you can do

MathJax.startup.document.state(0);
MathJax.texReset();
MathJax.typeset();

to force MathJax to reset the page to the state it was before MathJax processed it (i.e., remove its typeset math), reset the TeX automatic line numbering and labels, and then re-typeset the contents of the page from scratch.

Looking up the Math on the Page

MathJax saves its information about a particular expression that it has typeset in an object called a MathItem; each typeset expression has an associated MathItem. You can look up the MathItems using the MathJax.startup.document.getMathItemsWithin() function. You pass this a container element (or a CSS selector for an element or collection of elements, or an array of containers or selectors) and it will return an array of the MathItems that are within those containers. E.g.,

MathJax.startup.document.getMathItemsWithin(document.body);

will return an array of all the MathItems for the typeset math on the page. See the MathItem definition for details on the contents of the MathItem structure. The MathItem is the v3 replacement for the v2 ElementJax object, and getMathItemsWithin() performs a similar function to the v2 function MathJax.Hub.getAllJax().

Typesetting User-Supplied Content

Mathematics formats like LaTeX and MathML allow a powerful range of layout options, including access to hyperlinks, CSS styles, font selection and sizing, spacing, and so on. Such features give you a great deal of flexibility in producing the mathematics for your pages, but if your readers are allowed to enter mathematics into your pages (e.g., for a question-and-answer site, or in comments on a blog), these features can be abused to cause problems for other readers and pose a potential security risk to them. For example, the TeX \href command can be used to insert javascript: links into the page, while the \style macro could be used to disrupt the user interface or layout of your pages.

In order to limit the potential interference that could be caused by the mathematics entered by your readers, MathJax provides the ui/safe extension. This extension filters the mathematics on the page in order to try to remove problematic attributes, like javascript links, or font sizes that are too large or too small, or style settings that would be disruptive to the page layout. If your page allows your readers to post content that includes mathematics processed by MathJax, you should strongly consider using the ui/safe extension.

See the Safe Extension Options section for details of how to load and configure the ui/safe extension.

Loading MathJax Only on Pages with Math

The MathJax combined configuration files are large, and so you may wish to include MathJax in your page only if it is necessary. If you are using a content-management system that puts headers and footers into your pages automatically, you may not want to include MathJax directly, unless most of your pages include math, as that would load MathJax on all your pages. Once MathJax has been loaded, it should be in the browser’s cache and load quickly on subsequent pages, but the first page a reader looks at will load more slowly. In order to avoid that, you can use a script like the following one that checks to see if the content of the page seems to include math, and only loads MathJax if it does. Note that this is not a very sophisticated test, and it may think there is math in some cases when there really isn’t but it should reduce the number of pages on which MathJax will have to be loaded.

Create a file called check-for-tex.js containing the following:

(function () {
  var body = document.body.textContent;
  if (body.match(/(?:\$|\\\(|\\\[|\\begin\{.*?})/)) {
    if (!window.MathJax) {
      window.MathJax = {
        tex: {
          inlineMath: {'[+]': [['$', '$']]}
        }
      };
    }
    var script = document.createElement('script');
    script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js';
    document.head.appendChild(script);
  }
})();

and then use

<script src="check-for-tex.js" defer></script>

in order to load the script when the page content is ready. Note that you will want to include the path to the location where you stored check-for-tex.js, that you should change tex-chtml.js to whatever component file you want to use, and that the window.MathJax value should be set to whatever configuration you want to use. In this case, it just adds dollar signs to the in-line math delimiters. Finally, adjust the body.match() regular expression to match whatever you are using for math delimiters.

This simply checks if there is something that looks like a TeX in-line or displayed math delimiter, and loads MathJax if there is. If you are using different delimiters, you will need to change the pattern to include those (and exclude any that you don’t use). If you are using AsciiMath instead of TeX, then change the pattern to look for the AsciiMath delimiters.

If you are using MathML, you may want to use

if (document.body.querySelector('math')) {...}

for the test instead (provided you aren’t using namespace prefixes, like <m:math>).

Converting a Math String to Other Formats

An important use case for MathJax is to convert a string containing mathematics (in one of the three forms that MathJax understands) and convert it into another form (either MathML, or one of the output formats that MathJax supports). This was difficult to do in MathJax version 2, but easy to do in version 3.

When MathJax starts up, it creates methods for converting from the input format(s) to the output format(s) that you have loaded, and to MathML format. For example, if you have loaded the MathML input jax and the SVG output jax (say by using the mml-svg component), then MathJax will create the following conversion methods for you:

MathJax.mathml2svg(math[,options])

MathJax.mathml2svgPromise(math[,options])

MathJax.mathml2mml(math[,options])

MathJax.mathml2mmlPromise(math[,options])

If you had loaded the TeX input jax as well, you would also get four more methods, with tex in place of mathml.

As the names imply, the Promise functions perform the conversion asynchronously, and return promises, while the others operate synchronously and return the converted form immediately. The first two functions (and any others like them) produce DOM elements as the results of the conversion, with the promise versions passing that to their then() functions as their argument (see the section on Asynchronous Conversion below), and the non-promise versions returning them directly. You can insert these DOM elements into the document directly, or you can use their outerHTML property to obtain their serialized string form.

The functions that convert to MathML produce serialized MathML strings automatically, rather than DOM elements. (You can use the browser’s DOMParser object to convert the string into a MathML DOM tree if you need one.)

Conversion Options

All four of these functions require an argument that is the math string to be converted (e.g., the serialized MathML string, or in the case of tex2chtml(), the TeX or LaTeX string). You can also pass a second argument that is an object containing options that control the conversion process. The options that can be included are:

display, a boolean specifying whether the math is in display-mode or not (for TeX input). Default is true.
em, a number giving the number of pixels in an em for the surrounding font. Default is 16.
ex, a number giving the number of pixels in an ex for the surrounding font. Default is 8.
containerWidth, a number giving the width of the container, in pixels. Default is 80 times the ex value.
lineWidth', a number giving the line-breaking width in em units. Default is a very large number (100000), so effectively no line breaking.
scale, a number giving a scaling factor to apply to the resulting conversion. Default is 1.

For example,

let html = MathJax.tex2chtml('\\sqrt{x^2+1}', {em: 12, ex: 6, display: false});

would convert the TeX expression \sqrt{x^2+1} to HTML as an in-line expression, with em size being 12 pixels and ex size being 6 pixels. The result will be a DOM element containing the HTML for the expression. Similarly,

let html = MathJax.tex2chtml('\\sqrt{x^2+1}', {em: 12, ex: 6, display: false});
let text = html.outerHTML;

sets text to be the serialized HTML string for the expression.

Obtaining the Output Metrics

Since the em, ex, and containerWidth all depend on the location where the math will be placed in the document (they are values based on the surrounding text font and the container elements width), MathJax provides a method for obtaining these values from a given DOM element. The method

MathJax.getMetricsFor(node, display)

takes a DOM element (node) and a boolean (display), indicating if the math is in display mode or not, and returns an object containing all six of the options listed above. You can pass this object directly to the conversion methods discussed above. So you can do something like

let node = document.querySelector('#math');
let options = MathJax.getMetricsFor(node, true);
let html = MathJax.tex2svg('\\sqrt{x^2+1}', options);
node.appendChild(html);

in order to get the correct metrics for the (eventual) location of the math that is being converted. Of course, it would be easier to simply insert the TeX code into the page and use MathJax.typeset() to typeset it, but this is just an example to show you how to obtain the metrics from a particular location in the page.

Note that obtaining the metrics causes a page refresh, so it is expensive to do this. If you need to get the metrics from many different locations, there are more efficient ways, but these are advanced topics to be dealt with elsewhere.

Obtaining the Output Stylesheet

The output from the SVG and CommonHTML output jax both depend on CSS stylesheets in order to properly format their results. You can obtain the SVG stylesheet element by calling

MathJax.svgStylesheet();

and the HTML stylesheet from

MathJax.chtmlStylesheet();

The CommonHTML output jax CSS can be quite large, so the output jax tries to minimize the stylesheet by including only the styles that are actually needed for the mathematics that has been processed by the output jax. That means you should request the stylesheet only after you have typeset the mathematics itself.

Moreover, if you typeset several expressions, the stylesheet will include everything needed for all the expressions you have typeset. If you want to reset the stylesheet, then use

MathJax.startup.output.clearCache();

if the output jax is the CommonHTML output jax. So if you want to produce the style sheet for a single expression, issue the clearCache() command just before the tex2chtml() call.

Asynchronous Conversion

If you are converting TeX or LaTeX that might use require to load extensions, or where extensions might be autoloaded, you will either need to use one of the “full” components that include all the extensions, or preload all the extensions you need if you plan to use the synchronous calls listed above. Otherwise, you can use the promise-based calls, which handle the loading of extensions transparently.

For example,

let node = document.querySelector('#math');
let options = MathJax.getMetricsFor(node, true);
MathJax.tex2chtmlPromise('\\require{bbox}\\bbox[red]{\\sqrt{x^2+1}}', options)
  .then((html) => {
    node.appendChild(html);
    let sheet = document.querySelector('#MJX-CHTML-styles');
    if (sheet) sheet.parentNode.removeChild(sheet);
    document.head.appendChild(MathJax.chtmlStylesheet());
  });

would get the metrics for the element with id="math", convert the TeX expression using those metrics (properly handling the asynchronous load needed for the \require command); then when the expression is typeset, it is added to the document and the CHTML stylesheet is updated.