Wikipedia talk:WikiProject Mathematics/MathFormattingBugs

Hello all. I'm the product manager at the Wikimedia Foundation for the math rendering change tracked in T271001. I'm opening this thread so the status is visible here and not only on Phabricator, and so there is one place on-wiki to discuss which issues matter most.

Looking at the frequency of \boldsymbol{\Omega} the articles I found it impacts are

    24 Hund's cases
    19 Matrix t-distribution
    15 Rotating reference frame
     4 Nonlinear regression
     4 Fictitious force
     3 Linear least squares
     2 Vorticity
     2 Rotating spheres
     2 Magnetorotational instability
     1 Rigid body dynamics
     1 Generalized least squares

With some quite important articles. This should be an easy fix T435385 but I can understand why its low priority, with a small impact in number of articles. Hopefully, the articles will be self consistent, using the same symbol throughout the article. Salix alba (talk): 14:58, 3 November 2026 (UTC)Reply

You need to also look for \mathbf{\Omega} and variants without the curly braces (and of course also other Greek letters). –jacobolus (t) 20:18, 4 November 2026 (UTC)Reply

I would like to clarify why the roll-out is happening now and why it couldn’t wait:

TL;DR; Today's default, server-side SVG math rendering, depends on RESTBase. The Foundation is retiring RESTBase because its code is end-of-life and its design causes problems (details below) and the server-side rendering math component is tightly coupled with RESTBase. The new default, client-side SVG removes the separate service and the stored SVG files, so MediaWiki can render math on its own (reasons). Native MathML, the first option, doesn't look the same in every browser, and was set aside in 2024. Some rendering problems remain and they are being fixed, the most severe ones first.

What "server-side SVG" depends on. Today's default works like this:

• the Math extension sends each formula to a service called Mathoid, through a service called RESTBase;
• Mathoid draws the SVG image;
• RESTBase stores the result in a Cassandra database (T179419).

This has been the default since June 2016 (Tech News 2016/23).

Why RESTBase is going away.

• The Foundation decided in 2019 to retire RESTBase (mw:RESTBase/deprecation, T262315) to remove the need to support a complex piece of service architecture replacing it with a well supported third party application reducing cost of ownership. The RESTBase code is now end-of-life, and it depends on old versions of npm packages increasing the security risks over time.
• Since then, every other feature that used RESTBase has moved off it. These include Parsoid, the page content service, the visual editor API and the mobile endpoints (see the subtasks of T262315). Math is one of the last remaining users.
• The public Math API (/api/rest_v1/media/math/) has been deprecated since 31 August 2026. Its announced sunset date was 28 September 2026 (Tech News 2026/36, T431372). Server-side SVG on English Wikipedia is already running on endpoints past their announced end date.

To be precise:

• the old path runs through an unmaintained Node.js service with outdated dependencies;
• as of late September, some of the servers behind it were still waiting to move off Debian 11, which lost security support on 31 August 2026 (T401694, Debian announcement) and upgrading requires spending unnecessary resources and big efforts on a deprecated functionality.

The old path also fails in front of readers. Since 2016, editors have reported formulas replaced by "Failed to parse … Math extension cannot connect to Restbase" on the technical village pump at least nine times. See archives 147, 152, 170, 203, 207, 210 and 218.

Timeline of the project: The replacement was chosen two years ago by the maintainers of the Math extension on Phabricator (T338429, T271001), on mediawiki.org (Native MathML rollout, Reported Cases), and on WikiProject Mathematics (2024, 2025, the bug page). The plan changed several times along the way and most recently we have been fixing severe and impactful issues to increase the confidence to proceed.

• Sep 2024: the plan was native MathML as the default (T271001). This project raised serious rendering problems (WT:WPM, Sep–Oct 2024). Because of that, native MathML did not become the default.
• 2024–2026: the Math extension's maintainers tracked reported cases in public, on Native MathML/Reported Cases and on the beta test page Help:MathTestNative, and fixed them in the LaTeX-to-MathML converter. See T271001.
• Nov 2025: client-side SVG was proposed instead. It draws MathJax's TeX-style rendering the same way in every browser (WT:WPM, Nov 2025).
• Aug 2026: the switch was announced in Tech News 2026/33 and discussed here. That discussion started the bug page on 10 August, and it has collected reports since then.
• Aug–Oct 2026: further announcements in Tech News 2026/36 and 2026/45, and a VPR discussion on alignment.
• The dates announced in August moved to 2 November so that the most severe problems reported on the bug page could be fixed first, taking into consideration a prioritization framework built on top of the community reports.

Why not keep server-side SVG for a few months. Keeping it means keeping RESTBase, Mathoid and their servers running past their announced end dates, which we can’t do due to the related security concerns. This is a transition period and we will continue to polish client-side rendering with MathJax as the remaining problems are being fixed ASAP. MSantos (WMF) (talk) 10:19, 6 November 2026 (UTC)Reply

These decisions are not technically competent, were not made with any input from the people actually affected by the changes, and the timelines here have been a total failure on every level. Let me elaborate:

1. There is no inherent reason why "RESTBase" in particular must be used with the previous general approach to rendering mathematics. RESTBase is a generic caching proxy and has nothing to do with math rendering per se; for our math rendering RESTBase is an incidental infrastructure component which can be replaced by some other component serving the same function (some such component is surely already in use for other aspects of mediawiki).
2. There is no inherent reason why the previously used version of MathJax (v. 2) needed to persist as the way Wikipedia rendered math on the server side. An upgrade to version 4 could surely have been done without fundamentally changing the system architecture.
3. The "plan" to use "native MathML" was always a misguided pipe dream. Browser implementations of MathML are limited, buggy, inconsistent, and in relatively rapid flux, meaning that getting sufficient support across all necessary browser versions is many years away and quite possibly may never be adequate. MathML is fundamentally different from LaTeX in many ways, so LaTeX markup cannot be converted 1:1 to MathML, and various kinds of more-or-less hacky workarounds are required to get something that sort of almost works. This was never a reasonable thing to depend on for a project like Wikipedia, and it was only a "plan" because it was a few volunteer developers' hobby project. They were repeatedly told by Wikipedians that their "plan" was unworkable, but did not want to listen. Someone with enough perspective and technical competence to reject this plan outright should have done so several years ago (in 2022 or whenever) instead of letting these developers waste large amounts of effort on an idea that was doomed to failure from the start. But persisting with a variant of that plan now is succumbing to a sunk cost fallacy; as the saying goes, you're "throwing good money after bad".
4. "client-side SVG was proposed instead" – The Mediawiki developers / WMF planners made a comment or two on Wikipedia but then stopped engaging, left questions hanging, and never actually discussed either their plan or Wikipedians' needs in detail.
   This was pitched as something like "let's use MathJax on the client side", but what is actually being done is something entirely different: We are using a brand new piece of PHP software on the server written by a tiny number of people, untested, with no production use outside of Mediawiki, to convert LaTeX markup to MathML, and then as a second step (on the client) using MathJax to convert that MathML to SVG, something MathJax itself is not intended to be used for. That PHP program has many significant inconsistencies with the way it interprets LaTeX markup compared to either MathJax or LaTeX itself. This technical approach is complicated, nonstandard, and creates a large maintenance burden. It leaves us with LaTeX rendering which doesn't match LaTeX and also doesn't match any version of MathJax. It ties us to relying on a particular version of MathJax because future internal MathJax changes are likely to break our new program. It prevents us from taking advantage of many (most?) new MathJax features and improvements. It causes confusion for anyone trying to understand how our math rendering works in detail, because they need to trace through multiple code bases in different languages which were duct taped together.
   If we want to use MathJax on the client side, we should be sending LaTeX markup to the browser running MathJax the way MathJax is intended to be used, with some custom commands implemented for backwards compatibility with our previous pipeline. Alternately, we should be running one component of MathJax on the server side to convert LaTeX markup to MathJax's own internal math representation (which is based on MathML, but as far as I understand has various extensions because MathML by itself is insufficient to do the job) and a second MathJax component on the client to convert MathJax's internal representation to SVG. There is no good reason to include the new PHP program in this rendering pipeline.
5. "continue to polish" – there are still a long list of things which are essentially broken. This should be characterized as "continue to fix the many serious bugs" rather than "continue to polish".
6. If it was decided to get rid of RESTBase 7 years ago, we shouldn't be setting deployment deadlines of days or weeks, and we shouldn't be deploying broken buggy code because 1 or 2 people decide that they don't personally think the bugs matter. That's bad planning, bad time/resource management, and horrendously bad communication.
   The relevant stakeholders should have been gathered to discuss 5–6 years ago (or whatever), with fair consideration of all possible technical approaches, some kind of consensus decision reached (not just by a few people acting alone without consulting anyone) and any development project should have had well spaced required milestones to demonstrate that the current plan was on track, and possibly even multiple ideas should have been pursued in parallel so that if one failed we wouldn't be left without any backup plan. A large collection of test cases should have been set up years ago, with developers doing careful checking of every feature and every basic combination of features, instead of relying on Wikipedian volunteers to hunt for bugs under imminent threat. All nontrivial known bugs and regressions should have been fixed before a firm schedule was even set for deployment. Relevant stakeholders should need to agree that changes are not serious regressions. Technical decisions should be made in public discussion rather than secret back-room meetings.

–jacobolus (t) 18:52, 6 November 2026 (UTC)Reply

Given that there is such a big change, I wonder why the problems with the old rendering are still there, such as "\lvert not defined", "\overset does not preserve spacing", etc. 慈居 (talk) 14:49, 7 November 2026 (UTC)Reply

I think they tried to support exactly the LaTeX commands which were previously supported, though I'm not really sure how the various technical decisions were made: as far as I know there are no published design documents or anything of the kind. What's the \overset issue? –jacobolus (t) 18:36, 7 November 2026 (UTC)Reply

If you put something over a relation or binary operation using \overset or \stackrel, it does not give proper spacing any more:

• (a\overset{a}{\sim}b) (compare )
• (a\stackrel{a}{\sim}b)
• (a\overset{a}{+}b) (compare )
• (a\stackrel{a}{+}b)

This was so even in the old days and is unique to MediaWiki. Perhaps I can add this to this page?

Before the change here, they have changed math rendering (forced pure MathML rendering) in Wikidata without asking community opinion. Then I realized that I am interested in editing only when things are presented in a visually pleasant way. 慈居 (talk) 03:37, 8 November 2026 (UTC)Reply

Definitely a bug if \stackrel does not use the the same spacing as a relation (like ⁠⁠, ⁠⁠, ⁠⁠, etc.). (Edit: I guess \stackbin is not a default command, but is provided by the 'stackrel' package.) It seems like \overset is supposed to automatically pick the right spacing based on its content, so if we aren't doing that it's also a bug. We should match the behavior or LaTeX. We should also be able to use \mathbin, \mathrel, etc. on arbitrary content to get the expected spacing, but that is currently broken in the new renderer. In my opinion that should also be a high priority to fix, in part because it hints at more fundamental problems with the way LaTeX is being rendered. –jacobolus (t) 21:49, 8 November 2026 (UTC)Reply

I added rows about this issue to the bug list. –jacobolus (t) 22:49, 8 November 2026 (UTC)Reply

Yes, spacing affects underlying semantics of formulas and so should be considered of high priority. I'm worried that under this asserted priority criterion the overset/stackrel/... issue gets only low priority because they are old problems. (Actually \mathbin, \mathrel, etc. you mentioned were handy workaround before, so the situation is indeed "worse than before".) I think, now that they are working on math rendering, it's a good time to fix the bugs, old and new. 慈居 (talk) 03:14, 9 November 2026 (UTC)Reply

One persistent and extremely annoying old bug that remains unchanged after this rendering change: one cannot use mathematical formulas (formatted with <math>) in image captions because clicking on the image produces an expanded view with a broken caption. I was hoping that mathematics rendering would be different enough to fix this but no. For some reason this has been prioritized as "low" and open since 2020: https://phabricator.wikimedia.org/T263572 . This neglect is not a good omen for a quick resolution to the other rendering bugs now that the new renderer has been forced through. —David Eppstein (talk) 06:47, 9 November 2026 (UTC)Reply

I mentioned it in T271001 (coincidentally before it was mentioned here), in case that helps. –jacobolus (t) 08:16, 9 November 2026 (UTC)Reply

Somehow I've managed to set up a guideline in a sister Wikipedia which explicitly says that we do not disallow <math> in

• image captions,
• section headings (causing broken table of contents and edit summary),
• introductory sections (which may break article preview),
• CS1 citation templates (which conflicts with the templates themselves and now probably with reference preview),

and so on, despite all these bugs. Math in raw HTML has, among other things, accessibility concerns. 慈居 (talk) 08:56, 9 November 2026 (UTC)Reply

Well. Let's discuss accessibility concerns, shall we?

When I use MathJax (in its default vanilla mode with LaTeX input) on my blog, I get a formula made out of elements that I can select individually to cut and paste. Control-clicking or left-clicking on any formula produces an accessibility menu whose options include more than one level of text to speech. (This would normally happen on a click without even needing to control-click, but I disabled that because it interferes with external links that include formulas.)

When I use "client-side SVG" rendering on Wikipedia, I get a single rendered image. Using my browser's "accessibility inspector" on that image appears to show that it has no alt text. The Wikipedia editing preferences, in the mathematics section under appearance, include a checkbox labeled "Explain mathematical formulae on hover", but to me it appears to have no effect: nothing happens when I hover over a mathematical formula.

Where is the accessibility that we were promised this new rendering method would give us? —David Eppstein (talk) 19:22, 11 November 2026 (UTC)Reply

I suspect this kind of thing should be possible with the current approach, but is likely more difficult and brittle than if we adopted MathJax more directly. It's not clear what kind of resources the WMF is willing to devote to such projects. –jacobolus (t) 22:18, 11 November 2026 (UTC)Reply

Another thing that should now be relatively straightforward now that we are inlining math SVG (much easier than using the previous SVG-as-separate-image approach) is getting mathematical notation nested inside a wikilink or external link to take the appropriate (visited or unvisited) link color, using fill="currentColor" and stroke="currentColor". This would make an immediate improvement by taking away the downside of using LaTeX in links. The same changes might also fix any issues with "dark mode" color schemes. –jacobolus (t) 22:21, 11 November 2026 (UTC)Reply

If we were just using MathJax as MathJax instead of using it to create client-side SVG images, then highlight coloring would happen automatically. —David Eppstein (talk) 00:55, 12 November 2026 (UTC)Reply

+ I hope they make sure that latest versions of NVDA, JAWS, etc. (which support reading MathML anyway) work for the new rendering (did they work in the old rendering?), also take a look at situations in which low internet speed causes MathJax to fail to load.

These are all necessary and urgent fixes, I think. What should be optional is something like introducing new fundamental features, such as drawing commutative diagrams or defining custom macros. 慈居 (talk) 08:01, 12 November 2026 (UTC)Reply

I don't think our screen reader support has ever been particularly effective, but I'm not a screen reader user. –jacobolus (t) 15:13, 12 November 2026 (UTC)Reply

I think the saner option is to render everything fully client-side. The biggest argument against it was the large JS payload. Currently the Math extension sends 456kb of JS for MathJax (compressed, 1291kb uncompressed) to the browser on any page with math formulas, while a simple client-side js snippet is only 325kb compressed, so the size argument no longer holds. Client-side js through a gadget also has a few more advantages:

1. There is 0 upkeep from the WMF besides changing $wgDefaultUserOptions so that the source LaTex is available to everyone by default and can be rendered by the gadget. Less work for the WMF.
2. The community no longer needs to keep complaining to the WMF whenever they encounter issues. Any issue encountered can be fixed by bugging an interface administrator on enwiki.

So in the end it's a win for the community and a win for the WMF, which is not surprising because this is the decision every downstream wiki makes when they don't like a particular feature but don't want to go through the process of contacting upstream. If the extension developer and the enwiki math community cannot reach agreement, a client-side gadget allows both to have things their own way: the extension developer can implement features as they like; enwiki can render formulas however they like. PetraMagna (talk) 01:08, 13 November 2026 (UTC)Reply

In anticipation of some of the concerns which may be raised:

1. Accessibility. MathJax emits accessibility tags with the source LaTex. Since the JS snippet sets assistiveMml: true when loading MathJax, I would trust MathJax to do its job.
2. How easy is it to fix issues? As an example Special:Diff/1385378883 fixed T263572. It's a brittle solution in that if MMV changes the DOM layout the script may no longer work against it, but I think a brittle fix is better than no fix at all. And to address this fully MMV just needs to provide a JS hook.
3. Security, particularly the CSP. Well, MathJax4 JS just needs to be moved from jsdelivr to somewhere on the CSP whitelist and be updated semi-frequently for security fixes. It's a few minified JS files so I don't see an issue there. In fact it can probably use the MathJax4 files bundled with the Math extension? I need to look into this to find out.

PetraMagna (talk) 01:32, 13 November 2026 (UTC)Reply

@Pppery: Not sure if you are interested in this conversation but you are the only enwiki IA I know. I'm wondering what your thoughts are on this proposal. Are enwiki IAs willing to introduce a gadget like this if the math community prefers this solution? PetraMagna (talk) 01:38, 13 November 2026 (UTC)Reply

It's not completely out of the question, especially given that we now have template gadgets so this could be done without loading any JS on pages that don't contain math. It took a lot of time for me to get enough context to understand what the gadget would do (my first thought was "why would you replace one JS renderer with another?"), so if you want to propose this to the community at large you'll need a clearer explanation.

I think it would be a shame the enwiki community and the Math extension maintainers were so at odds that it had to come to that, but then I've always been an advocate for radical iadmin acton in times like those. * Pppery * _{it has begun...} 02:13, 13 November 2026 (UTC)Reply

Thanks for the feedback! I was not aware of this conversation until I read David Eppstein's blog, so yeah there is a sizable amount of background information and old conversations dating many years ago which led to the present situation. I can't say I know much about math rendering on enwiki, but I do think that if the math situation is bad enough to deserve a blog post, then we should at least try the gadget solution.

As for conditionally loading the gadget, the biggest obstacle would be uses of the bare <math> tag without a template, which emits no categories and is therefore very hard to track. The current JS payload is small. It only loads MathJax when LaTex is detected on the page, so the biggest overhead is a single querySelectorAll on the tex class, which is negligible. However, if the JS does get longer as more fixes are pushed to it, this could conceivably lead to more network requests on all pages for all users. I can think of 2 possible solutions:

1. Let the Math extension emit a category whenever the <math> tag is used. This requires cooperation from the extension developer, who may not like the idea of helping enwiki move away from the extension's intended use. But maybe the radical idea of replacing built-in rendering from the extension with a gadget will prompt the extension maintainer to re-consider the needs to the enwiki community? And then we can get good math rendering from the extension again without the laborious path of creating a gadget?
2. Use something along the lines of

   if (document.querySelectorAll('.tex')) {
       // Load both the main math handling script and MathJax here
   }
   

   which would minimize the JavaScript payload sent to every page. This is not ideal but at least the size will be kept in check, as the more complicated logic is tucked away in another script. PetraMagna (talk) 02:42, 13 November 2026 (UTC)Reply

Template gadgets do not work in the Android and IOS mobile apps. That seems like a showstopper to me. —David Eppstein (talk) 02:44, 13 November 2026 (UTC)Reply

Yeah this seems to be reproducible for the 2 gadgets I tried, so the only remaining option is to load it on every page, but convincing others that they need to load 500 bytes of math-handling JS for every page would be a challenge, even if it is negligibly small.

So I guess the other option is to convince upstream to add a 4th rendering mode and, if it ever becomes mature enough, switch to it. This may not be too difficult as most of the code path is identical to the "LaTex source" mode with only some additional JS. I will file this on Phabricator since this migration away from RESTBase affects downstream as well. PetraMagna (talk) 22:05, 13 November 2026 (UTC)Reply

What is "radical iadmin action"? –jacobolus (t) 03:21, 13 November 2026 (UTC)Reply

I think it's referring to replacing functionalities from a WMF extension (in this case Math) with a gadget. This is a last resort because the typical response to a WMF change is to complain instead of fixing it locally with a gadget. PetraMagna (talk) 23:48, 13 November 2026 (UTC)Reply

Filed T444884 for introducing this in the extension. PetraMagna (talk) 23:45, 13 November 2026 (UTC)Reply