feat(mathjax): upgrade mathjax from v2 to v4 by navinkarkera · Pull Request #270 · openedx/xblocks-core

navinkarkera · 2026-06-29T06:10:51Z

Summary

Upgrade MathJax from v2.7.5 → v4.1.2 across all XBlocks (problem, discussion, html). The v2 MathJax.Hub.Queue(...) / .Hub.Config() / .Hub.getAllJax() API is removed upstream. This PR ports all JS interactions to v4's MathJax.typesetPromise() / MathJax.typesetClear() / MathJax.startup.promise API.

Co-authored by: GPT 5.5(xhigh)

Manual testing

See openedx/openedx-platform#33555

Risks

Host dependency: xblocks-contrib expects the host platform (edx-platform) to provide MathJax v4 with input/asciimath loaded. Its own mathjax_include.js is a guarded fallback (if (typeof MathJax === 'undefined')). If the host changes config without enabling AsciiMath input, formula preview (backtick-delimited syntax) breaks silently.
noerrors package: Loaded in config; silently swallows MathJax rendering errors. Same behavior as v2, intentional.
messageStyle: "none" not ported — v4 may show brief "Loading MathJax..." overlay. Cosmetic only.

Merge checklist:
Check off if complete or not applicable:

Version bumped
Changelog record added
Documentation updated (not only docstrings)
Fixup commits are squashed away
Unit tests added/updated
Manual testing instructions provided
Noted any: Concerns, dependencies, migration issues, deadlines, tickets

openedx-webhooks · 2026-06-29T06:10:57Z

Thanks for the pull request, @navinkarkera!

This repository is currently maintained by @openedx/axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

Migrate MathJax v2 Hub.Queue/Hub.getAllJax/Callback APIs to v3/v4 startup.promise/typesetPromise/typesetClear in Problem display.js, formula_equation_preview.js, and HtmlBlock init. - Problem.display.js: replace Hub.Queue(Typeset) with startup.promise.then(typesetPromise), Hub.getAllJax with startup.document.getMathItemsWithin, jax.root.toMathML with startup.toMML - Formula equation preview: replace Hub.signal.Interest/Queue/getAllJax with startup.promise.then(typesetClear; textContent; typesetPromise) - HtmlBlock: call typesetPromise on student_view load - Bump version to 0.17.1

Update display_spec.js and formula_equation_preview_spec.js MathJax mocks from v2 (Hub.Queue, Hub.getAllJax, Startup.signal.Interest, Callback.After, jax.root.toMathML) to v3/v4 (startup.promise synchronous mock, typesetClear, typesetPromise, startup.toMML, startup.document.getMathItemsWithin).

navinkarkera · 2026-09-04T06:23:31Z

@feanil @OmarIthawi Please review and merge this.

OmarIthawi · 2026-09-09T09:11:47Z

@navinkarkera are the screenshots in the platform PR (openedx/openedx-platform#33555) is the same here?

Why do we need two places to render the same equations? I understand this is an old decision, but it helps to know why.

navinkarkera · 2026-09-09T09:39:11Z

@OmarIthawi Some xblocks have been moved here from openedx-platform, including html and problem blocks that also render mathjax equations so we need to upgrade Mathjax configuration here.

OmarIthawi

Thanks @navinkarkera. It's a pretty dense PR, reviewing it is hard but to be fair no objections from me here.

feanil

Did a quick Claud assisted review, just a couple of smaller issues but not to major.

feanil · 2026-09-16T19:30:04Z

+            }
+            if (!mathSpan) {
+                mathSpan = document.createElement('span');
+                mathSpan.className = 'mathjax-preview';


ProblemBlockDisplay.css:1049-1051 styles this box with span.MathJax_CHTML, span.MathJax, span.MathJax_SVG, and line 1035 uses .MathJax_Display. v4 emits <mjx-container class="MathJax" jax="CHTML">, a custom element, so none of those match. MathJax_Display, MathJax_CHTML and MathJax_SVG appear zero times in the 4.1.2 bundle. The bordered grey box disappears from every formula-equation preview.

Both preview paths end with a mjx-container inside div.equation, this one and the <textline math="1"> path where display.js typesets into div#display_<id>.equation, so one selector covers both:

div.equation mjx-container[display="true"] { width: auto; } div.equation mjx-container { padding: 6px; min-width: 30px; border: 1px solid #e3e3e3; border-radius: 4px; background: #f1f1f1; display: inline-block; }

display: inline-block moves onto that rule because div.equation span used to catch the v2 span wrappers and mjx-container is not a span.

feanil · 2026-09-16T19:30:04Z

 };

+// MathJax v3/v4 exposes readiness and typesetting through startup/typesetPromise.
+const isMathJaxTypesetReady = () => typeof MathJax !== "undefined" && MathJax !== null


On a host still serving MathJax v2 these guards silently do nothing, so problem, html and discussion math stops rendering with nothing in the console.

Don't cut a release from this until openedx-platform#33555 has landed.

feanil · 2026-09-16T19:30:04Z

+    || (/^\s*\\\[/.test(eqn) && /\\\]\s*$/.test(eqn))
+    || (/^\s*\$\$/.test(eqn) && /\$\$\s*$/.test(eqn))
+    || (/^\s*\$[^$]/.test(eqn) && /[^$]\$\s*$/.test(eqn));
+  math.textContent = isTexDelimited ? eqn : `\`${eqn}\``;


This is the branch every existing <textline math="1"> problem takes, and it only renders if the host loaded input/asciimath. That jax is not in tex-mml-chtml.js, it is fetched on demand, so a host that omits it breaks every formula preview with no error. The risk section on this PR says the same thing.

Add a one-time console.warn when MathJax.startup is present but the AsciiMath input is not registered.

feanil · 2026-09-16T19:30:04Z

+      expect(MathJax.typesetPromise).toHaveBeenCalled();
+    });
+
+    it("preserves backslash-delimited TeX without wrapping in AsciiMath backticks", function () {


Add the matching case for plain input. Nothing asserts that E=mc^2 becomes `E=mc^2`, and that is the branch all existing content goes through. The TeX branch is new behavior and has a test, the one carrying the back-compat does not.

feanil · 2026-09-16T19:30:04Z

+    const dynEl = document.getElementById(`${element.id}_dynamath`);
+    if (dynEl) { dynEl.value = MathJax.startup.toMML(jax.root); }
  } catch (exception) {
    if (!exception.restart) {


exception.restart was a MathJax.Callback concept with no v4 equivalent, so this branch is dead. Drop the condition or drop the catch.

feanil · 2026-09-16T19:30:04Z

+    return;
  }
+  // Use getElementById so IDs with : or . do not break as CSS selectors.
+  const math = document.getElementById(`display_${elid}`) || document.getElementById(`${element.id}_preview`);


989ae32 removed formula-equation inputs from the keyup binding, so <id>_preview is unreachable here. Drop the fallback.

openedx-webhooks added open-source-contribution PR author is not from Axim or 2U core contributor PR author is a Core Contributor (who may or may not have write access to this repo). labels Jun 29, 2026

openedx-webhooks added this to Contributions Jun 29, 2026

github-project-automation Bot moved this to Needs Triage in Contributions Jun 29, 2026

navinkarkera mentioned this pull request Jun 29, 2026

feat!: upgrade to mathjax v4 openedx/openedx-platform#33555

Open

navinkarkera force-pushed the navin/mathjax-v4 branch from 60e1f68 to 56660c7 Compare June 29, 2026 10:38

navinkarkera marked this pull request as ready for review June 29, 2026 15:50

navinkarkera requested review from OmarIthawi and feanil June 29, 2026 17:22

mphilbrick211 moved this from Needs Triage to Ready for Review in Contributions Jul 6, 2026

navinkarkera added 7 commits July 31, 2026 11:42

fix(discussion): support MathJax v4

378f6c5

fix(mathjax): stabilize v4 xblock rendering

48e8f20

fix(mathjax): stabilize v4 xblock rendering

2ca5e3d

fix(mathjax): restore tex-delimited input detection in problem display

ea22077

fix(mathjax): stop refreshMath binding on formula equation inputs

989ae32

navinkarkera force-pushed the navin/mathjax-v4 branch from f271052 to 989ae32 Compare July 31, 2026 17:04

Merge branch 'main' into navin/mathjax-v4

d02d862

OmarIthawi approved these changes Sep 9, 2026

View reviewed changes

feanil reviewed Sep 16, 2026

View reviewed changes

Navigation Menu

feat(mathjax): upgrade mathjax from v2 to v4 - #270

feat(mathjax): upgrade mathjax from v2 to v4#270
navinkarkera wants to merge 8 commits into
openedx:mainfrom
navinkarkera:navin/mathjax-v4

navinkarkera commented Jun 29, 2026 •

edited

Loading

Uh oh!

openedx-webhooks commented Jun 29, 2026 •

edited

Loading

Uh oh!

navinkarkera commented Sep 4, 2026

Uh oh!

OmarIthawi commented Sep 9, 2026

Uh oh!

navinkarkera commented Sep 9, 2026

Uh oh!

OmarIthawi left a comment

Uh oh!

feanil left a comment

Uh oh!

feanil Sep 16, 2026

Uh oh!

feanil Sep 16, 2026

Uh oh!

feanil Sep 16, 2026

Uh oh!

feanil Sep 16, 2026

Uh oh!

feanil Sep 16, 2026

Uh oh!

feanil Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

navinkarkera commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Manual testing

Risks

Uh oh!

openedx-webhooks commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

navinkarkera commented Sep 4, 2026

Uh oh!

OmarIthawi commented Sep 9, 2026

Uh oh!

navinkarkera commented Sep 9, 2026

Uh oh!

OmarIthawi left a comment

Choose a reason for hiding this comment

Uh oh!

feanil left a comment

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

feanil Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

navinkarkera commented Jun 29, 2026 •

edited

Loading

openedx-webhooks commented Jun 29, 2026 •

edited

Loading