Migration MathJax 3.1.2 to MathJax v.4
5 views
Skip to first unread message
akhil joshi
Nov 11, 2025, 5:24:14 AM (12 days ago) Nov 11
to mathj...@googlegroups.com
Hi Team,
Currently, we are using the CDN for MathJax v3.1.2
https://cdn.jsdelivr.net/npm/mat...@3.1.2/es5/tex-mml-chtml.js
to render MathJax HTML.
In this version, the rendered structure includes the predefined <math></math> tags.
However, when we switch to MathJax v4 using the CDN below:
https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js,the
<math> tag is no longer included in the rendered output. The structure we receive in v4 differs from v3. 
Could you please confirm if there are any configuration-level changes required for this behavior in v4?
Additionally, please let me know if any technical implementation updates are needed to support MathJax v4.
Thanks & Regards,
Akhil Joshi
Davide Cervone
Nov 11, 2025, 7:37:27 AM (12 days ago) Nov 11
to mathj...@googlegroups.com
Akhil:
MathJax v3 uses the assistive-mml extension to insert hidden MathML to support screen readers. It was a stop-gap measure used to get screen-reader support when MathJax's speech generation was not performant enough to be on by default. Users who wanted the full MathJax speech generation and expression explorer had turn them on themselves. In v4, the speech generation and expression explorer are on by default, and the assistive-mml option is off (though they can be controlled by the MathJax contextual menu). That is why you are seeing this difference in output. This is described in the "What's new in v4" documentation at
https://docs.mathjax.org/en/latest/upgrading/whats-new-4.0/explorer.html
While you can re-enable the assistive-mml output (and disable MathJax's own speech and Braille generation), I would not recommend that. The assistive-mml approach required a screen reader that understands MathML (not all do), and it was somewhat fragile even with a MathML-ready screen reader, and over time, as browsers and screen readers changed, it became less reliable. For example, VoiceOver on MacOS now does not read the math at all, and on Windows, screen readers say "clickable math", but do not read the math.
If you are looking to support screen readers, the v4 experience using MathJax's speech generation should be much better than the v3 one using assistive-mml.
Davide
On Nov 11, 2025, at 5:23 AM, akhil joshi <akkijo...@gmail.com> wrote:
Hi Team,
Currently, we are using the CDN for MathJax v3.1.2
https://cdn.jsdelivr.net/npm/mat...@3.1.2/es5/tex-mml-chtml.js
to render MathJax HTML.In this version, the rendered structure includes the predefined
<math></math>tags.
<image.png>
However, when we switch to MathJax v4 using the CDN below:
https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js,
the<math>tag is no longer included in the rendered output. The structure we receive in v4 differs from v3.
<image.png>
Could you please confirm if there are any configuration-level changes required for this behavior in v4?
Additionally, please let me know if any technical implementation updates are needed to support MathJax v4.
Thanks & Regards,
Akhil Joshi
--
You received this message because you are subscribed to the Google Groups "MathJax Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to mathjax-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/mathjax-dev/CAH43X8%2B_D%3DH72_%3D-frQA5ZR_Czp_D7zYqm6%3DmpRdFA3PbXDs7g%40mail.gmail.com.
Neil Soiffer
Nov 11, 2025, 9:32:49 PM (11 days ago) Nov 11
to MathJax Development
Davide,
I'm not sure where you heard about what works where, but it is wrong. For example, if you go to a Wikipedia page with either NVDA or JAWS, it reads the math well. I'm not an Apple person, so I can't speak about VoiceOver support being broken, but I'd be very surprised if that were true because I've not heard people complain about that and Apple is very proactive about its accessibility.
I just tried a MathJax V4 page. After fiddling with the menus to turn off MathJaX's reading and to turn on MathML inclusion and then force reloading the page (this requires a lot of menu navigation that is probably not easy for users who want to do this along with knowing that a reload is needed), it reads ok in both NVDA and JAWS. In NVDA, it does say "clickable". It doesn't do this for Wikipedia pages, so MathJax is generating something that is triggering NVDA to say "clickable" -- JAWS doesn't say this. I thought that there might be a bug report about this in the issue tracker for NVDA, but I don't see one. If you're willing to potentially change the MathJax output, I can look into why NVDA is saying "clickable" and might be able to suggest changes to prevent that, or fix NVDA if that is where the issue lies.
There are very good reasons for people wanting to use the screen reader to read the math rather than MathJax. These include better speech (that can be subjective), better braille support (objectively less buggy and support for more braille codes in screen readers), and the ability to hear math the same way that they hear it in non-web contexts such as Word and PDF documents (now fully accessible when generated from Word or the new luatex/pdftex versions).
I think not generating MathML in the default configuration is an accessibility regression. Probably half the US now uses UEB for math, as does most of the rest of the English speaking world. I imagine that as sites start to use v4, teachers will not be happy having to configure MathJax for each of their students and for each site they use if they are UEB users. The same is true for people who aren't Nemeth or LaTeX braille users.
Neil
Davide Cervone
Nov 18, 2025, 7:39:01 AM (5 days ago) Nov 18
to mathj...@googlegroups.com
Neil:
I'm not sure where you heard about what works where, but it is wrong.
I got it from my own testing.
I'm not an Apple person, so I can't speak about VoiceOver support being broken, but I'd be very surprised if that were true because I've not heard people complain about that and Apple is very proactive about its accessibility.
Well, prepare to be surprised, then, because it is pretty flakey. For example, I used the following file
<!DOCTYPE html><html><head><title>Testing Screen Readers</title></head><body><div style="padding: 1em; width: 25em; font-size: 200%; line-height: 2"><p>If<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>a</mi><mo>≠</mo><mn>0</mn></math>,then<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup><mo>+</mo><mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi><mo>=</mo><mn>0</mn></math>has two solutions,<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>x</mi><mo>=</mo><mrow data-mjx-texclass="ORD"><mfrac><mrow><mo>−</mo><mi>b</mi><mo>±</mo><msqrt><msup><mi>b</mi><mn>2</mn></msup><mo>−</mo><mn>4</mn><mi>a</mi><mi>c</mi></msqrt></mrow><mrow><mn>2</mn><mi>a</mi></mrow></mfrac></mrow><mo>.</mo></math></p></div></body></html>
with pure MathML and no MathJax at all and tested various screen reader/browser/os combinations. I'm linking to screen captures of the results below.
For VoiceOver in Safari, I first Use VO-A to read the full page. Note that the math is skipped entirely. Then I go back to the beginning and use VO-right-arrow to move through the page a piece at a time. It does that well. Then I use up-arrow to move back to the previous line, and it reads the MathML text content, but not as math (note that the "ax^2" be comes "a x 2").
A similar test in Firefox works the same for VO-A, but now even the VO-right-arrow doesn't work properly (notice the incorrect voicing of the fraction in the displayed equation).
On Ubuntu Linux with ORCA in Firefox, the math is read as plain text (again, "ax^2" becomes "a x 2", and the fraction and root are not voiced correctly), and stepping through the page with the down arrow key produces rather garbled results.
In Chrome, the results are worse, as (for some reason) the page title is read after each math expression when reading the page in full, while when stepping, the letters are voiced with a preceeding "italic", and many of the symbols are left out (e.g., "a ≠ 0" is read "italic a not equal to" without the "0").
On Windows, with NVDA out of the box, the math is skipped (this screen capture is from Edge, but it is the same in Firefox and Chrome).
You will say that that is not fair, and that NVDA needs a plugin to handle MathML. That may be true, but that is an extra step that users need to take (and know about), and there is no indication in the page being read that that is required. How is a novice user to know this?
I admit that JAWS did better than I remembered (perhaps the update this spring improved it), as it did read the page well, but the "synchronized" highlighting was not very accurate:
For dyslexic users, for example, who are using the highlighting to help them read that page, I would think that would be rather confusing.
After fiddling with the menus to turn off MathJaX's reading and to turn on MathML inclusion and then force reloading the page (this requires a lot of menu navigation that is probably not easy for users who want to do this along with knowing that a reload is needed), it reads ok in both NVDA and JAWS.
I have made a pull request to simplify the menu switching so that only one menu choice is needed to make the change (selecting the hidden-MathML option will turn off MathJax's speech and Braille generation, and conversely, turning on speech or Braille will disable the hidden MathML insertion). It's true that that was more complicated than necessary, so this change should be a useful one.
A page reload should not be necessary. When I turn off speech and Braille and turn on the hidden MathML, the page updates properly for me without a reload.
In NVDA, it does say "clickable".
Yes, that is due to the fact that the MathJax output has an attached menu and is focusable in order to be able to access that. The "clickable" is NVDA's indication for that. Since Wikipedia doesn't use MathJax live in the page (it uses MathJax server-side to generate the MathML), the menu is not available, and the math isn't focusable, so no "clickable".
I think not generating MathML in the default configuration is an accessibility regression.
I understand your viewpoint, but while it can be made to work reasonably well on Windows, that is not the only platform we need to consider, and it simply doesn't work in MacOS or Linux reliably enough to use that as the default. MathJax's output works in all the situations I listed above out of the box. I know you have a vested interest in web pages using MathML, but MathJax gives you the option of doing that (and it will be easier in the next release, and I will add text to the MathJax help dialog to make how to do that clearer). The fact that MacOS and Linux don't work well with the MathML, as illustrated in the links above, or that one needs additional plugins to handle it, is a dealbreaker for us, and we are not willing to make it the default at this point.
Davide
Reply all
Reply to author
Forward
0 new messages