feat!: upgrade to mathjax v3 by navinkarkera · Pull Request #33555 · openedx/openedx-platform

navinkarkera · 2023-10-22T09:31:57Z

Description

Upgrades mathjax from version 2 to 3.2.1. MathJax v3 is a complete rewrite of MathJax with changes in its internal structure so it is not a drop in replacement to v2.

This PR implements the changes required to make use of v3 and still have the same functionality as before and hopefully without breaking anything.

Useful information to include:

This will impact both learners and course authors.
There are no changes in UI

Supporting information

Private-ref: BB-7992
MathJax v2 to v3 upgrade document

Testing instructions

Setup master devstack
Start lms, cms and frontend-app-learning using make {lms,cms,frontend-app-learning}-up.
Checkout this PR/branch and run make {lms,cms}-static.
Restart lms and cms using make {lms,cms}-restart to make sure new static files are served.
Visit studio on http://localhost:18010/
Go to Network tab in console and search for mathjax to make sure that mathjax v3 is being loaded.
Go to demo course and create a new unit.
Add a following components:
- Problem > numerical input
- Problem > advanced > Math expression input problem
- Text > Raw HTML: add \[\mathbf{x}^{G} = \frac{1} {M}\sum^{3}_{i=1}m_i\mathbf{x}^{G}_i\] formulae in the text.
In the problem blocks input field try adding some asciimath formulas, for example: R_1*R_2/R_3, A*x^2 + sqrt(y). Make sure preview works as expected.
Go to unit with title Mathematical Expressions in second section and play with the input field. In this field you can also enter tex as it is directly converted by MathJax while numerical input problems use a python library called calc to parse the text first and they cannot parse tex.
Go to next section with title Chemical Equations, play with the input field.
Publish the changes and click on View Live Version button and test above blocks again in LMS.
To test mathematical expressions in discussions, go to discussions tab and create a post. Add some text with math and tex formulas.
- Remember to escape backtick with \, example: \`A*x^2 + sqrt(y)\`
- Escape \[ and \( with additional \ for tex commands, example: \\[A \cdot x^2 + \sqrt{y}\\], \\(A \cdot x^2 + \sqrt{y}\\)
Repeat above tests with and without this PR changes, i.e. with MathJax v2 and v3.

Please let me know if we are using mathjax in some other components which we need to test.

Deadline

None

Other information

None

openedx-webhooks · 2023-10-22T09:32:03Z

Thanks for the pull request, @navinkarkera!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform.

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.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

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.

CefBoud · 2023-10-26T14:23:34Z

@navinkarkera Great work on this!
Mathjax2 is also used in frontend-app-library-authoring. Can you please take a look?

navinkarkera · 2023-10-26T15:28:02Z

Mathjax2 is also used in frontend-app-library-authoring. Can you please take a look?

@CefBoud Although I don't know if it is in the scope, I can update it as it seems to be used in only once place.

CefBoud

👍

I tested this: in Text, Numerical Input, Math Expression and Problem components. Also in course Discussions. Inline and display expressions.
I read through the code
I checked for accessibility issues : Mathjax built-in accessibility functioning properly. Tested with Chrome Screen Reader extension.
~~Includes documentation~~
~~I made sure any change in configuration variables is reflected in the corresponding client's configuration-secure repository~~.

wittjeff · 2023-11-07T17:53:46Z

Please see discussion re upgrade paths for MathML rendering not being simple in this earlier PR: #32418
If you'd like to implement a course-level Advanced Option (with at least MathJax v2.7.9 and 3.2.1), that'd be super.

navinkarkera · 2023-11-08T05:58:21Z

@wittjeff Thanks for pointing me to the PR. About implementing course level advance option to support both v2 and v3, I'll come back with an update/answer soon.

wittjeff · 2023-11-08T11:41:29Z

        $script(
-            'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js'
-            + '?config=TeX-MML-AM_SVG&delayStartupUntil=configured',
+            'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js',


There is a v3.2.2 available. https://github.com/mathjax/MathJax/releases/tag/3.2.2

wittjeff · 2023-11-08T11:41:59Z


            // externally hosted files
-            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_SVG&delayStartupUntil=configured', // eslint-disable-line max-len
+            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js?noext',


3.2.2 available

wittjeff · 2023-11-08T11:42:36Z

            'URI': 'xmodule_js/common_static/js/vendor/URI.min',
            'mock-ajax': 'xmodule_js/common_static/js/vendor/mock-ajax',
-            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_SVG&delayStartupUntil=configured', // eslint-disable-line max-len
+            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js?noext',


3.2.2 available

wittjeff · 2023-11-08T11:42:50Z

            'domReady': 'xmodule_js/common_static/js/vendor/domReady',
            'URI': 'xmodule_js/common_static/js/vendor/URI.min',
-            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_SVG&delayStartupUntil=configured', // eslint-disable-line max-len
+            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js?noext',


3.2.2 available

wittjeff · 2023-11-08T11:43:55Z

 @import 'build-v1'; // shared app style assets/rendering
+
+
+.MathJax>svg {


I thought v3 eliminated SVG rendering. No? SVG rendering is problematic when used as items in a select element.

wittjeff · 2023-11-08T11:48:06Z

+                ],
+                autoload: {
+                    color: [],
+                    colorv2: ['color']


Do we need to consider accessibility (particularly contrast) of a MathJax color palette?

wittjeff · 2023-11-08T11:48:22Z

-        }
-    };
-    vendorScript.src = 'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_HTMLorMML';
+    vendorScript.src = 'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js';


3.2.2 available

wittjeff · 2023-11-08T11:52:41Z

     It can't be run through static.url because MathJax uses crazy url introspection to do lazy loading of
     MathJax extension libraries -->
-<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_SVG"></script>
+<script type="text/javascript" id="MathJax-script" src="https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js"></script>


3.2.2 available

wittjeff · 2023-11-08T11:53:45Z

            'jasmine-imagediff': 'xmodule_js/common_static/js/vendor/jasmine-imagediff',
            'domReady': 'xmodule_js/common_static/js/vendor/domReady',
-            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@2.7.5/MathJax.js?config=TeX-MML-AM_HTMLorMML&delayStartupUntil=configured', // eslint-disable-line max-len
+            mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3.2.1/es5/tex-mml-svg.js?noext',


3.2.2 available

wittjeff · 2023-11-08T11:54:01Z

    }
 }
+
+.MathJax>svg {


Use of SVG??

wittjeff · 2023-11-08T18:58:40Z

Related discussion re Canvas use of MathJax: https://community.canvaslms.com/t5/Canvas-Question-Forum/Canvas-s-MathJax-Needs-An-Update/m-p/583189

Yagnesh1998 · 2023-11-09T10:54:00Z

I submitted a PR because I'm having some issues with MathJax on the edX platform.Let me know if there is anything I can do here

rayzhou-bit · 2024-01-22T18:30:34Z

Hi @navinkarkera, I tried testing this recently with a more current version of edx-platform and could not get it to work. Is it still working on your environment?

navinkarkera · 2024-02-02T15:44:51Z

@rayzhou-bit Thanks for testing it. I am currently occupied with another project and we haven't received any confirmation from the original stakeholders yet, but I hope to get back to this soon.

OmarIthawi

Thanks @navinkarkera for your contribution. This is really useful and the update is much needed to improve performance.

I recommend using HTML CSS instead of SVG whenever possible. SVG is challenging for MathJax plugin makers like myself when it comes to Arabic and RTL support.

Additionally, Open edX needs to support mobile and to stay accessible which I think MathJax SVG isn't very well suited for:

https://docs.mathjax.org/en/latest/output/html.html

mphilbrick211 · 2024-10-30T20:04:22Z

Hi @navinkarkera! Are you planning to pursue this PR?

navinkarkera · 2024-11-04T05:22:04Z

@mphilbrick211 Yes, once mathjax 4 is released, we plan to upgrade since it is already in beta. For more info, please see this discussion

mphilbrick211 · 2025-09-24T17:12:04Z

Hi @navinkarkera! Just checking in on this :)

navinkarkera · 2025-09-25T10:57:09Z

@mphilbrick211 Sorry, I don't have any update here.

wittjeff · 2025-11-16T00:55:58Z

Version 4.0.0 is now available.

feanil · 2025-11-19T20:31:40Z

@navinkarkera I'm gonna move this to draft until you're ready to with the MathJax 4.0 update. Once it's ready for review let me know and I can help get it reviewed and landed.

fix: use asciimath test: fix mathjax related tests fix: lint issues fix: mathjax_delay_renderer test: fix mathjax related tests

feanil · 2026-05-08T13:36:01Z

@navinkarkera are you planning to come back to this?

navinkarkera · 2026-05-09T05:46:46Z

@feanil I do have a branch that works with version 4 but need to rebase and test it out. But the ability to select different versions per course is not implemented and I don't have the capacity right now.

- Pin CDN URLs to mathjax@4.1.2 - Fix mathjax_delay_renderer.js immediate path to pass DOM node - Add null guard in capa/display.js for missing math element - Fix CSS syntax: comma to semicolon in MathJax SVG rules - Pass textContent instead of innerHTML for security

- mathjax_delay_renderer.js: add typesetClear before .html() in both immediate and delayed paths, so MathJax v3/v4 re-renders replaced content - capa/display.js refreshMath: replace v2 Hub.Queue/getAllJax with v3/v4 typesetClear/typesetPromise; add typesetClear before setting preview textContent; unify rendering to AsciiMath/backtick for all non-tex-delimited input (fixes formula preview for formulaequationinput where * → multiplication and / → fraction instead of literal chars) - capa/display_spec.js: add tests for calculator syntax backtick wrapping, TeX delimiter preservation, and empty-input early return

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Oct 22, 2023

navinkarkera force-pushed the navin/upgrade-mathjax-v3 branch 4 times, most recently from 3f5125c to 6d29ae7 Compare October 25, 2023 06:56

navinkarkera marked this pull request as ready for review October 25, 2023 08:10

CefBoud reviewed Oct 26, 2023

View reviewed changes

Comment thread common/static/js/capa/src/formula_equation_preview.js Outdated

navinkarkera mentioned this pull request Oct 26, 2023

feat: upgrade mathjax from v2 to v3 openedx-unsupported/frontend-app-library-authoring#352

Closed

navinkarkera force-pushed the navin/upgrade-mathjax-v3 branch from 6d29ae7 to 70f67b9 Compare October 26, 2023 15:51

CefBoud approved these changes Oct 27, 2023

View reviewed changes

navinkarkera force-pushed the navin/upgrade-mathjax-v3 branch 2 times, most recently from 5315c9c to c7ed9e1 Compare October 30, 2023 04:38

navinkarkera self-assigned this Oct 30, 2023

navinkarkera mentioned this pull request Nov 8, 2023

fix: Upgraded Mathjax version from 2.7 to 3.0.1 #32418

Closed

wittjeff suggested changes Nov 8, 2023

View reviewed changes

itsjeyd added the waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. label Mar 11, 2024

OmarIthawi suggested changes Jul 13, 2024

View reviewed changes

mphilbrick211 removed the waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. label Oct 30, 2024

mphilbrick211 added the waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. label Oct 30, 2024

mphilbrick211 removed the waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. label Aug 5, 2025

openedx-webhooks added the core contributor PR author is a Core Contributor (who may or may not have write access to this repo). label Sep 24, 2025

feanil marked this pull request as draft November 19, 2025 20:31

feanil self-assigned this Nov 19, 2025

feat: mathjax upgrade v2 to v3

e6c9a20

fix: use asciimath test: fix mathjax related tests fix: lint issues fix: mathjax_delay_renderer test: fix mathjax related tests

navinkarkera force-pushed the navin/upgrade-mathjax-v3 branch from c7ed9e1 to e6c9a20 Compare November 28, 2025 15:14

feanil added the waiting on author PR author needs to resolve review requests, answer questions, fix tests, etc. label Jan 9, 2026

navinkarkera added 8 commits June 16, 2026 10:34

Merge branch 'master' into navin/upgrade-mathjax-v3

5e6700f

fix(mathjax): use chtml output

6dd7f9b

fix(mathjax): support v4 formula previews

40d3ae7

Merge branch 'master' into navin/upgrade-mathjax-v3

5ef1413

temp: fix

c9945ba

fix(mathjax): enable extracted xblocks for v4

b960c53

		@import 'build-v1'; // shared app style assets/rendering


		.MathJax>svg {

Uh oh!

Conversation

navinkarkera commented Oct 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Supporting information

Testing instructions

Deadline

Other information

Uh oh!

openedx-webhooks commented Oct 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CefBoud commented Oct 26, 2023

Uh oh!

Uh oh!

navinkarkera commented Oct 26, 2023

Uh oh!

CefBoud left a comment

Choose a reason for hiding this comment

Uh oh!

wittjeff commented Nov 7, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

navinkarkera commented Nov 8, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wittjeff commented Nov 8, 2023

Uh oh!

Yagnesh1998 commented Nov 9, 2023

Uh oh!

rayzhou-bit commented Jan 22, 2024

Uh oh!

navinkarkera commented Feb 2, 2024

Uh oh!

OmarIthawi left a comment

Choose a reason for hiding this comment

Uh oh!

mphilbrick211 commented Oct 30, 2024

Uh oh!

navinkarkera commented Nov 4, 2024

Uh oh!

mphilbrick211 commented Sep 24, 2025

Uh oh!

navinkarkera commented Sep 25, 2025

Uh oh!

wittjeff commented Nov 16, 2025

Uh oh!

feanil commented Nov 19, 2025

Uh oh!

feanil commented May 8, 2026

Uh oh!

navinkarkera commented May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

navinkarkera commented Oct 22, 2023 •

edited

Loading

openedx-webhooks commented Oct 22, 2023 •

edited

Loading

wittjeff commented Nov 7, 2023 •

edited

Loading