What’s New in MathJax v3.1

Version 3.1 includes a number of new features, as well as bug fixes for several issues with version 3.0. These are described below.

TeX Package Name Changes

The names of several tex packages have been changed to conform to a new naming convention. All package names are now entirely in lower case. The mixed case naming used in the past proved to be problematic, and so four extensions have been renamed to all lower case: amscd, colorv2, configmacros, and tagformat.

If you are using the component system to load MathJax, the old names will continue to work for now, but the backward-compatibility support may be removed in the future, so you should change the names to their lower case versions for protection against future changed. Note that the names need to be changed in not only in the tex.packages array but also in the name of their configuration options, if any, and in the autoload configuration (e.g., if you are disabling the autoloading of the colorv2 extension).

If you are using direct imports of the MathJax modules, you will need to change to the new names now, as there is no backward-compatibility option for that.

TeX Error Formatting

There is a new formatError option for the TeX input jax that provides a function that is called when a syntax or other error occurs during the processing of a TeX expression. This can be used to trap the errors for reporting purposes, or to process the errors in other ways. See the formatError documentation.

Noundefined Package Options

The noundefined package now has configuration options similar to the ones available in the ones available in version 2. These include the ability to set the text color, background color, and size of the text to use for disoplaying undefined macro names within TeX formulas. See the noundefined options for details.

New textmacros Package

There is a new textmacros package for the TeX input jax that provides support for processing a number of text-mode macros when they appear inside \text{} or other similar settings that produce text-mode material. This allows you to quote TeX special characters, create accented characters, change fonts and sizes, add spacing, etc., within text-mode material. See the textmacros page for complete details.

New Safe Extension

The Safe extension hs now been ported from v2 to v3. This extensions allows you to filter the values used in the attributes of the underlying MathML that is generated from the TeX, AsciiMath, or MathML input. This can be used to prevent certain URLs from being used, or certain CSS styles from being used, etc. See Typesetting User-Supplied Content for more details.

New Accessibility Features

MathJax’s accessibility code has undergone some internal improvements for speed and reliability. In addition, there is now a localization of the speech output for the German language. The accessibility contextual menu has been updated to include the ability to select the localization language (in the speech submenu), and to expose additional features, such as the ability to set the opacity of the foreground and background colors in the highlight submenu. Finally, there is a new control panel for managing the Clearspeak preferences available in the Clearspeak rules submenu of the Speech menu. See the Accessibility Extension for more details.

MathML Verification Options

The MathML input jax has the ability to check and report or (sometimes) correct errors in MathML trees, but the options that control this checking were not documented, and could not be changed easily. Version 3.1 exposes these options so they can be set in the configuration block for the MathML input jax.

New Output Configuration Options

There are two new output configuration options, and updated behavior and defaults for two existing options. These options control the fonts used for <mtext> and <merror> elements. The original mtextInheritFont and merrorInheritFont properties controlled whether these elements used the same font as the surrounding text, but neither worked properly in version 3.0. This has been fixed in version 3.1 so these now properly cause the surrounding font to be used for the contents of the specified elements when set to true.

If these are set to false, the new mtextFont and merrorFont properties specify a font family (or list of families) to use fort the content of these elements. This allows you to force a specific font to be used for the text within mathematics. If these are set to an empty string, then the MathJax fonts will be used.

The defaults for these are

mtextInheritFont: false,
merrorInheritFont: false,
mtextFont: '',
merrorFont: 'serif',

which means that the MathJax fonts will be used for <mtext> elements, and the browser’s serif font will be used for <merror> text. See the Options Common to All Output Processors for more information.

Note: the default for merrorInheritFont has been changed from true to false now that merrorFont is available.

Startup Promise Revisions

The MathJax.startup.promise now works in a more intuitive way. In the past, it was initially set to be a promise that resolves when MathJax is ready and the DOMContentLoaded event occurs, and was changed by the startup.pageReady() function to one that resolve when the initial typesetting is finished. So you could not use MathJax.startup.promise to tell when the initial typesetting is complete without overriding the startup.pageReady() method as well.

In version 3.1, the MathJax.startup.promise has been changed to one that resolves when the action of the startup.pageReady() method is finished (which includes the initial typesetting action). That makes this promise a reliable way to determine when the initial typesetting is finished.

See the sections on Performing Actions During Startup, on Handling Asynchronous Typesetting, and on the pageReady() for more details.

New API for Clearing Typeset Content

If you are dynamically adding and removing content from your page, you need to tell MathJax abiout what you are doing so that it can typeset any new mathematics, and forget about any old typeset mathematics that you have removed. In version 3.0, the MathJax.typesetClear() method could be used to tell MathJax to forget about all the mathematics that is ahs typeset, but if you only removed some of it, there was no easy way to tell it to forget about only the math you removed. This situation has been improved in version 3.1 by allowing the MathJax.typesetClear() method to accept an array of elements whose contents should be forgotten. See Updating Previously Typeset Content for more details.

New API for Getting Math within a Container

MathJax keeps track of the math that you have typeset using a list of objects called MathItems. These store the original math string, the locatino of the math in the document, the input jax used to process it, and so on. In the past, you had access to these through a list stored in the MathDocument object stored at MathJax.startup.document, but it was not easy to get access to the individual MathItems in a convenient way. In v3.1 there is now a function MathJax.startup.document.getMathItemsWithin() that returns all the MathItems for the typeset math within a DOM container element (or collection of DOM elements). See Looking up the Math on the Page for details.

Change to SRE Interface

In version 3.0.5, The a11y/sre module exposed a value sreReady that was a promise that would be resolved when the Speech-Rule Engine was ready to use. Due to changes in SRE (which can now be configured to load localized translation data, and so may become un-ready while that is happening), the sreReady value in version 3.1.0 is now a function returning a promise, so should be called as sreReady().

Fixes to the LiteDOM and DOMAdaptors

The LiteDOM in version 3.0.5 failed to process comments correctly: they were properly read and ignored, but where not included in the output when the DOM is serialized. In version 3.1.0, this has been fixes so that comments are properly maintained. In addition, the doctype of the document is now retained by the LiteDOM, and can be accessed by a new doctype() method of the DOMAdaptor class (and its subclasses).

Updated Demos

The web and node examples have been updated to use the new features available in version 3.1.0, and to include more examples. In particular, the node examples now include demonstrations of using the simpler loading mechanism for node applications, using puppeteer to perform server-side processing, and using JSDOM for server-side processing.