Upgrade plans for MathJax v3/v4

Question

While this is not the way I wanted to announce this, it seems the cat is out of the bag. But for those who haven't noticed, as part of our Community Asks Sprint, I spent the week investigating how we might go about upgrading our MathJax version from 2.x to 3.x+, as had been requested in several places, notably:

• Are there plans to switch to the current version of MathJax?
• Switch to MathJax version 3? - Mathematics Meta Stack Exchange
• MathJax out of date - Mathematics Meta Stack Exchange

Caveats

Right off the bat, I want to place some important caveats on this work:

1. It's still experimental and early stages.
2. There are several features that were removed in v3 that will likely come back in v4 that are probably worth including in a GA release.
3. If there are too many insurmountable issues, we may have to stick with v2 for the foreseeable future until we can further dedicate / prioritize efforts.

For these reasons, v3+ right now is opt-in only at the individual account level for folks who would like to take part in early beta testing and report back any issues they find (on this post). On sites that have MathJax enabled, you'll see a preference toggle under /users/preferences/current that will enable MJv3 for your account.

If this in any way impedes your work please feel free to toggle back off to V2. If we need to roll this back for any reason, we can disable the toggle and serve all users v2 until any Sev 0 issues are fixed. Also, if there are any syntax choices that work better in v2 than v3, please stick with v2 while drafting new posts to optimize for all viewers until we've rolled this out everywhere.

Known Issues / Deltas / Mitigations

• Currently only the TeX font is available (HTML-CSS.availableFonts not implemented)
  • Note: we used to allow STIX & TeX, but preferred TeX, so only having that option should be acceptable.
• The HTML-CSS.EqnChunk option is not yet implemented (but may be in a future release)
  • Note: Chunking allows for the site to process small batches of changes to optimize load times. On mobile we chunked 10 at a time, on desktop 50. The new version is more efficient and does all loading in a single pass, so chunking is not really a concept there and much less of a need.
• Extension TeX/begingroup is not yet implemented (but may be in a future release)
  • Note: Grouping allowed expressions from one post to not impact another by sideloading resources. This is not implemented for v3 so it's possible to have side-effects from multiple different posts on the same page. This may be a blocker for GA.
• The HTML-CSS.linebreaks option is not yet implemented (but may be in a future release)
  • Note: This is a known limitation of v3, but it should be added back by v4. We had our configuration set to allow automatic linebreaking so long expressions should have wrapped. We will handle this in v3 with an overflow scrollbar when necessary. Example of Mathjax v2 vs v3 linebreaking comparison showing horizontal scrollbar in v3
• MHChem is now included in the base package by default, so we may eventually be able to do away with enabling mhchem on a site-by-site basis as it will automatically lazy load if used.
• Packages that are \require'd in many have been moved around, notably AMScd which seems to break spectacularly enough that JS throws for the entire page. I'll try to get a quick turnaround to patch that up, so we can focus on more edge case error reporting here.

Reporting / Future

A future consideration is how any content changes will work if we need to update syntax on posts between v2 and v3. For Example, in my testing AMScd seems to be case sensitive, which is gonna be a tricky migration if we need to fix during the upgrade, but maybe there's a programmatic solution we can unlock as well.

I wanna thank Davide Cervone for his helpful analysis here and ongoing project updates. Please feel free to report any issues you run into under this post, that'll be helpful for the full migration, but please be aware that there's not a team on this full time right now, so this is more to help line up and document remaining work than a full feature rollout at this point.

Answer 1

In preview, display math $$ ... $$ is incorrectly rendered as ordinary in-line math $ ... $.

E.g., when editing this answer, the preview looks like this:

It shows up correctly in the final post.

Strangely enough, editing this post shows an opposite behaviour: $$ ... $$ displays properly, but normal paragraph breaks are not rendered. Also, Markdown formatting including *...* and **...** is not rendered:

Again, it shows up correctly in the final post, and in v2.

Answer 2

In many of my answers on Math SE and MathOverflow, I use the \label MathJax command with equations, e.g., \label{eq1A}, so I can later reference them using the \eqref command, e.g., \eqref{eq1A}. This, however, doesn't work properly with the new version's editor, with it complaining about each of the labels being duplicated, even though one of them are actually being used.

For example, with my answer on Math SE, when the option is turned off and I edit the answer, the top part of what I see is:

However, when I turn on the MathJax v3 beta option, the top part of this is now:

These yellow multiple definition error messages continue further for every equation where I used \label. Note this problem also occurs while I'm initially creating a new answer. Nonetheless, apart from requiring a refresh if I save my edits, the final display does otherwise work properly (including if I'm only just displaying these answers).

Answer 3

I added a comment using the MathJax \color command to make several parts of a couple of equations be red. To better show the text that I used and the results, I repeated this using an answer on Math meta's "Formatting Sandbox" post. Here's what it looks like with the option turned off while editing:

After saving this, both the post, as well as the comment, appear correctly. However, when editing that post with the MathJax v3 beta option turned on, it instead appears as:

Notice how the first equation now has all of it being red (as shown in the first blue oval) after the first usage of \color, as opposed to just the intended 3 separate smaller parts. Also, in the second equation on the next line, the last 3 terms (in the second blue oval) are red, instead of just the the last term of the LHS of the equation.

Unfortunately, this problem persists when I view this post, as well as the original comment.

---

Note that wizzwizz's comment below states:

This behaviour is documented; there's a fix available, but I think this should only be applied to old posts, if possible.

Fortunately, one quite simple way to have the color handling work properly in both MathJax v2 and v3, as it's now without any potential fixes or other changes being implemented, is to use brace brackets around each of the color commands and text, so they form their own groups. For example, we can change \color{red}{2abc} in the first equation above to {\color{red}{2abc}}. More details, including the updated MathJax text, is in the Math meta answer I mentioned earlier.

---

This issue may potentially cause a syntax error to be displayed instead of the equation. Using MathJax v2, the last part of this answer is:

The issue is with the red '+' superscript being used. In MathJax v3 beta, this causes the equation display to become:

Note that the edit preview shows the same behaviors as in both the corresponding v2 and v3 beta displays. Fortunately, my earlier suggestion of using brace brackets around the entire part also solves the problem here for both v2 and v3 beta, i.e., in the MathJax for the equation of

$$\lim_{x\to0}\sqrt{|x|}\ln|x|=
\lim_{x\to0^\color{red}{+}}x^{\frac12}\ln x=0.$$

I changed in the middle part of the second line the \color{red}{+} text to {\color{red}{+}}.

Answer 4

It seems v3 has some issues with bounding box of some expressions with exponents. Here are two examples I found now - notice the exponents being cut out:

source: 0\leq(x(x-a)(x-b))^{2^n}=-1.

(from https://math.stackexchange.com/a/2647669/290240 )

v3:

v2:

source: x^2+x-\zeta_{2^{n+1}} \equiv x^2+x-1 \in O_K/(\pi)[x]\cong \Bbb{Z/2Z}[x]

(from https://math.stackexchange.com/a/3340575/290240 )

v3:

v2:

I'm sure there are better examples around. I think I saw v2 doing this too but it was very rare, in current v3 beta I see it much more often.

Edit: I just noticed that the second example shows how v2 and v3 render the number two at the end differently. But I guess v3 is correct in this case, since \Bbb{} applies to the whole Z/2Z.

Answer 5

Certain special characters are not currently being handled appropriately with MathJax v3 beta. For example, the top part of Sea ships and their space-time equations, in MathJax v2, appears as:

However, with MathJax v3 beta, it now shows as:

i.e., "Math input error" is displayed instead for both equations. The editor display of that part of the question is:

What's interesting is that the problematic character displays as a space followed by a question mark enclosed in a square. However, this display isn't the same here, e.g., with

x ⃗
⃗

Instead, as you can see, it appears to be a small square (at least for me, with this being similar to how unsupported characters with the current font are displayed), and a small arrow when shown by itself. However, on MathJax supported sites like the Math meta one, the square box is displayed as an arrow as well! This is a Unicode character that causes a backspace and overlay, which is how the "x" with an arrow overtop of it is shown in the top MathJax v2 output. Note that one may get a very similar result using MathJax with $\vec x$ instead.

---

There are also other special characters that work in MathJax v2 but result in the yellow "Math input error" message with MathJax v3 beta. For example, in Revision 4 of Find the smallest constant $C$ with given condition., the OP used the Euro symbol character. Unlike the other character mentioned above, this one appears to always be displayed properly, e.g.,

$€$
€

I'm unsure about why this problem is occurring with certain characters in MathJax v3 beta. I checked, but didn't find, this issue in the Upgrading from v2 to v3 - MathJax 3.2 documentation Web page. My suspicion is that MathJax v3 may be trying to interpret them as being some sort of unrecognized special MathJax characters.

Answer 6

In v2, the quote characters “...” (U+201C and U+201D) display as themselves just like most other Unicode characters:

In v3, they are engorged into huge double stroke characters:

(The screenshots are from this MathOverflow question.)

Answer 7

With MathJax v2 it was possible to copy/paste a line containing MathJax into a plain Text editor. Of course this gives only a simplified representation.

For example, this is what I get when copying the title of this Math SE question on a Mac into a TextEdit window (raw format), or into BBEdit:

Determine a unit vector which is perpendicular to 2𝑖+𝑚𝑗−3𝑘 and parallel to 2𝑖+𝑗−𝑘.

With MathJax v3 I get only

Determine a unit vector which is perpendicular to and parallel to .

so apparently all math content is omitted from the copy.

Answer 8

Another preview bug: < followed by a letter inside a MathJax expression renders the rest of the paragraph invisible (as it is presumably misparsed as a start of an invalid HTML tag).

It works correctly in the final post, and it worked even in preview in v2.