MathJax v4.0.0-beta.6

This release includes a significant rewrite of the expression explorer and an update to the speech-rule engine (SRE) that underlies MathJax's assistive support. Accompanying this is a reorganization of the MathJax contextual menu that moves the assistive options to a more prominent position for easier access and better control. This release also includes several new font-based TeX packages (and the fonts to accompany them) that provide alternative double-struck character styles. In addition, we have moved from npm to pnpm as the package manager for the MathJax source repository. Finally, there are also a number of bug fixes since the beta.4 release.

We anticipate one more beta release before the official 4.0.0 release.

Explorer Updates

The MathJax expression explorer has been updated to seamlessly fit in with an accessible browsing experience. In particular, there is no longer a need to switch on accessibility support in the contextual menu (which can still be used to explicitly disable that support, as described in the next section). Once a formula is focused, exploration can immediately start by using the arrow keys. (For a full list of keyboard commands see here.) This allows you to dive into the details of the formula, including highlighting sub-expressions, and, if selected, magnification. Moreover, the explorer can now also be started by left-clicking elements within in the formula itself. That is, you can click on any character within the expression to start the explorer at that point in the expression. Communication with screen readers (if any is used) is achieved via aria-label and aria-braille-label elements instead of the live region as utilized previously. Alternatively, automatic voicing and synchronized highlighting can be used directly without a screen reader by switching on those options in the contextual menu.

Menu Updates

The MathJax contextual menu has been reorganized to make the accessibility features more easy to use. The top-level menu now includes an "Accessibility" section with four submenus — "Speech", "Braille", "Explorer", and "Options" — rather than an accessibility submenu as in previous versions. The Speech menu allows you to enable/disable speech generation and its associated visual output, and to turn on or off auto voicing. It also provides control over the speech rule-set to use, the verbosity of the set in use, and the language to use for the speech. Similarly, the Braille menu allows you to enable/disable Braille generation and display, as well as to select the type of Braille to generate.

The explorer controls for magnification and highlighting have been moved to the Explorer menu, and other accessibility options have been moved from the Math Settings and old Accessibility submenus to the Options menu. A new "Semantic Enrichment" option controls whether the accessibility features are available or not (unchecking disables speech and Braille generation and the explorer).

New TeX packages

This release of MathJax includes three new TeX packages that provide alternative double-struck (i.e., blackboard bold) character sets: dsfont, bbm, and bboldx. New font extensions for the mathjax-modern font are now available for these packages, and the font extensions are loaded automatically when the TeX package is loaded. Currently, these fonts are available only in combination with the mathjax-modern font, but in the next release, they will be able to be applied to any of the available fonts.

The dsfont package defines a macro \mathds that provides access to its double-struck characters. There is a configuration option that controls whether the sans-serif version of these fonts is used, or the roman versions:

MathJax = {
  tex: {
    dsfont: {
      sans: true   // default is false
    }
  }
}

The bbm package defines macros \mathbbm, '\mathmmbss, and \mathbbmttto generate its double-struck characters, as well as a\mathversionmacro that can be used to select the version of the double-struck fonts to use (this is a global setting). Here,\mathversion{bold}selects the bold versions of the double-struck characters, while any argument other thanbold` will select the normal versions of the fonts.

The bboldx package redefines \mathbb to use the bboldx double-struck characters, and adds \mathbfbb to access their bold-face versions, plus \imathbb, \jmathbb, \imathbfbb, and \jmathbfbb for dotless i and j characters in these fonts. In addition, there are macros for upper- and lower-case Greek letters, e.g., \bbGamma, \bfbbsigma, etc., and text-based versions of these for use in \text{}, e.g., \txtbbGamma. The bold delimiters \bbLparen, \bbRparen, \bbLbrack, \bbRbrack, \bbLangle, \bbRangle, and the bfbb versions of these, are defined, but do not yet work with \left and \right. That will be addressed in the next release.

Move from npm to pnpm

With this release, MathJax is switching to pnpm as our package manager rather than npm. This speeds up installation and improves script handling. Although you can still use npm, some of the scripts in package.json call pnpm, so you will need to have pnpm installed to use those scripts. Fortunately, this only affects those who are compiling and packaging MathJax, so unless you are working with the MathJax source files, you should not be affected by this change. If you are only using MathJax in web pages via a CDN, for example, you will not need to worry about pnpm (or npm).

To install pnpm you can use

npm install -g pnpm

---

The following sections indicate the bug fixes in this release:

TeX Input Fixes

• Add dsfont, bbm, and bboldx TeX extensions (#1055, #1056, #1057, #1063, #1064, #1065, #1074, #1075, #1076)

• Make textcomp package register with textmacros automatically. (#1073)

• Fix problems with data-latex attribute generation (mathjax/MathJax#3184) (#1028, #1060)

• Allow unknown characters to use operator table to determine class and node type. (mathjax/MathJax#3203) (#1070)

• Handle primes in munderover as in msubsup. (mathjax/MathJax#3202) (#1069)

• Make \symbf and \symsf handle Greek italics as in LaTeX. (#1061)

• Add missing commands to textmacros package (#1071)

• Make stretchy paired delimiters in math tools package not be class INNER. (mathjax/MathJax#3183) (#1059)

• Fix \require to properly handle retries in dependencies. (mathjax/MathJax#3170) (#1050)

• Move \divsymbol to physics package and add \divisionsymbol. (mathjax/MathJax#3173) (#1049)

• Allow (embellished) operators in \underset, \overset, and \underoverset to specify accent="true" (#894)

• Fix processing of \U{...} where two occurrences in \text{} would fail. (#1048)

• Update handling of braket bars so that the enclosing braket can be more accurately found. (mathjax/MathJax#3164) (#1041)

• Fix problem with \let using attributes of {} when they should be null (#1030)

• Have \unicode check for illegal font name. (mathjax/MathJax#3129) (#1019)

Output Fixes

• Add xmlns attribute for global cache svg element. (mathjax/MathJax-demos-node#58) (#1045)

• Fix issues with line breaks and spacing in SVG output. (mathjax/MathJax#3166) (#1043)

• Make sure math items have their metrics set before lazy typesetting. (mathjax/MathJax#3167) (#1042)

• Don't descend into items that aren't broken when looking for the line-break node. (mathjax/MathJax#3135) (#1024)

• Fix font extension handling of extra variants, and handle those variants in enrichment. (#1033)

• Update CHTML longdiv output to not require clip-path. (#1025)

• Better measuring of text that is in a native font rather than MathJax fonts (#1014)

User Interface Updates

• Update accessibility menu items (#1068, #1082)

• Update expression explorer (#987, #1035, #1040, #1053, #1058, #1078, #1079)

• Fix problem with spurious white pixels from unused explorer regions (mathjax/MathJax#3001) (#1072)

• Fix rendering of embedded HTML to work with scaling and mathsize changes. (mathjax/MathJax#3116) (#1012)

• Add ability to not show latex attributes, and reorganize settings menu (#1017)

API Fixes

• Proper handling of typesetPromise() in defaultPageReady(). (mathjax/MathJax#3130) (#1018)

• Move from npm to pnpm (#1021, #1023, #1077)

• Add missing Text.splitText() method to linkedom. (mathjax/MathJax#3134) (#1036)

• Update LiteParser's serializeXML() method. (mathjax/MathJax-demos-node#58) (#1046)

• Fix menu to not re-render if no typesetting has occurred. (mathjax/MathJax#3167) (#1044)

• Fix keyvalOptions to process braces and backslashes better (#1031)

• Update TeX input's keyvalOptions, and add GetBrackets() option to match brackets. (#1037)

• Add ability to do typechecking and conversion on the values of key-value options (#1032)

• Clear process bits for findMath and attach-speech, and remove safe bit that isn't needed. (#1034)

• Refactor input/tex/ParseUtil.ts to remove namespace (#1022)

• Add cssText() method to DOMadaptor and handle dynamic rules in HTML output. (#1027)

• Make const enum DIRECTION into a regular object. (mathjax/MathJax#3114) (#1026)

• Fix default option list to {} in constructors for output jax. (mathjax/MathJax#3128) (#1016)

• Fix make-cjs-components script to work without mjs files being built first (#1013)

MathJax v4.0.0-beta.5

This release has a packaging problem that affects its use in node application. It should work for web use, but you should not use it for in node. We are preparing a beta.6 release that should resolve the issues.

MathJax v4.0.0-beta.4

This is mainly a bug-fix release to resolve some errors reported with the recent beta.3 release. A summary of some of the most significant fixes are below, followed by a categorized list of the fixes with links to the original issues that reported them, and to the pull requests that fixed the problem. See those links for additional details on those issue.

Change Summary

• The move to ESM modules and compiling to ES6 rather than ES5 lead to an issue with the webpacked versions of some component files that would cause errors when they are loaded. This has been resolved in this release. The source of the problem was due to the use of a custom Symbol class in MathJax's TeX input jax that conflicts with the native javascript Symbol object. This was not an issue in previous versions of MathJax, but due to differences between how webpack handles CommonJS and ESM modules, it now causes problems with some TeX extension packages that use the Symbol class. This has lead us to rename the custom Symbol class to Token, and rename the Symbol.ts and SymbolMap.ts files to Token.ts and TokenMap.ts. This is a potential breaking change to those who have created their own TeX extension packages that load one of these files.

• There was an issue in v3 where MathJax would throw an error setting getter-only property "Package" during its configuration processing (particularly when there was no explicit MathJax configuration in the page), and the move to ESM modules exacerbated that problem. The issue has been resolved here.

• The beta.3 version had an error where the equation, equation*, displaymath, and math LaTeX environments would produce an error about incorrectly nested environments, regardless of their content. That has been fixed.

• The \text{} macro would produce an error message when the textmacros package is used in beta.3. This has been resolved.

• Inline line breaks could occur in incorrect locations, sometimes producing blank lines the shouldn't be there. These extraneous breakpoints have been removed, so line breaking should work better for in-line mathematics.

• The TeX input jax now attaches data-latex attributes to the MathML elements that it produces, indicating the TeX command from which the element originated. This information can be used by the assistive tools to produce Braille output of the original LaTeX, for example. Since data attributes are transferred to the CHTML and SVG output nodes, this information is available in MathJax's output in the page, not just the internal MathML notation.

• Because the MathML specification indicates that any mtext element is "space-like", and since an operator in an mrow whose only other elements are space-like is considered to be an "embellished operator" that should be treated as an unbreakable unit, this can lead to unexpected results. When the operator is used for line breaking, the line break must occur before or after the embellished operator as a whole. That is, {\text{A} + \text{B}} produces <mrow><mtext>A</mtext><mo>+</mo><mtext>B</mtext></mrow>, making the <mo>+</mo> an embellished operator; if a linebreak is to occur at this +, it will be done before the A or after the B, not at the + itself. This is not what is usually intended for this LaTeX expression. Although the MathML specification is not clear about why mtext elements are space-like, it is likely because these are sometimes used to insert explicit spaces into the expression via space characters, but any mtext is considered space-like regardless of its content, leading to awkward situations like the one described above.

  In this release, MathJax has parted from the specification in making an mtext element be space-like only if its contents consists only of space characters or is empty and it doesn't have a mathbackground or style attribute. Similarly, an mspace element is considered space-like only if it does not have an explicit linebreak, height, depth, mathbackground or style attribute. With these changes, TeX expressions will not generate unexpected embellished operators that will affect their line breaking.

---

The categorized list of changes are in the subsections below:

TeX Input Fixes

• Use proper spacing for initial relations in right-aligned columns of alignment tables. (mathjax/MathJax#3089) (#996)

• Make sure \operatorname keeps TeX class OP after enrichment. (mathjax/MathJax#3084) (#989)

• Remove incorrect frame from multline environment. (mathjax/MathJax#3083) (#988)

• Fix bug with \text{} when textmacros package is used. (mathjax/MathJax#3082) (#983)

• Fix error message with \vdotswithin{} from the mathtools package when it is used outside of a table. (mathjax/MathJax#3078) (#981)

• Fix incorrect flagging of nested environments. (mathjax/MathJax#3070) (#975)

Output Fixes

• Don't include extra line-break positions after an explicit break. (#1003)

• Propery handle placement of scripts on \vcenter, \vbox, and \vtop. (mathjax/MathJax#3091) (#1000)

• Fix spacing before \vcenter, \vtop, \vbox. (mathjax/MathJax#3085) (#990)

• Fix placement of super- and subscripts when superscript has large depth. (mathjax/MathJax#3097) (#999)

• Remove errant mjx-linestrut from SVG output. (mathjax/MathJax#3087) (#991)

Miscellaneous

• Include default font configuration so that it will be loaded when input/chtml or input/svg is loaded in node-main. (#992)

• Update check for spacelike MathML nodes to be more sensible. (mathjax/MathJax#3098) (#1002)

• Prevent setting a property that has a getter during configuration processing. (mathjax/MathJax#3098) (#1001)

• Set TeX class OP for multi-letter mo elements, as in v2. (mathjax/MathJax#3095) (#998)

• Improve build tools for use with third-party extensions. (mathjax/MathJax#3086) (#997)

• Prevent file system paths from being included in extensions and bundles. (#993)

• Remove install script from package.json that is only needed for development. (#985)

• Change Symbol to Token to avoid conflict with native Symbol in webpacked files. (mathjax/MathJax#3072) (#982)

New Features

• Add support for *{n}{...} in array environment preamble. (mathjax/MathJax#3090) (#995)

• Add data-latex attributes to MathML nodes from TeX input jax. (#986)

• Add LaTeX Braille support to assistive tools. (#1004)

MathJax v4.0.0-beta.3

This release fixes a problem with determining the path used by MathJax in the webpacked node-main.js file, which is what is loaded when you require("mathjax-full") or import "mathjax-full". In addition, the commit that is tagged 4.0.0-beta.2 corresponding to the beta.2 release had the version number incorrectly set to 4.0.0-beta.1 in the MathJax object, though the npm package had it set correctly.

See the 4.0.0-beta.2 release notes for details about the changes in the v4.0-beta release, but (of course) use 4.0.0-beta.3 in place of 4.0.0-beta.2 in the URLs for accessing this version.

MathJax v4.0.0-beta.2

This is the second preliminary release of version 4, which we hope to be the last beta release before the official version becomes available. We include fixes for a number of issues reported with the alpha release, and add several new features and improvements as well. A significant one is that we now provide the MathJax JavaScript files as both ES modules as well as the older CommonJS format that we have been using in the past, and these newer ES modules are compiled into ES6 rather than the older ES5 used in earlier versions. This is discussed more fully below. There is a lot of information here, but you can use the links below to jump to the points that interest you.

---

• Major New Features
  • ES6 modules
  • Improvements to Line Breaking
  • Improvements to Assistive Support
  • New TeX Features
  • New Output Features
  • User-Interface Updates
  • API Changes
  • Changes to the Build Tools
• Updates and Resolved Issues
  • TeX Updates
  • MathML Updates
  • Output Updates
  • User Interface Updates
  • API Updates
• Availabilty of v4.0.0-beta

---

New Features

This beta version of MathJax introduces the following significant new features in addition to those from the v4 alpha release.

ES6 Modules

When MathJax was first released, the current version of JavaScript was ES5, so when the code base was moved to Typescript for v3, it was down-compiled to produce ES5 code. Modern browsers support ES6, which include many new features, such as true object class creation and inheritance, proper import and export commands, Set and Map objects, promises, iterators, and many other features that make JavaScript programs faster and more reliable.

Along with new language features, ES6 introduced a new module structure that affects how individual javascript files obtain values from other files, and how they make their own definitions available to others. ES6 modules (which we will refer to as "MJS") use the new import and export commands to do this, while the older CommonJS module format (which we will call "CJS") used require() and the module.exports object to perform those functions.

MathJax v3 uses CommonJS modules with ES5 code (though this was not quite pure ES5, since one of its dependencies was actually ES6), but modern JavaScript applications are moving more and more to MJS format. Beginning with this beta version of v4, MathJax offers both MJS and CJS versions, with the MJS version being ES6, but the CJS version remaining ES5, as in past versions. The webpacked components for use in web pages are now based on the MJS versions.

Implications for MathJax in Web Pages

The webpacked MJS files are smaller than the earlier webpacked CJS files, so that should mean faster download and compile times, and the ES6 code is more efficient, so should run faster. But since this version is no longer ES5, the es5 directory that was part of the URLs for accessing MathJax from a CDN is no longer correct. The details of how the directories have been adjusted are given in the next section, but for use on the web, the only important difference introduced by the change to ES6 is that you simply remove the /es5 from the url. For example, you would use

https://cdn.jsdelivr.net/npm/mathjax@4.0.0-beta.2/tex-mml-chtml.js

to load the tex-mml-chtml.js combined component.

Support for IE11 has been dropped with this version, as it does not support enough of the ES6 standards. (It is possible to webpack the CJS versions, so you can build your own ES5 version if that is necessary for you. This is described at the end of this section below.) In version 3, we recommended a link to polyfill.io in order to support IE11. This can now be removed since this version will not work with IE11 even with the polyfill.

If your only usage is in a web browser, you can skip to the section on line breaking.

New Directory Structure

MathJax's new dual distribution of both MJS and CJS modules requires a new directory structure in the mathjax/MathJax-src repository and its associated mathjax-full npm package in order to accommodate both versions. In the past, the compiled JavaScript code was found in the js directory, and the webpacked components were in the es5 directory. Now that there are both CommonJS and ES-module versions of the compiled code, these are stored in the cjs and mjs directories, respectively.

The webpacked components are now based on the new mjs files, hence they are ES6 files, and so the es5 directory has been removed, with the components now being placed in the new generically named bundle directory. That way, if there is a move to ES7 or higher, the directory name doesn't need to change again. The mathjax/MathJax repository and associated mathjax package have also eliminated the es5 directory, and the combined components and component directories are now at the top level of the repository. That means you can access them without the need for /es5 in the URL that was needed in v3. (See the Availability section below for more information on how to access v4.0.0-beta.2 in a browser.)

Existing node applications that use MathJax may have code that refers to mathjax-full/js (e.g., the examples in the MathJax-demos-node repository), and mathjax-full/es5 or mathjax/es5 directories, which no longer exist. To accommodate these, this beta release includes an exports section in its package.json file that maps these references to the proper new locations. In particular, references to mathjax-full/es5 are routed to mathjax-full/bundle automatically, and similarly, mathjax/es5 is routed to mathjax. For the mathjax-full/js directory, references will be routed to mathjax-full/mjs or mathjax-full/cjs depending on whether the reference is from an import statement or a require() call. That means that ES modules (using import) will get the mjs versions, while CommonJS modules (using require()) will get the cjs ones, and so you can continue to use mathjax-full/js, mathjax-full/es5 and mathjax/es5 as you have in the past.

The main package.json file now includes a "type": "module" line so that the .js files are considered to be MJS files automatically. The cjs directory (and other directories that need to be marked as CJS files), contain separate package.json files that set the type to commonjs so that the .js files they contain will be treated as CJS files.

Similar changes have been made to the font directories in the font packages. In particular, there are mjs and cjs directories, and the es5 directory has been removed. The bundled files for the fonts are now in the top-level directory, as they are in the mathjax npm package.

Changes to components/src

The files that are used to create the webpacked component files are ES6 modules, since they use import and export, and in previous versions of MathJax, you needed to use node -r esm to be able to require() these in your own programs (you can't use require() to load ES modules directly). Although you could load the webpacked versions of the component files in either MJS or CJS applications, the fact that the source component files are MJS modules made it difficult to use the source versions of the components in CJS applications.

Now that MathJax provides both MJS and CJS versions, we wanted to allow the source component files to be available in both forms as well. Originally, the component files were found in components/src; with this beta version, those are now in components/mjs, since they are ES modules.

Prior to this version, MathJax used Babel to convert these to ES5 during the webpack process, but since the webpacked versions are now ES6, that is no longer necessary, and Babel is no longer needed as a dependency for MathJax. Instead, for those who wish to use the components from source in a CommonJS node application, we use Typescript to down-compile the components/mjs files into the components/cjs directory as CJS modules of ES5 code.

In previous versions, require('mathjax-full') would load components/src/node-main/node-main.js, which would load the components from source rather than the webpacked versions. With the mathjax package, which only includes the webpacked versions, require('mathjax') would get es5/node-main.js, the webpacked version. In this beta version, the two have been standardized so that they both load the webpacked version. When used with require(), you will get bundle/node-main.cjs, while import will load bundle/node-main.mjs. This is accomplished via the exports section of the package.json file.

In order to get the source versions in mathjax-full, use require('mathjax-full/source').init(...) or import {init} from 'mathjax-full/source' and then call init(...). These load components/mjs/node-main/node-main.mjs or components/cjs/node-main/node-main.cjs, respectively.

For those who have been using components/src to load individual components from source, we map components/src to components/mjs when included via an import command, and to components/cjs when included via require().

The end result is that you should always get an appropriate version for your situation, whether you are importing MathJax into an MJS application or requiring it into...

MathJax v4.0.0-beta.1

This release has been deprecated due to an error in the package.json file. Please use 4.0.0-beta.2

MathJax v4.0.0-alpha.1

This is the first alpha release of a major update to MathJax, adding a number of new features and enhancements. As this includes significant changes that involve potentially breaking changes, in order to not have these changes affect existing web sites, this release increments the major version number so that sites using the mathjax@3 URLs will be protected from these changes until they update to version 4 explicitly. That is, this new release is an opt-in update.

---

• Major New Features
  • Extended Font Support
  • Line-breaking Support
    • Display breaking
    • In-line breaking
    • New TeX preamble options
    • Line-breaking macros in TeX
    • Options for <mpadded> elements
  • Support for HTML in MathML and TeX
    • HTML in MathML
    • HTML in TeX
    • Specifying the size of the HTML
  • Expression Explorer Included in Combined Configurations
• MathJax v4.0 and Promises
• Availability of v4.0.0-alpha

---

Major New Features

Version 4 of MathJax introduces the following significant new features. It also fixes some outstanding bugs, adds some new TeX macros, and improves support for some others.

Extended Font Support

This version includes support for a number of new font sets for MathJax, and changes the default font to one based on the Latin-Modern fonts; it offers support for a much larger range of characters than MathJax's original TeX font set, but is consistent with the look-and-feel of the original MathJax TeX fonts. The new set is slightly lighter, so will not seem so bold and will fit in better on Windows machines, without losing too much on linux, Mac OS, and iOS displays. The original MathJax TeX font set is also available as an option, for those who are unwilling to part with it.

There are 11 fonts available for MathJax v4:

Font Name	Original Source
mathjax-modern	A version of Latin-Modern (the new default font in MathJax)
mathjax-asana	A version of the Asana-Math font
mathjax-bonum	A version of the Gyre Bonum font
mathjax-dejavu	A version of the Gyre DejaVu font
mathjax-pagella	A version of the Gyre Pagella font
mathjax-schola	A version of the Gyre Schola font
mathjax-termes	A version of the Gyre Termes font
mathjax-stix2	A version of the STIX2 font
mathjax-fira	A version of the Fira and Fira-Math fonts
mathjax-euler	A version of the Neo Euler font as an extension to mathjax-modern
mathjax-tex	The original MathJax TeX font

You can specify the font you want to use by setting the font option in the new output block of your MathJax configuration (where options common to both output renders can be placed). For example,

MathJax = {
  output: {
    font: 'mathjax-stix2'
  }
};

will select the mathjax-stix2 font. For in-browser use, this will obtain the font and its data from cdn.jsdelivr.net and no other configuration is necessary. For node applications, first install the font via

npm install mathjax-stix2-font

(add -font to the name of whichever font you want and install that); MathJax should find the font in your node_modules folder. It is also possible to configure the path to the fonts using the fontPath option of the output block. This should be set to a string that indicates where the font can be found; that string should include %%FONT%% in any part of the path where the font name needs to appear. For example,

MathJax = {
  output: {
    fontPath: './node_modules/%%FONT%%-font/es5/output/fonts/%%FONT%%'
  }
};

is the default path in node applications.

It is also possible to specify an explicit URL as the font name in the configuration:

MathJax = {
  output: {
     font: 'https://cdn.jsdelivr.net/npm/mathjax-stix2-font/es5/output/fonts/mathjax-stix2'
  }
};

For those who wish to use the original MathJax font as it appears in version 3, specify the font as mathjax-tex.

The combined component files, like tex-chtml.js and mml-svg.js, include the new mathjax-modern font as part of the component so that only one file needs to be downloaded. But if you want to use a different font, you probably don't want to download mathjax-modern first and then the font you actually want to use. Instead, you should use a component ending in -nofont.js, for example, tex-chtml-nofont.js, so that the initial download is smaller, as it doesn't include mathjax-modern. See the section on MathJax v4.0 and Promises for more details concerning the proper handling of typesetting with the new fonts.

The tools for building the data needed by MathJax for your own font will be made available after version 4 is officially released. They were used to create these new fonts, but are not yet ready for public release, as they need cleaning up and documentation. But in the future, you will be able to generate an extension to an existing font (for example, to replace the letters and numbers with a different font while leaving all the rest of the characters unchanged), or a completely new font. So look for that functionality in the future.

Line-breaking Support

Version 4 includes the long-awaited support for automatic and explicit line breaking of math expressions. The support in v4 is an improvement over that in v2 in a number of ways. In particular, version 4 includes the option of breaking in-line expressions so that long expressions near the end of a line will automatically break and wrap to the next line. This is accomplished by allowing the browser to break the expressions where it needs to (following TeX's rules for what constitutes a valid in-line breakpoint). For display equations, version 4 provides support not only for automatic line breaking, but also for several other options for handling wide equations, including scaling the equation (to fit the container size), and scrolling if it is too wide. The page author can set the default, but there is also a new menu item where the viewer can switch the overflow handling to match their preferences. Version 4 also implements line-breaking of <mtext> elements (which are created by \text{} and other text-mode macros) , so long textual material can be broken automatically; this was not possible in version 2.

As part of the line-breaking support, a number of new TeX macros have been made available to control line breaks (to make them more or less desirable, or force or prevent them entirely). Also, support has been added for additional array environment template patterns that can be used to control the width of and automatic line breaking within table cells, as well as insert text before or after every cell in a column, or adjust the spacing between columns. New macros for creating boxes of specific widths in which line breaking will occur are also available, and there are options for controlling justification and indentation of the text. Such boxes are also available in MathML via additional options for the mpadded element.

Finally, version 4 now attempts to break cells within tables based on the size of table as a whole (whereas v2 broke cells only if they individually were too wide for the container, and broke them to the container width regardless of the size of the rest of the table).

Display breaking

The algorithm used in version 4 for breaking displayed equations is based on the one from version 2, but is not identical to it. Unlike version 2, the results should be nearly identical between the CHTML and SVG output renders, and the code is set up so that the algorithm can be updated or even replaced much easier than in v2. We do have plans for improvements that we hope to make in the future.

The page author can control how long expressions are handled using the new displayOverflow output jax configuration option, which can be set to overflow, scale, scroll, truncate, linebreak, or elide, though the latter is not yet implemented. The reader can override that default using the MathJax contextual menu, which has a new item in the "Math Settings" submenu for handling "Wide Expressions". For MathML input, MathJax version 4 now honors the overflow attribute of the math element, so you can mark a single long expression for line breaking, or for scrolling, for example.

Note that there is now a new output configuration block that can be used to provide options that are common to both CHTML and SVG output, so that you may have set for your default output jax will stay in effect when the user changes renderers via the contextual menu.

When displayOverflow is set to linebreak, the breaking is controlled by the settings in the linebreaks sub-block of the output (or chtml or svg) block. The default settings are

    linebreaks: {                  // options for when overflow is linebreak
      inline: true,                   // true for browser-based breaking of inline equations
      width: '100%',                  // a fixed size or a percentage of the container width
      lineleading: .2,                // the default lineleading in em units
      LinebreakVisitor: null,         // The LinebreakVisitor to use
    },

The last option is used to replace the line-breaking algorithm with a new one, so is a developer option, but the others are author-level settings that control things like how wide the lines are allowed to be, and how much extra space to put between li...

MathJax v3.2.2

This is a hot-fix release to correct three issues in the recent 3.2.1 release. These are listed below:

• Prevent lazy typesetting from re-typeset expressions unnecessarily, which can cause duplicate-label error messages in the output, and degrade performance. (mathjax/MathJax#2873)

• Improve method for obtaining the <math> element from mml3 conversion, allowing it to work better in an XHTML setting. (mathjax/MathJax#2879)

• Make version.ts use a constant and create the file during the build process rather than dynamically determining the version. This allows easier packaging of MathJax into other applications. (#824)

MathJax v3.2.1

This is mostly a bug-fix release, resolving various display and input bugs and other issues. See the individual bugs linked below for more details, and the 3.2.1 milestone for the pull requests involved in this release.

---

New Features in this Release

Speech-Rule Engine

MathJax now integrates version 4 of Speech Rule Engine (SRE). (#800)

• SRE v4 is a full port to ES6 using TypeScript providing transpiled JavaScript for easier integration into third party projects via its npm package.
• Uses webpack as the primary bundler to offer a single bundle file for both node and browser.
• Major rewrite of rule handling and provision of locales.
  • Smaller locale files and memory footprint in the index structure.
  • Hierarchical locale setup that allows inheritance within rule sets.
  • Uses ES6 promises to handle locale loading and engine setup.
• A number of new locales for Swedish, Norwegian (Bokmal and Nynorks), Danish (MathSpeak only), and Catalan (MathSpeak only)
• Locale files are now served with a .json extension. (mathjax/MathJax#2403)

For more details and a full list of all changes and additions see the SRE release notes.

MathJax makes use of SRE v4 new features in the following ways:

• Source integration
  • Integrates SRE directly via importing the relevant library files into its code and webpacks them into its components and bundles.
  • Replaces the timeout-driven SRE loading promise with SRE's new native promises.
  • The sre.ts module now imports and exports exclusively API methods necessary for SRE's use in MathJax
  • A new mathmaps.ts module provides a map for directly integrating and bundling locales (see more below).
• Components integration
  • The sre component under components/src/sre now simply handles copying the locale files in the mathmaps directory.
  • The a11y/sre component under components/src/sre contains a configuration file sre_config.js that sets up the basic SRE configuration for MathJax, especially the correct path to the mathmaps folder (online or in the npm distribution).
  • Components can webpack SRE's locale files into bundles. See the components/src/tex-chtml-full-speech component as an example.
• MathJax Configuration
  • The sre path in MathJax is now used exclusively for pointing to a directory containing the locale files.

Most of these changes are internal and should remain unnoticeable. However, there are a couple of points to note when using SRE via MathJax:

• Previously, MathJax would load SRE as a single library file, but now webpacks its source files, which, as a side-effect, closes several convenient loopholes you could have exploited in the past:
  • OLD: SRE's functionality was available to a developer as if running SRE standalone. That is, in both node and browser, all of SRE's API methods where available in the SRE namespace, and additionally, the full functionality was reachable in the browser through the sre namespace.
    NEW: Now only the explicitly exported API methods are available to import via the a11y/sre component.
    * OLD: You could easily change the version of SRE MathJax would use by:
    1. In the browser, pointing to an alternative copy of sre_browser.js using the sre path in the MathJax configuration, and
    2. In node, replacing the speech-rule-engine package with a different version in the node_modules folder.
       NEW: This is no longer possible.
• The sreReady method is still exported but deprecated. In the future, you should use the corresponding method in the API bundle Sre.sreReady().
• By default SRE comes without rules (or locales) preloaded, and pulls those in only when necessary. That is, it loads the relevant .json files via XML-HTTP-request in the browser, or via file loading in the node module. However, it is now possible to pre-bundle (some) locales directly into a custom distribution using webpack, which is particularly useful if you want to run MathJax offline while still using the full power of is assistive technology extension. See the tex-chtml-full-speech component as an example.

Output Improvements

• Properly handle border and padding CSS in CHTML and SVG output. (#799)

Lazy Typesetting

• Have lazy typesetter typeset all remaining math before printing. (#777)
• Have lazy typesetting specify a (configurable) distance around the viewport for triggering typesetting. (#777)
• Allow containers to be marked so that they are always typeset by the lazy typesetter. (#777)

---

Bugs Addressed in this Release

Output Bug Fixes

• Update svg output to properly handle token elements with multiple child nodes. (mathjax/MathJax#2836)

• Include CSS to reset border-collapse in CHTML output. (mathjax/MathJax#2861)

• Prevent CHTML adaptive CSS from adding character CSS multiple times. (#796)

• Make sure all character data is included when adaptiveCSS is false. (mathjax/MathJax#2724)

• Place super- and subscripts properly around \vcenter elements. (#787)

• Add a minimum height for accented characters. (mathjax/MathJax#2766)

• Take relative scaling into account for CHTML output of non-MathJax fonts. (mathjax/MathJax#2818)

• Fix placement of surd when root extends above the top of the root. (mathjax/MathJax#2764)

• Fix problem with msubsup when subscript is blank (mathjax/MathJax#2765)

TeX Input Fixes

• Add \textup and \textnormal to macros allowed by textmacros. (mathjax/MathJax#2846)

• Update \operatorname to work more like in LaTeX. (mathjax/MathJax#2830)

• Have physics package match nested parentheses, fix spacing issues. (mathjax/MathJax#2760, mathjax/MathJax#2831)

• Re-implement \sideset using mmultiscripts. (mathjax/MathJax#1217)

• Fix problem where errors during mhchem argument collection are not properly handled. (mathjax/MathJax#2835)

• Update XSLT to produce better results in mml3 extension. (#785)

• Add ability for TeX input to force normal variant for CJK input. (mathjax/MathJax#2744)

• Make sure math-in-text forms an ORD atom within textmacros. (mathjax/MathJax#2828)

• Make sure explicit attributes added by \mmlToken are not removed. (mathjax/MathJax#2806)

• Fix typo in \DeclarePairedDelimiter macros, and substitute arguments in pre and post sections. (mathjax/MathJax#2816, mathjax/MathJax#2758)

• Mark mo as not an accent if used in \overset and friends. (mathjax/MathJax#2800)

MathML Input Fixes

• Fix problems with verification and repair of malformed mtables. (#779)

• Add support for mglyph use of fontfamily/index. (mathjax/MathJax#2298)

• Trim MathML string before parsing it. (mathjax/MathJax#2805)

• Only process MJX-TeXAtom classes on mrow elements. (mathjax/MathJax#2822)

• Move mml3 filter to an mmlFilter so that forceReparse isn't needed. (mathjax/MathJax#2718)

• Make U+2061 through U+2064 have TeX class NONE so they don't affect spacing. (#806)

Miscenaleous

• Handle documents better when created by parsing in XHTML. (mathjax/MathJax#2788)

• Add version numbers to component files and check them when loaded. (#738)

• Fix problem where some menu settings weren't sticky (mathjax/MathJax#2786)

• Add a linkedom adaptor (mathjax/MathJax#2833)

• Refactor usage of all-packages to reduce redundant code in components. (#784)

• Make variables local in legacy AsciiMath code. (mathjax/MathJax#2748)

• Make safe extension properly handle scriptlevel of 0. (mathjax/MathJax#2745)

• Update webpack files for empheq and cases. (mathjax/MathJax#2762)

• Update build tools to work with extensions better. (#737)

• Add defaultPageReady() to MathJaxObject interface. (#746)

MathJax v3.2.0

This release includes a number of new features, along with several bug fixes. The new features include a lazy-typesetting extension, better handling of adaptive CSS in the CommonHTML output, several new TeX extensions, a port of the MML3 extension from v2, and the addition of the Hindi language to the speech generation. These are described more fully below.

There are several several potentially breaking changes in this release. See the second section below for more details.

Finally, a number of bug fixes are also included in this release, as described in the last section below.

---

• New Features

  • Lazy Typesetting
  • CSS Updates
  • New TeX Packages
  • MathML Extensions
  • Explorer Update
  • Other New Features

• Breaking Changes

• Bug Fixes

  • Output Bug Fixes
  • Input Bug Fixes
  • Miscellaneous

---

New Features in this Release

Lazy Typesetting

Although MathJax version 3 is already an order of magnitude faster than version 2, with version 3.2 we offer a new extension that is designed to make pages with large numbers of equations perform even better. It implements a "lazy typesetting" approach that only typesets an expression when it comes into view, which means that expressions will not be typeset when they are not visible. Your readers will not have to wait for the entire document to typeset, which can speed up their initial view of the page. Furthermore, any expressions that are never seen will not be typeset. This also helps with the situation where you may link to a particular location in your page (via a URL with a hash); in version 2, typesetting the material above that point can cause the browser to change the scroll position, and so the user may not end up at the proper location in the page. With the lazy extension, the material above that point is not typeset until the user scrolls upwards, and so there is no position change.

Lazy typesetting works best with SVG output, but changes (discussed below) with the way the CommonHTML output handles its stylesheet updates make the CHTML output nearly as fast. With TeX input, the lazy extension makes sure that previous expressions are processed by TeX (though not output to the page) so that any macro definitions or automatic equation numbers are in place when the visible expressions are processed. Currently, documents that contain \ref or \eqref links may not yet work properly, since target equations may not have been typeset, and so the link location may not be marked in the document. In particular, forward references are unlikely to work, and backward references will work only if the target expression has already been typeset. We hope to improve this situation in a future release.

See the lazy extension documentation for information on how to configure MathJax to use this new feature.

CSS Updates

MathJax's CHTML output handles the characters that appear in the math on the page by storing information about their bounding boxes and text content in a CSS stylesheet. When additional math is typeset, this stylesheet may need to be updated, and in previous versions, MathJax would replace the entire stylesheet with a new one. This can cause visual flashing, and can be expensive as the browser must re-evaluate all the rules and apply them again. In version 3.2, the CHTML output now adds rules to the stylesheet individually, so the older rules are not replaced, and only the new rules must be evaluated and applied. This makes updates must faster, and is of particular benefit to the lazy-typesetting extension described above, as the page can be updated many times as equations scroll into view. This change makes the CHTML output work almost as smoothly as SVG output with the lazy extension.

New TeX Packages

Version 3.2 includes nine new TeX extension packages:

• cases — provides environments for individually numbered cases.
• centernot — implements a centered \not command (and a non-standard \centerOver that places one symbol centered on top of another).
• colortbl — provides macros for coloring cells of an array or alignment.
• empheq — an environment for placing material to the left or right of an alignment that has individual equation numbers.
• gensymb — provides macros for some specific units.
• mathtools — offers a range of macros and environments for advanced mathematical typesetting.
• setoptions — provides the ability to change some TeX input jax options from within an expression (e.g., to change the tag side).
• textcomp — provides a range of macros for specifying various text characters.
• upgreek — provides macros for upright Greek characters.

These are all included in the components that end in -full (and include the TeX input jax), and you can load individual ones as you would other tex packages. Note, however, that none of these are autoloaded, though you can configure the autoload extension to do so, if you wish. See the autoload documentation for details.

In addition to these new packages, some of the older packages have been updated:

• The ams package now includes flalign, xalign, and xxalign environments. In addition, the multline extension has been made more compatible with actual LaTeX. In the past, multline was set to be 85% of the container width, but now it is set to 100%, but with a 1em indent on both sides; when there is a tag, the indent on the tag side is increased by the width of the tag, as is the case in LaTeX. The width was stored in the multlineWidth configuration option in the tex configuration block. That has now been moved to the ams block in the tex configuration, and there is a new multlineIndent value. These are set to 100% and 1em respectively. To obtain the old behavior, set them to 85% and 0. Currently, if multlineWidth is found in the main tex option block, it will be moved to the ams block, but that backward-compatibility code will be removed in a future release.

• The physics package now implements all macros, even those that are not officially documented, but are nevertheless available in LaTeX. In addition, it now implements the italicdiff and arrowdel options.

• The following macros have been added to the indicated package:

  • \overunderset (ams) — a combination of \overset and \underset.
  • \stackbin (ams) — similar to \stackrel but produces a symbol with the spacing of a binary operator.
  • \nonscript (base) — apply the following spacing only when in display and text styles.
  • \boxed (base) — puts a frame around an expression.
  • \framebox (base) — puts a frame around a text argument.
  • \ip, \Bqty, \qsince, \Residue (physics) — originally missing from the physics package.

MathML Extensions

The MML3 extension from version 2 has been ported to version 3 and is available to be included when you load the MathML input jax. This extension implements the MathML3 elementary math tags (like <mstack> and <mlongdiv>) using an XSLT transform to convert these tags into other presentation MathML tags that MathJax has implemented. This does a reasonable job for some constructs, and a poorer job for others, but it does make it possible to process elementary math within MathJax v3. This is an experimental extension as a stop-gap measure until these tags are fully implemented within core MathJax.

See the mml3 extension documentation for information on how to configure MathJax to use this new feature.

Explorer Update

The Speech-Rule Engine (SRE) that underlies MathJax's assistive technology support has been updated to the most recent version (3.3.3). This includes support for the Hindi language, so that the expression explorer can generate speech in Hindi (as well as its other languages: English, French, German, Italian, Spanish, together with Braille support in Nemeth).

See the SRE release notes for details.

This release also ports the remaining missing features for the explorer to v3. This includes summarising expressions and navigation of tabular expressions, like matrices or equation systems. See the explorer keyboard commands for details.

Other New Features

In addition to the major features listed above, there are some minor new features as well:

• Packages can now be specified for the textmacros extension to the TeX input jax. This allows you to configure additional macros that can be processed within text mode. See the textmacros documentation for details.

• Processing of raw Unicode character...