Upgrading from v3 to v4
Because version 3 was a complete rewrite of MathJax, the API had major changes from version 2 to version 3, making that upgrade one that could require significant work. That is not the case for upgrading from v3 to v4. The API for v4 is largely the same as v3, with most changes being additions rather than changes.
There are many new features in v4. See the What’s New in MathJax v4.0 section for complete details. There are some breaking changes, which are outlined in the Breaking Changes in V4 section.
For those who are using MathJax in web pages by just configuring and loading MathJax without calling its API directly, you may not have to make any changes other than changing the URL to load version 4.
If you are calling the MathJax API, then you may need to change to
using the promise-based calls like MathJax.typesetPromise()
rather than the synchronous ones like MathJax.typeset().
See the MathJax v4.0 and Promises section for details and suggestions for how
to proceed.
MathJax v4 now produces ES6 modules rather than the older ES5 CommonJS modules of v3. This means has lead to changes in the MathJax source directories and the build tools that are used to compile and pack MathJax and its extensions. See the sections on MathJax ES6 Modules, Change to ES6 Modules, and Changes to the Build Tools for more information.
There are significant changes to how MathJax handles speech generation in v4. See the Explorer Technical Details and Changes for Speech Generation sections for more information on these changes and how to address them.
If you have written extensions or other customizations for MathJax, then there are changes that you may need to take into account. See the Breaking Changes in V4 section for more details about these. There are also many more examples available here for both the web-based and node-based applications of MathJax. See Examples of MathJax in a Browser and Examples of MathJax in Node for lists of the most important ones.
There are a number of changes to the TeX input jax and its extensions
that may affect existing content. For example, the
textmacros extension is no by default in the combined
components, which has implications for
\text{} and other text-mode macros if they contain text that will
now be considered as macro references that where ignored in the past.
There are also changes to the mathtools extension, and to
several other extensions. See the Input Improvements section
for details on this and the other such changes.
The all-packages extension has been removed, as have the combined
components ending in -full. See Removal of AllPackages for more on this.