Skip to content

Releases: mathjax/MathJax-src

MathJax v4.0.0-rc.2

21 Jun 18:38
@dpvc dpvc
4.0.0-rc.2
62226e2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
MathJax v4.0.0-rc.2 Pre-release
Pre-release

This PR is the culmination of months of work to improve the performance of the assistive and speech-generation tools in MathJax. These are discussed in the sections below. There are also a number of new features and bug fixes. With this release, MathJax is moving to scoped npm packages, in the @mathjax scope; see below for more details. This is the last planned pre-release of v4.0, and it is the current release candidate. If all goes well, the official v4.0 should be released in July.

Note that 4.0.0-rc.1 had a packaging issue, and has been removed.

Accessibility Performance Improvements

When the MathJax accessibility features were turned on by default in the 4.0.0-beta.6 release, this led to a greater performance degradation in practice than in our testing. The 4.0.0-beta.7 attempted to address that issue by putting off the speech generation until after the mathematics was displayed, but this still did not perform as well as we wanted. As a result, we have spent the last 6 months working on alternative approaches.

The method we selected is to move the speech generation into a web-worker thread, which allows the browser to remain responsive even while the speech generation is being performed. This involved a substantial refactoring of both the MathJax assistive support code, as well as the speech-generation engine that underlies that support, but our tests indicate that this is a significant improvement over the results in the beta.7 release. Because web-workers are only available in browsers, not in node applications, we had to develop a means of supporting this new approach within node. Our solution was to use the node worker-threads library, along with some shim code to give it a corresponding interface to the features we were using from web-workers in the browser. This allows the same code to be used in both browsers and node applications. Currently this requires the use of the LiteDOM in node, but we may provide support in other DOM implementations in the future.

Because node applications that include speech generation now use worker-threads behind the scenes, the node application won't exit until the MathJax worker thread is shut down, so applications may need to tell MathJax that they are finished. This is done by calling the new MathJax.done() method in applications that use MathJax components, or by calling the MathDocument's done() method for this that use direct calls to MathJax's modules.

Expression Explorer Improvements

The expression explorer in the beta.7 release does not follow the ARIA standards properly, and while it worked in some browsers and with some screen readers, it did not work well in others, and, in particular, it failed rather badly in VoiceOver on MacOS. The interaction between browsers and screen readers is complicated, and the results vary widely among the different browser/os/screen-reader combinations. We spent several months searching for a mechanism that followed the ARIA specification while still giving consistent results across that various browsers and screen readers. The main goals were to:

  • Follow the ARIA standards.
  • Work across the major browser/OS/screen-reader combinations.
  • Properly read the full expression when reading the whole page or stepping through the page sentence-by-sentence (or by other units).
  • Automatically enter "focus mode" when the expression is focused via tabbing or clicking (in those screen readers that have separate focus and browse modes).
  • Allow control over the description of the math (e.g., "math", "clickable math", or no description) used during reading and focusing.
  • A "press H for help" message should be spoken when the math is first focused (but can be turned off by a menu preference).

We tested with 13 combinations: Chrome, Firefox, and Safari on MacOS with VoiceOver; Chrome, Firefox, and Edge on Windows with NVDA and JAWS; and Chrome and Firefox on Linux (Ubuntu 24 and 22) with Orca, and believe we have achieved these goals in all cases. The new explorer should give a much smoother experience to screen-reader users in all these settings.

Using the explorer remains largely the same. The explorer was enabled by default initially in beta.6, and continues to be in this release. That means that clicking on an expression will enter the explorer, highlight the clicked term, and cause a screen reader to speak that term; navigation via arrow keys will continue from that point. In previous versions, the speech and/or braille subtitles were shown as well, but these have been turned off by default in this release, as they caused confusion for users not aware of the explorer fetures. They can be re-enabled by use of the MathJax contextual menu.

Several new functions have been added to the explorer:

  • Pressing h will open a dialog box that describes the explorer's features. When an expression is first focused, a message informing the user of this feature is announced after the expression is read, but that can be disabled using the contextual menu.
  • Clicking on an expression starts the explorer and selects the clicked character, as in the past. New in this version is that double-clicking will start the explorer on the whole expression (just as tabbing to it would).
  • In the previous version, if an expression was explored and tab is used to leave the explorer, when that expression is refocused, the selection would remain where it was when the expression was exited. In this version, tabbing to an expression always starts at the top level of the expression, not the last selected term. The reason for this is so that if the page is read, wither as a whole or by smaller chunks, the expression will be read in full rather than just the previously selected term. There is a contextual menu item that can be used to select the older behavior, however, if a user wishes to be able to restart the explorer where they left off.

Speech-Generation Improvements

Aside from moving the speech generation into a web worker or node worker thread, the speech-generation has been improved by adding more sophisticated semantic analysis for complex user defined structures, including improved disambiguation of function applications, ellipses, and unusual large operators. MathJax now also automatically includes speech generation in precise SSML markup that is used for MathJax's auto-voicing feature as well as exposed in the speech attributes. Additional locales supported are Afrikaans and Korean as well as 8-dot Euro Braille output generated from original LaTeX input formulas.

Because the speech generation has been moved to a web-worker, the speech is no longer produced by the main MathJax thread, and so the timing options that were added in v4.0.0-beta.7 have been removed. That is, the speechTiming section of the options block of the MathJax configuration is not longer necessary, and will be marked as invalid if it is used.

Input Changes

In previous versions of MathJax, the macros in text-mode material (in \text{} and similar macros) were not processed unless the textmacros extension was loaded and enabled. This version now includes the textmacros extension in all the combined components that contain the TeX input jax (i.e., all the ones starting with tex-). This means that macros inside text-mode will be processed. Because only a limited number of text-mode-macros are defined, this can lead to errors in cases where the literal macro name would be displayed in the past. For example, prior to this version \text{The \item macro is used in lists} would produce the literal string The \item macro is used in lists, but in this version, it will lead to an error message about \item being undefined. So this may be a breaking change in some pages that take advantage of the old behavior.

You can disable the textmacros extension in combined components that include it by merging

MathJax = {
  tex: {
    packages: {'[-]': ['textmacros']}
  }
};

into your MathJax configuration.

One of the last remaining extensions from version 2 that was not ported to v3 is now available in this release: the begingroup extension that allows you to create temporary macro definitions. See the v2 begingroup documentation for more details (the v4 documentation is being written, but is not yet available).

The v4 version of begingroup defines two new non-standard macros: \begingroupReset and \begingroupSandbox. The first one ends any open \begingroup macros, reming any of their temporary macros or environments. The second can be used to isolate the definitions in one section of the page from those in another, so that sites like StackExchange can use this between user posts to make sure that one user doesn't redefine things to mess up another user. The \begingroupSandbox macro can't be redefined, and its action is essentially to do \begingroupReset\begingroup. This removes any previous user definitions and makes a new group for the next user's definition. It also directs any global definitions to this new group so that a user can create...

Read more
Loading

MathJax v4.0.0-beta.7

25 Jul 21:03
@dpvc dpvc
4.0.0-beta.7
267bc5e
Compare
Choose a tag to compare
MathJax v4.0.0-beta.7 Pre-release
Pre-release

This release is primarily a bug-fix release. In particular, the redesign of the way speech is computed and attached to MathJax’s output that was part of the beta.6 release introduced a performance degradation that needed to be addressed. The main purpose of the beta.7 release is to fix that performance problem. In addition, there are also fixes to allow table columns to shrink when their contents have line-breaks, and to allow in-line breaking to work properly in Safari. The computations for the bounding boxes of the layouts in the bussproofs TeX package have been improved. A security issue involving the potential for users being able to insert CSS styles into MathJax equations was identified by the GitHub security team, and is addressed here. The all-packages extension and corresponding AllPackages.ts file and the tex-full component that used them have been removed. Finally, font extension can now be generic extensions so that they work with any base font, and the bbm, bboldx, and dsfonts packages have been rebuilt to be generic font extensions.

Performance Update

The changes made to the speech computations in v4.0.0-beta.6 caused a performance degradation that causes pages to typeset visibly slower than earlier versions. In particular, the lazy-typesetting extension was noticeably affected. In order to address this, MathJax v4.0.0-beta.7 puts off doing the speech computation until after the visual mathematics has been displayed, which restores the original performance. To do this, the speech is computed and attached a few equations at a time, with slight delays in between in order to allow the browser to perform screen updates and scrolling for other user interaction. There are new configuration parameters that control the timing of this operation:

MathJax = {
  options: {
    speechTiming: {
        asynchronous: true,                // true to allow screen updates while adding speech, false to not
        initial: 100,                      // initial delay (in milliseconds) until starting to add speech
        threshold: 250,                    // time (in milliseconds) to process speech before letting screen update
        intermediate: 10                   // delay (in milliseconds) after processing speech reaches the threshold
    }
  }
};

When the options.speechTiming.asynchronous value is true, speech will be added a little at a time. The options.speechTiming.initial value is the delay (in milliseconds) to wait before starting to add speech, the threshold value indicates how long MathJax should work on speech before allowing the screen to update again, and intermediate is how long to wait after that before starting to compute speech again.

If options.speechTiming.asynchronous value is false, then speech is added to the expressions immediately when they are typeset. This can be useful for node applications that run on the server, and don't need to wait for screen updates (as there is no screen to update).

Removal of AllPackages

The AllPackages.ts file was intended as a means of loading most of the TeX extensions up front so that you did not need to worry about asynchronous loading of extensions via the autoload package. But now that MathJax's output is also asynchronous, using AllPackages is no longer sufficient to allow for synchronous processing. As more extensions have been created, they have not all been added to AllPackages.ts, and as the library of extensions, both core and third-party, grows, it is impractical to keep all of them in one package. So in this release, these files have been removed. For those using MathJax in node applications, you can use

import {source} from 'mathjax-full/components/src/source.js';
const AllPackages = Object.keys(source).filter((name) => name.substring(0,6) === '[tex]/').sort();

to get a list of the main TeX packages. For use on the web, you could use

<script type="importmap">
{
  "imports": {
    "#source/source.cjs": "https://cdn.jsdelivr.net/npm/mathjax-full@4.0.0-beta.7/components/mjs/source-lab.js"
  }
}
</script>
<script type="module">
import {source} from 'https://cdn.jsdelivr.net/npm/mathjax-full@4.0.0-beta.7/components/mjs/source.js';
const load = Object.keys(source).filter((name) => name.substring(0,6) === '[tex]/').sort();
const packages = ['base'].concat(load.map((name) => name.substring(6)));
window.MathJax = {
  loader: {load},
  tex: {packages}
};
</script>

to load all the extensions. Add any other configuration options that you need to the window.MathJax variable.

List of Bug Fixes in this Release

Loading

MathJax v4.0.0-beta.6

30 Apr 19:15
@dpvc dpvc
4.0.0-beta.6
2185f0b
Compare
Choose a tag to compare
MathJax v4.0.0-beta.6 Pre-release
Pre-release

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 \mathbbmtt to generate its double-struck characters, as well as a \mathversion macro 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 than bold 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

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

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)

Loading

MathJax v4.0.0-beta.5

25 Apr 21:51
@dpvc dpvc
4.0.0-beta.5
81e2437
Compare
Choose a tag to compare
MathJax v4.0.0-beta.5 Pre-release
Pre-release

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.

Loading

MathJax v4.0.0-beta.4

04 Oct 16:35
@dpvc dpvc
4.0.0-beta.4
818f68e
Compare
Choose a tag to compare
MathJax v4.0.0-beta.4 Pre-release
Pre-release

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

Output Fixes

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)

Loading

MathJax v4.0.0-beta.3

19 Jul 21:22
@dpvc dpvc
4.0.0-beta.3
49db078
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
MathJax v4.0.0-beta.3 Pre-release
Pre-release

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.

Loading

MathJax v4.0.0-beta.2

17 Jul 16:44
@dpvc dpvc
4.0.0-beta.2
6331c82
Compare
Choose a tag to compare
MathJax v4.0.0-beta.2 Pre-release
Pre-release

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.

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

Read more
Loading

MathJax v4.0.0-beta.1

17 Jul 15:59
@dpvc dpvc
4.0.0-beta.1
b27a4c8
Compare
Choose a tag to compare
MathJax v4.0.0-beta.1 Pre-release
Pre-release

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

Loading

MathJax v4.0.0-alpha.1

02 Oct 13:52
@dpvc dpvc
4.0.0-alpha.1
9d13709
Compare
Choose a tag to compare
MathJax v4.0.0-alpha.1 Pre-release
Pre-release

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

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

Read more
Loading

MathJax v3.2.2

08 Jun 17:22
@dpvc dpvc
3.2.2
ad8f5c2
Compare
Choose a tag to compare
MathJax v3.2.2 Latest
Latest

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)

Assets 2
Loading