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(() => {code(); return MathJax.typesetPromise()})
                   .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(() => {code(); return MathJax.typesetPromise()})
    .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.

If you have inserted new content, that may require the entire page to be reprocessed in order to get the automatic numbering, labels, and references to be correct. 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, reset the TeX automatic line numbering and labels, and then re-typeset the contents of the page from scratch.

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-mathjax.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 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.