MathJax source code for version 3 and beyond
This is a hot-fix release to correct two issues in the recent 3.1.3 release. Both errors only affect server-side node applications that use the mathjax-full npm package and import the MathJax modules directly, and not the web-based MathJax components.
The inclusion of the mhchemparser npm package caused errors in server-side node application that included the mhchem package. This is resolved in #689.
A change to HTML the serialization code in the LiteDOM caused empty tags to not have their closing tags. This is resolved by #690.
The mathjax npm package and CDN servers will see an update to v3.1.4 as well, even though the 3.1.3 version does not include these bugs, so that the versions stay synchronized.
This is mostly a bug-fix release, various display bugs and other issues. See the individual bugs linked below for more details, and the 3.1.3 milestone for the pull requests involved in this release.
reset() command now allows resetting input and output jax. (#647)\mathXYZ and \symXYZ macros (e.g., \mathsfit, \symbfup) and use multi-letter <mi> when possible. (mathjax/MathJax#2595)mhchem extension to the latest version from the author. (#688)\middle to work when a style or color is open. (mathjax/MathJax#2663)* in \\* and \\*[...] constructions. (mathjax/MathJax#2433)\| being stretchy when it shouldn't be. (mathjax/MathJax#2632)textmacros and noundefined are both in effect. (mathjax/MathJax#2622)<mrow> nodes that look like \left...\right to be TeX class INNER. (mathjax/Mathjax#2584)<mrow> nodes as fences if the parentheses aren't stretchy. (#583)<mspace> elements have TeX class NONE. (mathjax/MathJax#2576)<mo> elements to better follow the specification. (mathjax/MathJax#2392)<menclose> notations. (mathjax/MathJax#2571)smallmatrix environment properly. (#582, #621)<mi> elements to include trailing combining characters. (mathjax/MathJax#2617)<munderover> and <msubsup> combinations. (#634)<mroot> elements properly. (mathjax/MathJax#2630)enableEnrich and other a11y options could not be configured. (mathjax/MathJax#2651)<annotation-xml> content. (#678)role='presentation' attributes. (mathjax/MathJax#2608)pack and makeAll commands to display the modules used in version 5 of webpack. (#591, #579)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. Since MathJax flags invalid options and stops processing when it encounters one, this means any configurations that used the older options would no longer work. Version 3.1.3 includes code to transfer the old options to their new locations, but that code will be removed in version 3.2. This gives page authors the opportunity to fix the issue before version 3.2 is released and their pages break.
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) will likely be removed from version 3.2, so if you are using old package names, you should change your configurations before version 3.2. 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 will also see the removal of the matchFontHeight option for the SVG output jax, since it only applies to the CommonHTML output, but is currently allowed in the svg configuration block, while doing nothing.
Version 3.2 may include other breaking changes, such as the removal 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 will likely be removed in v3.2, so you should modify any custom code that loads these files to obtain them from the util directory instead.
Hot fix to correct regression introduced in v3.1.1 that caused control sequences followed by spaces to not be recognized.
This is a bug-fix release to address several issues that arose from the 3.1.0 release, particularly with the textmacros package for the TeX input jax. It also updates the Speech-Rule Engine to version 3.1.1.
\textit, etc., not working with the textmacros extension enabled. (mathjax/MathJax#2514)textmacros extension. (mathjax/MathJax#2526)\ref and \eqref in textmacros extension. (mathjax/MathJax#2528)textmacros. (mathjax/MathJax#2527)textmacros causing incorrect display in SVG mode. (mathjax/MathJax#2524)displaystyle. (mathjax/MathJax#2520)\begin followed by spaces. (mathjax/MathJax#2511)convert() to accept family parameter (mathjax/MathJax#2512)aria-label, alt, exact-speech.mglyph if they contain a direct speech attribute.This is a feature release that includes a number of API improvements, new extensions, and updates to the assistive tools, as described below. It also includes several bug fixes.
See the individual issues and pull requests linked below, as well as the What's new in v3.1 section of the MathJax documentation, for more details.
Also note that the demos in the node examples have been updated and expanded to include examples of using a simplified interface for MathJax in server-side node applications, MathJax with Puppeteer, and MathJax with jsdom.
textmacros extension for handling some macros in text-mode. (#509)safe extension and component. (#514)noundefined extension. (#507)mtextInheritFont, and provide new mtextFont option. (mathjax/MathJax#2189)formatError a configuration option for tex input jax. (#483)startup.promise so it is always valid. (mathjax/MathJax#2307)data-mjx-error, similar to compile/typeset errors. (#490)bbox property. (#495)output/common/BBox.ts to util directory. (#494)output/common/CssStyles.ts to util/StyleList.ts. (#493)scriptminsize and scriptsizemultiplier. (#515)texClass for multi-character <mi> elements. (#503)node-main to be able to load SRE more easily. (#479)texClass. (#512)classList when elements don't have it. (mathjax/MathJax#2411)\underset explicitly turn off movablelimits. (mathjax/MathJax#2460)\boldsymbol\partial work properly. (mathjax/MathJax#2417)\overbrace in SVG output. (mathjax/MathJax#2402)This is a hot fix release to resolve an important issue with horizontal stretchy characters (e.g., \overline and \overrightarrow) in CommonHTML output that was introduced in the recent version 3.0.4 release.
This is mostly a bug-fix release, resolving a number of important issues since v3.0.1. See the individual bugs linked below for more details, and the 3.0.4 milestone for the pull requests involved in this release.
Version 3.0.2 and 3.0.3 had problems with their npm deployment and have been removed; 3.0.4 is the next release after 3.0.1.
The infrastructure for the font system has been updated to prepare for more font support in a future release. See #455 for details.
The expression explorer now has dynamic loading for its locale data, and the speech-rule engine has been updated to 3.0.0-beta.10.
Fix positions of superscripts in "cramped" style. (mathjax/MathJax#2395)
Fix problem with \rightarrow being converted to \vec in some cases. (mathjax/MathJax#2380)
Improve handling of displayed equations next to floating content. (mathjax/MathJax#2351)
Make SVG honor the scale configuration option. (mathjax/MathJax#2376)
Fix row alignment for negative row numbers. (mathjax/MathJax#2394)
Fix spacing around some fractions. (mathjax/MathJax#2391)
Make unitless linethickness be a multiple of the default size. (mathjax/MathJax#2381)
Fix issues with munderover/msubsup output when base is scaled. (mathjax/MathJax#2317)
Add ability to include MJXZERO to font-family used for undefined characters. (#449)
Improve alignment of elements of multi-glyph stretchy characters in Chrome. (mathjax/MathJax#2311)
Fix incorrect positioning of root in mroot. (mathjax/MathJax#2347)
Fix incorrect font data for \setminus and \smallsetminus. (mathjax/MathJax#2325)
Use em rather than mu units for extensible arrows. (mathjax/MathJax#2357)
Don't add \text to operators whose names already include it. (mathjax/MathJax#2222)
Allow \newline to work like \\. (mathjax/MathJax#2141)
Use proper spacing for \mathrel in align environment. (mathjax/MathJax#2175)
Add tagFormat to AllPackes, and update the preloaded list. (mathjax/MathJax#2328)
Fix mglyph attribute from offset to align. (mathjax/MathJax#2360)
Fix problem with convert() call with MathML input. (mathjax/MathJax#2330)
Correct menu name being disabled. (mathjax/MathJax-demos-node#10)
Fix error with setting startup.elements in configuration. (mathjax/MathJax#2371)
Use components/global.js to get window.MathJax in menu handling. (#458)
Prevent reading node_modules/@types from containing directories. (mathjax/MathJax#2358)
Don't process escaped characters in a11y and menu extensions. (mathjax/MathJax#2327)
Set loader's mathjax path to work in more situations. (#406)
Fix problem with infinite loop with SRE component in IE. (#450)
This is a bug-fix release that fixes most of the bugs reported since the v3.0.0 release. See the individual bugs linked below for more details, and the 3.0.1 milestone for the pull requests involved in this release.
\text{} content values. (mathjax/MathJax#2283)\require{bussproofs} load properly.TexParser.Push() handle inferred mrows properly. (mathjax/MathJax#2261)mu to ems. (mathjax/MathJax#2239)movablelimits support.tagFormat to allow it to work with AMS tags. (mathjax/MathJax#2201)amsCd component. (#335)texClass uses by \dots. (mathjax/MathJax#2315)maligngroup elements. (mathjax/MathJax#2295)pt relative to the em size (as it was in v2). (mathjax/MathJax#2285)xlink namespace in SVG output. (#365)msqrt when computing clearance value.variantForm characters in CHTML. (mathjax/MathJax#2236)multline environments with tags. (mathjax/MathJax-demos-web#17)mtables. (mathjax/MathJax#2186)annotation-xml elements. (mathjax/MathJax#2210)\underline in SVG output. (#264)data-mjx-* attributes to MathML serialization to support internal values.annotation-xml contents.texClass for TeXAtom serialization. (mathjax/MathJax#2193)node-main.js to use require() and the correct mathjax path. (#406)source.js and dependencies.js into ESM modules. (#420)ts/core/MmlTree/MmlNode.ts.<br>. (mathjax/MathJax#2202)className attribute values. (mathjax/MathJax#2185)MathDocument.convert() stopping before the final requested step.MathDocument.convert() handle output with unknown characters. (mathjax/MathJax#2309)After over two years of development, the MathJax team is pleased to announce the official release of MathJax 3.0.0!
This version is a complete rewrite of MathJax from the ground up using modern programming techniques, including Typescript, ES6 modules, Promises, and more.
Please see the What's New in v3.0 section of the documentation for details about the new version 3.0.0.
Please see the Upgrading from v2 instructions for details about what is and isn't in version 3, and how to upgrade your site from version 2. Note in particular that there is a configuration converter that can help you move from version 2 to version 3.
See the documentation for details about how to use MathJax.
There are two repositories that contain examples of using MathJax, one for web pages, and one for use with node on a server:
Please use the MathJax Issue Tracker to report problems in version 3 of MathJax.
This is the fourth public beta release of MathJax v3.
NOTE: Mathjax v3 is in beta release. Do not use this in production but please test it and report issues at https://github.com/mathjax/mathjax-v3/issues!
This is the final planned beta version. We expect an official 3.0 release in the near future.
This beta includes a number of important improvements over the beta.3 version, which are described below.
The biggest change is the ability to create MathJax "components" that can be dynamically loaded by MathJax as needed (much as could be done in version 2). This allows portions of MathJax to be bundled together into components that include most or all of what you need to run MathJax, but still allows less-used pieces to be loaded on demand later when needed. This is similar to v2's combined configuration files and TeX extensions.
The main goal of these components is to use them for the delivery of MathJax from the CDNs that host MathJax. This allows you to customize the MathJax components that you use without having to have (as single files on the CDN) every possible combination of parts that anyone would need packaged together. We will provide a number of all-in-one packages that include an input and output jax together with the data for a font to be used, but also will provide separate components for the individual input and output jax, fonts, TeX extensions, and so on, so that you can mix-and-match them as needed.
MathJax components can be used in the browser as well as on the server in NodeJS applications, so browser and server-side applications can use the same code base and configurations. Components can be combined together into larger packages, either with other MathJax components, or with your own code, via webpack, for example.
Moreover, the tools for building components are available so that you can create your own custom components that you can serve from your own website if you have special needs not addressed by the CDN. For example, authors writing TeX extensions for MathJa can create their own components that can be loaded into MathJax from a different server even if the core MathJax is loaded from a CDN.
Although components are a convenient way of working with MathJax, those writing NodeJS scripts that use MathJax need not use the components as we have packaged them at all; they can continue to import MathJax into their projects directly, as in previous beta versions.
The component system described above can be configured using a global variable MathJax that you set before loading the main MathJax component that you are planning to use. The MathJax variable specifies configuration blocks for the various components in much the same was as was done in version 2 (this is illustrated in the examples below, and described in more detail in a separate section below). MathJax will modify this global variable to include the methods and data that it creates during the startup process for your use in your applications.
The mechanism for rendering expressions in previous beta versions of MathJax 3 involved calling a sequence of MathJax commands to perform the individual actions required to find, compile, typeset, and insert the math into the page. These functions are still available, but there are now several new functions to make that process easier and more natural to perform. The render() method of the MathDocument and MathItem classes will perform all the actions normally needed for typesetting math to the page, and the convert() method will perform conversion from the input format to the output format of the page (or to MathML, which is used internally by MathJax).
These methods use an internal list of actions to be taken when they are called, and those lists are updated automatically when extensions are loaded. For example, when the semantic-enrichment extension is loaded, the action that performs the enrichment is added to render() and convert() automatically, so you don't have to call the extension's methods yourself. You can even add your own actions to the list, if you want, or could remove the automatic ones to fully customize the rendering process.
If you use the MathJax components described above, MathJax will set up short-hand functions for you for typesetting the page or converting from input to output formats. For example, if you load the input/tex and output/chtml components (or the tex-chtml combonent that combines them), you automatically get methods Typeset() and TypesetPromise() for typesetting the page, and tex2chml(), tex2chtmlPromise(), tex2mml(), and tex2mmlPromise() that convert from TeX to HTML or MathML. You also get texReset(), TypesetClear(), and chtmlStylesheet() that reset TeX's labels and equation numbers, reset the typesetting system entirely (the information about CSS used, font caches, etc.), and produce the CSS stylesheet object used by CommonHTML for the expressions you have processed so far. The ones ending in Promise return a promise that is resolved when the math is completed (use this if there is a chance that an external module needs to be loaded, e.g., with \require), while the others perform the typesetting or conversion and return the result immediately (they will throw an error if an external module needs to be loaded).
If you are using the MathJax components, then the MathJax.startup object includes references to the important objects created by MathJax automatically, like the input and output jax, the DOM adaptor, and the MathDocument. You may reference these as needed in order to access their methods for more special-purpose needs. Some of the examples below illustrate this.
A contextual menu similar to the one in version 2 has been added to MathJax v3 in this beta version. It has the actions familiar from version 2, but also includes some new features like copying to the clipboard.
This beta version now includes support for assistive technology via the generation of speech strings attached to the math elements, and via an interactive expression explorer like the one in version 2. These can be activated using the contextual menu, as in version 2, or by importing the a11y components into your node project or custom webpacked version of MathJax.
The CommonHTML output now produces only the CSS needed for the expressions on the page, rather than the CSS for every possible character in the font being used. This reduces the number of CSS rules used by CommonHTML considerably, and improves performance of browser refreshes and zooming. If you use NodeJS applications to preprocess math expressions and capture the CSS output to a separate CSS file, you may need to process all the math expressions before generating the CSS file. Alternatively, there is a new adaptiveCSS option for the CommonHTML output jax that you can set to false to have MathJax return to the beta.3 behavior.
The SVG output now includes the option of caching the glyphs used to render the mathematics so that the paths are shared if a character is used more than once. The cache can either be global (all expressions on the page share a common cache) or local (each expression has a cache for glyphs used within it, but they are not shared between expressions). This can be set using the fontCache option for the SVG jax, and it can be set to 'global', 'local', or 'none'. The default is 'local' so that conversion of math to SVG will produce self-contained SVG expressions.
As part of the new components feature discussed above, the TeX input jax can load TeX extensions in much the same way that v2 could. This is accomplished through the new require extension that implements the \require macro to load extensions. There is also and autoload extension that will load extensions automatically when their macros or environments are first used. These are included in the default input/tex component, so you if you use that component (or one of the combined components based on it, like tex-chtml or tex-svg), you should have access to these extensions automatically. For example, \require{physics} will load the physics package.
Another new TeX package is the configMacros extension that allows you to configure pre-defined macros using the TeX input jax options, much like you could do in v2. See the tex-macros example below for more information.
The new tagFormat extension allows you to customize how tags are handled in MathJax, and provides the equivalent of the formatNumber(), formatTag(), formatID() and formatURL() options of the TeX equationNumbers configuration block from v2.
The new braket extension implements the physics bra-ket notation macros. They will be loaded automatically if you use the input/tex component, or include the autoload extension in your project.
In version 2, the \color macro worked in a non-standard way. The LaTeX \color macro acts as a switch, to change the current color for all the math that follows it, while the MathJax version took a second argument that enclosed the math to be colored. Version 2 included a color extension that implemented the LaTeX \color behavior, but it was not loaded by default.
In version 3, the LaTeX \color macro will be the default behavior if you are using the input/tex or input/tex-full components, or any component buildt on them (e.g., tex-chtml or tex-svg). You can restore the v2 behavior by setting color: [] in the autoload configuration for the tex component (when using input/tex), or by
removing the color extension from the package list using packages: {'[-]': ['color']} in the tex configuration (for input/tex-full). See the v2-color example for details.
This beta version includes two input processors (TeX and MathML) and two output processors (CommonHTML and SVG). Other input and output processors (e.g., AsciiMath input) will be added in the future.
The current TeX input processor has all the core functionality of the MathJax v2 TeX input, and nearly all the extensions that are now available in v3.
The CommonHTML and SVG output implement all the MathML elements that they do in v2, but do not yet include support for line breaking (neither automatic nor explicit ones); this will be implemented in a later version. Both output renderers currently only support the MathJax TeX font; other fonts will be added in the future.
The mj3-demos repository includes examples of how to use MathJax v3 in web browsers, including interactive examples, custom configurations, custom tex extensions, and custom builds that you can use as a starting point for your own projects. See the instructions in that repository for more details.
The mj3-demos-node repository includes examples for how to use MathJax v3 in NodeJS applications, and includes sample tools and examples of how to use a number of MathJax v3's features.