MathJax source code for version 3 and beyond
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.
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.
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).
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.
npm to pnpmWith 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:
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)
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)
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)
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)
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.
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.
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:
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)
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)
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)
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)
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.
This release has been deprecated due to an error in the package.json file. Please use 4.0.0-beta.2
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.
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.
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.
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).
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 lines.
In version 4, in-line expressions can be allowed to break automatically by the browser. This is controlled via the inline option of the linebreaks block described above. When true (the default), MathJax will arrange for in-line expressions to be broken into pieces so that the browser can move parts of the equation onto the next line, if they would otherwise extend beyond the width of the expression's container. (In version 2, in-line expressions are only broken when the expression by itself would be wider than the container, and in that case, the expression would essentially act like it was inside a <div> element, so it badly disrupts the flow of the paragraph, and could cause misleading wrapping of text around the broken expression).
Note, however, that in order to do this, MathJax must make several separate elements containing math, and for SVG output in particular, several separate top-level <svg> elements. For this reason, node applications that are trying to create single svg images for the mathematics would want to set linebreaks.inline to false to avoid that.
Finally, because the browser is doing the actual determination of the locations for in-line breaks, these breaks are chosen purely by how much of the expression can fit at the end of the line before the break. That is, the parameters that mark breakpoints as good or bad (described below) are not taken into effect; however, forced breaks and no-break markers are respected.
To help support line breaking within cells of wide tables, MathJax v4 includes support for the preamble column declarations defined in the array TeX package. These include the traditional c, l, and r for alignment of the contents of the cell (centered, left, or right), but adds support for p{width}, m{width}, and b{width} for vertical alignment of a fixed-width column in which line-breaking will occur at the given width, as well as w{align}{width} and W{align}{width}. There is also new support for >{...} and <{...} for adding content that is put before or after every entry in a column, as well as @{...} for replacing the inter-column space with the given content, and !{...} for replacing inter-column rules. Support for | and the non-standard : are improved so multiple copies of | and : now produce multiple rules that are close together. Finally, non-standard P{...}, M{...}, and B{...} are defined that produce math-mode versions of their corresponding lower-case counterparts. The \newcolumntype macro for declaring new column specifications is also available.
Note that for p, m, b, w, W, P, M, and B columns, line-breaking will occur to the given column with if line-breaking is the active overflow setting. Otherwise, wide content will overflow the width, as in actual LaTeX.
In MathML, <mo> and <mspace> items can be marked as either good or bad breakpoint options via the linebreak="goodbreak" or linebreak="badbreak" options, or linebreaks can be prevented via linebreak="nobreak" or forced with linebreak="newline". In TeX, these can be controlled via the \goodbreak, \badbreak, \nobreak, and \break (or \\) macros. These will try to mark the operator that follows (or in some case precedes) the macro using the appropriate linebreak attribute. If there is no operator, then one will be introduced into the expression at that location. There is also \allowbreak that inserts a breakpoint that can be used if one is needed.
The \parbox[align]{width}{text} macro has been added in v4 to provide a line-breaking context of a given width and vertical alignment (t, b, c for top, bottom, center (the default), with m allowed as an alias for c) for text-mode material. Previous versions of MathJax include \vcenter{} for vertical centering, and v4 adds \vtop{} and \vbox{} for material to be aligned on the top line or bottom line of the contents. In LaTeX, their content is text-mode, but in MathJax, they are in math mode (since MathJax mainly does math-mode, and for backward compatibility with the original \vcenter{} implementation). The width of these boxes can be controlled using \hsize=<dimen> within the box, so \vtop{\hsize=10em ...} would make a box that is 10em wide whose content is line broken and aligned on the baseline of the first line. Finally, the \makebox[width][align]{text} macro can also be used to produce a line-breaking text box of a given width and vertical alignment. (This complements the \mathmakebox[width][align]{math} macro already in the mathtools package.)
While the new array preamble options allow you to control the cell widths in an array, they aren't available for other environments, like align. When line-breaking is enabled, you may want to have more control over how long lines of an alignment are broken. You can use \hbox or \mbox to avoid line breaks, but when you do allow breaks, you may want more control over indenting and alignment in such settings. For this reason, MathJax v4 introduces a non-standard indentalign environment that can be used within a cell of a table (or in any line-breaking context) to adjust the indentation amount and the horizontal alignment of any wrapped lines:
\begin{indentalign}[first][middle][last]{align}
(long line of math)
\end{indentalign}
where first, middle, and last are optional dimensions that specify how much indentation to use for the first, middle, and last lines (where middle is any but the first or last lines). If only first and middle are provided, last will be the same as middle, and if only first is given, all three will use the same value. The align argument is one to three letters, each being one of l, c, or r, and these represent the alignments for the first, middle, and last lines. So
\begin{indentalign}[0em][1em]{l}
(long line of math)
\end{indentalign}
would left align all lines, and indent the second and subsequent lines by 1em, when used in a context where line-breaking is in effect.
<mpadded> elementsThe various line-breaking boxes described above are implemented via the MathML <mpadded> element. In order to facility that, MathJax v4 adds two non-standard attributes to the mpadded element: data-overflow and data-align. When data-overflow="linebreak" is used, the contents performs line-breaking to the width specified in the element's width attribute. (No other value for data-linebreak is implemented). The data-align attribute value can be left, center or right, to get the contents (line-broken or not) aligned to the left, center, or right of the specified width. You can use an <mstyle> element within the <mpadded> element in order to set the indentshift, indentalign, and similar attributes (for first and last lines) of the content, or can specify those attributes on the individual <mo> or <mspace> elements within the <mpadded> container.
The HTML5 specification allows for mixing HTML nodes inside MathML token nodes, and it is a long-standing request for MathJax to implement that as well. Version 4 finally does so. You can now use HTML nodes as children of token nodes, such as <mtext>. Thus
<mtext>a button <input type="button" value="Push Me"> to press</mtext>
is allowed, and would produce an <mtext> element containing a button surrounded by some plain text.
Because the HTML is not currently sanitized (something that could be added to the safe extension), allowing HTML in token elements would be a security issue for sites that allow user-entered MathML. For this reason, the MathML input jax has a new option allowHtmlInTokenNodes to control whether to allow it, and it is false by default, so you have to opt into this new feature if you want to use it on your site.
HTML is now allowed in TeX and LaTeX input as well. This is handled through the special <tex-html> node, which (unlike most HTML nodes) can be included within the math delimiters. So, for example
$$3 + <tex-html><input type="text" id="answer" size="10"></tex-html> = 10$$
would present an expression with an input box where a student could fill in an answer. This feature is implemented via the texhtml extension package for the TeX input jax, so you would use a configuration like
MathJax = {
loader: {load: ['[tex]/texhtml']}},
tex: {
allowTexHTML: true,
packages: {'[+]': ['texhtml']}
}
};
to load it, add it to the packages to use, and enable it.
In its usual use case in the browser, the HTML will come from the DOM already, and so MathJax doesn't include HTML sanitization in this extension. Because of this, however, the texhtml extension does represent a security risk on sites that allow user content, if they don't sanitize the user input themselves. For this reason, there is an allowTexHTML option for the TeX input jax that must be enabled in order for the <tex-html> elements to be used. Note that \require{} is configured not to load the texhtml package, so unless you explicitly load it yourself, there should be no security issue.
In a browser, MathJax can measure the size of the HTML so that it can provide the proper amount of space for it within the equation, but in node applications, that is not possible, so MathJax provides a method for you to specify the size of the HTML explicitly. To specify the dimensions, add data-mjx-hdw="H D W" to the top-level HTML element inside the MathML token element, where H, D, and W are the height, depth, and width of the HTML. They can be in any units, but em units will work best.
How this attribute is used is handled via a new option to the output jax, htmlHDW, which can be set to 'auto' (the default), 'ignore', 'use', or 'force'. When set to ignore, the data-mjx-hdw attribute is ignored, and MathJax will try to measure the size of the HTML directly. This works well in the browser, but not in the liteDOM, jsdom, linkedom, or other non-browser adaptors. The force option means that MathJax will use the data-mjx-hdw values and will surround the HTML with additional nodes that force the HTML to have the given dimensions. This would make the browser and node both have the same representation, not relying on the browser measurements. The value use means that MathJax will assume the data-mjx-hdw values are correct and will use them without forcing the HTML to have the given dimensions. Finally, auto means that MathJax will determine which to use; this will be ignore when in the browser and force when in node applications.
Having accurate values for the data-mjx-hdw attribute is crucial to the quality of the output. To that end, the following HTML file computes the needed values. These values depend on the surrounding font, so there is a place to enter that, as well. You can also specify the font in the MathML token element that holds the HTML, as in <mtext fontfamily="Arial"><div>...</div></mtext> or <mo style="font-family: arial"><div>...</div></mo>. Otherwise, MathJax will use the surrounding font. The page below gives you a place to enter the HTML you want to measure and the font to use. Press the "Compute HDW" and the HTML is shown below together with modified HTML source that includes the needed data-mjx-hdw attribute. You can copy that and replace the original HTML will it.
<!DOCTYPE html>
<html>
<head>
<title>Compute HDW values for HTML in Token nodes</title>
<script>
function GetHDW() {
const html = document.querySelector('mjx-html');
const content = html.getBoundingClientRect();
const baseline = document.querySelector('mjx-baseline').getBoundingClientRect();
const em = parseFloat(window.getComputedStyle(html).fontSize);
const h = baseline.top - content.top;
const d = content.bottom - baseline.top;
const w = content.right - content.left;
return [h, d, w].map(x => (x / em).toFixed(3).replace(/\.?0+$/, '') + 'em').join(' ');
}
function ShowHDW() {
const html = document.querySelector('#html').value;
const content = document.querySelector('mjx-html');
content.style.fontFamily = document.querySelector('#family').value;
content.innerHTML = html
const output = document.querySelector('#output');
content.firstChild.setAttribute('data-mjx-hdw', GetHDW());
output.innerHTML = content.innerHTML.replace(/</g, '<');
}
</script>
<style>
mjx-measure {
display: inline-block;
border-left: 2px solid red;
border-right: 2px solid red;
}
mjx-baseline {
display: inline-block;
height: 0;
width: 0;
}
mjx-html {
display: inline-block;
}
mjx-line {
display: inline-block;
height: 0;
width: 1em;
border-top: 1px solid blue;
}
#input {
display: inline-block;
}
#input textarea {
margin-bottom: 3px;
}
#input input[type="button"] {
float: right;
}
</style>
</head>
<body>
<h1>Compute HDW values for HTML in Token nodes</h1>
<p id="input">
<textarea id="html" cols="80" rows="10">
<div>HTML</div>
</textarea><br>
Font family: <input type="text" id="family">
<input type="button" value="Compute HDW" onclick="ShowHDW()">
</p>
<h2>The HTML:</h2>
<p>
<mjx-line></mjx-line><mjx-measure><mjx-baseline></mjx-baseline><mjx-html>
 
</mjx-html></mjx-measure><mjx-line></mjx-line>
</p>
<h2>The HTML with the HDW attribute:</h2>
<p id="output">
</p>
</body>
</html>
Of course, you can use this as a basis for automating the process using something like puppeteer, if you wish.
In version 3 of MathJax, the expression explorer was not active by default, and so those with assistive needs had to turn it on explicitly, and it was loaded dynamically at that time. In its place, the assistive-MathML extension was used to generate a hidden MathML expression that could be read by those screen readers that can process MathML. This was a stop-gap measure that was both clunky and somewhat fragile, and changes in screen readers often rendered it ineffective (e.g., the current VoiceOver version doesn't read the mathematics and skips it entirely).
Because of these problems, and because the Speech Rule Engine (SRE) that underlies MathJax's assistive support has been substantially rewritten, we are now packaging the expression explorer and SRE as part of all the combined configuration files, and the assistive MathML extension has been removed from them (though it can still be turned on in the Accessibility sub-menu of the MathJax contextual menu). The SRE generates speech automatically for the expressions in your page and makes these speech strings available to screen readers using ARIA labels and live regions, a technology that has far better support in screen readers than the hidden MathML. This is a substantial change, however, and there are many screen-reader/browser/operating-system combinations, so some issues may arise. Please report problems that you encounter to our issue tracker.
While basic speech is provided for expression via an aria-label attribute, so that a screen reader can read the math naturally as part of the page, it is still possible to interactively explore expressions. This features is available by default in version 4, but interaction with the expressions is now achieved using the ARIA tree view paradigm, moving away from the previously used application role. This should provide smoother interaction with screen readers on all platforms. Speech during exploration is still exposed via a live region; however, we are still experimenting with a number of alternative methods before the final v4.0 release.
In addition, MathJax now provides optional auto-voicing of expressions together with step-by-step highlighting of expression while a formula is spoken. This feature is primarily aimed at users who do not normally utilize a screen reader, and in particular as support for dyslexic readers. It currently has to be switched on explicitly, either in the speech sub-item of the explorer sub-menu of the MathJax contextual menu, or using the voicing option in the a11y sub-block of the options configuration block. Speech is generated by providing SSML annotations to the browser's speechSynthesis API. While this makes use of the full range of prosody annotations available in SRE's speech rules, the feature is only available in browsers that come with an implementation of the speechSynthesis API and with built in voices.
Because the new MathJax fonts include more extensive character coverage, meaning much more data is required, the fonts have been broken down into smaller pieces that can be loaded dynamically, rather than being one big data file, as was the case with version 3. This allows the initial download of MathJax to be smaller, while still accommodating rarely used glyphs for those who need them.
As a result, however, when the data for one of these ranges is needed, MathJax will pause and wait for the data to arrive from the CDN. That means that producing MathJax output is now potentially an asynchronous process, which was not the case in v3. So in the past, as long as you pre-loaded all the TeX extensions that you needed (e.g., with one of the -full components), you could use synchronous calls to MathJax.tex2svg() or the other similar functions. With the new (larger) dynamic fonts, that is no longer guaranteed. That means you should instead use the promise-based versions of these calls, like MathJax.tex2svgPromise(), in order to properly handle the potential for dynamically loaded font data. Without this, you may get errors indicating a "retry" error, which is what MathJax uses to mediate its asynchronous loading actions.
If you can not avoid using synchronous calls, then you may need to load all the font dynamic data up front using a single promise-based call before you start using MathJax synchronously. This can be done using
MathJax.startup.document.outputJax.font.loadDynamicFiles();
to load all the font dynamic data. This function returns a promise, and you should wait for it to resolve before calling any MathJax conversion functions. Note, however, that there can be a lot of font data, and these fonts may include many characters that will never get used, so only do this if you absolutely have to. It is better to use the promise-based conversion functions if you can.
For node applications, you can use
MathJax.startup.document.outputJax.font.loadDynamicFilesSync();
to load the font data synchronously, provided you have defined the MathJax loading mechanism by importing mathjax-full/js/util/asyncLoad/node.ts before hand.
The MathJax 4.0.0-alpha.1 version can be accessed via CDN as
https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-mml-chtml.js
or using one of the other combined configuration files:
tex-html.js
tex-svg.js
tex-mml-chtml.js
tex-mml-svg.js
mml-html.js
mml-svg.js
Each of these includes the mathjax-modern font, but also comes in a version ending in -nofont.js (e.g., tex-mml-chtml-nofont.js) that does not include it, where you are expected to specify the font using the output.font configuration option. This saves your readers from having to download the mathjax-modern font that is not going to be used. The other combined configurations have been removed, as they were either redundant (now that the explorer is already included in all combined components), or where the ones that included tex-full. The latter have been removed because you will need to use the promise-based calls anyway, and that will handle the autoloading of extensions as well, and since the all-packages extension doesn't include the newer packages, and so isn't really "all" packages anyway.
The source code for MathJax v4 is available in the [email protected] npm package, or in the v4.0.0-alpha branch of the MathJax-src repository on GitHub.
The fonts are each in their own npm package, e.g., mathjax-modern-font, mathjax-stix2-font, etc., which you can install in your own node applications as needed. In a browser, MathJax should access the fonts from jsdelivr automatically. These font packages also include combined configuration files that are like tex-mml-chtml.js and tex-mml-svg.js, but that include that package's font rather than mathjax-modern. For example, the mathjax-stix2-font package include tex-mml-chtml-mathjax-stix2.js and tex-mml-svg-mathjax-stix2.js, so you can use
https://cdn.jsdelivr.net/npm/mathjax-stix2-font/ex5/tex-mml-chtml-mathjax-stix2.js
in order to get a single-file MathJax component that includes the mathjax-stix2 font rather than mathjax-modern. In particular, you can get the equivalent of the tex-mml-html.js file with the original MathJax TeX font all in one file using
https://cdn.jsdelivr.net/npm/mathjax-tex-font/ex5/tex-mml-chtml-mathjax-tex.js
This font does not have dynamic ranges (all the font data is in one file), so it should operate much the same as MathJax v3 in that respect.
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)
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.
MathJax now integrates version 4 of Speech Rule Engine (SRE). (#800)
.json extension. (https://github.com/mathjax/MathJax/issues/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:
sre.ts module now imports and exports exclusively API methods necessary for SRE's use in MathJaxmathmaps.ts module provides a map for directly integrating and bundling locales (see more below).sre component under components/src/sre now simply handles copying the locale files in the mathmaps directory.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/src/tex-chtml-full-speech component as an example.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:
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:
sre_browser.js using the sre path in the MathJax configuration, andspeech-rule-engine package with a different version in the node_modules folder.
NEW: This is no longer possible.sreReady method is still exported but deprecated. In the future, you should use the corresponding method in the API bundle Sre.sreReady()..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.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)
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)
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)
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)
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.
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.
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.
Version 3.2 includes nine new TeX extension packages:
\not command (and a non-standard \centerOver that places one symbol centered on top of another).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.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.
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.
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 characters in TeX input has been improved. In the past, nearly all non-ASCII characters would be placed within an <mo> element, which is not always the best tag to use. In version 3.2, processing of raw Unicode characters is more nuanced, so that letters are placed in <mi> elements and other symbols in <mo>. For example, a literal Greek alpha (U+03B1) will produce <mi>α</mi> (which is what is generated by \alpha) rather than <mo>α</mo> as in earlier versions. This should provide better results, though perhaps still not perfect in all cases.
In the past, errors in the MathJax configuration options (such as an unknown option) would produce a fatal error and MathJax would not run. In version 3.2, such errors now produce non-fatal warnings instead, and MathJax will continue to process the remaining options (and then typeset the page). This means that changes to the options (like those described in the breaking changes below) will not cause your pages to fail outright (though the old options will have no effect). You can configure MathJax to make such errors fatal again, if you wish, and you can provide a function that will be called when there is an option error so that you can more easily trap such errors and handle them yourself. See the startup options for more details.
The component loader uses a set of filters to convert a component specification (like [tex]/physics) to the full URL for loading the extension. In the past, it was difficult to hook into that filtering mechanism, but in version 3.2, you can now configure additional filters for the loader. See the loader documentation for more details.
Some of the changes made to the options to accommodate the updated speech-rule engine are potentially breaking changes, in that the previous options (enrichSpeech, a11y.locale, a11y.speechRules) are no longer valid options. Version 3.1.4 includes code to transfer the old options to their new locations, but that code has been removed in version 3.2. As errors in options are no longer fatal (unless you configure them to be), this change will no longer cause MathJax to fail, but will cause warning messages in the browser console, so look there for such error reports.
Similarly, the code that automatically renames the older TeX package names to their current all-lower-case versions (e.g., configMacros to configmacros and colorV2 to colorv2) has been removed from version 3.2. If you are using old package names, you will need to update your configuration. This applies to \require{} macros that refer to the older names as well as their names in the loader section, the tex.packages array, and the tex.autoload block.
Version 3.2 removes the matchFontHeight option for the SVG output jax, since it only applies to the CommonHTML output, but was previously allowed in the svg configuration block, while doing nothing.
Version 3.2 removes of the toArray() method from the LinkedList class (and its subclasses), so any custom code that uses that should switch to using Array.from(...) around the list instead.
Finally, the Box.ts and CssStyles.ts (and their associated .js files) have been moved from the output directories to the util directory. Compatibility files were placed in the original locations so that older code would continue to work, but these have been removed in v3.2, so you should modify any custom code that loads these files to obtain them from the util directory instead.
\| delim causes the wrong size to be used. (#700)\big and friends (mathjax/MathJax#2688, mathjax/MathJax#2689)\mathbf and similar macros so they are treated as a unit(mathjax/MathJax#2688, mathjax/MathJax#2689)physics package (mathjax/MathJax#2449)node-main for webpack 5 (#696)mhchemparser package, now that it is es5 (#714)