Upgrade MathJax support from v2/v3 to v3/v4

README.md

@@ -95,17 +95,23 @@ While non-minified source files may contain characters outside UTF-8, it is reco
 > Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.5. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
 
 ### MathJax
-You can load either version two or version three of MathJax files. For example:
+plotly.js supports using MathJax v3 or v4 to render mathematical expressions within plots.
+
+MathJax is not included in the plotly.js bundle, so it must be loaded separately as a script on the webpage.
+
+For MathJax v4:
 ```html
-<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@4.1.2/tex-svg.js"></script>
 ```
 
+For MathJax v3:
 ```html
 <script src="https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js"></script>
 ```
 
-> When using MathJax version 3, it is also possible to use `chtml` output on the other parts of the page in addition to `svg` output for the plotly graph.
-Please refer to `devtools/test_dashboard/index-mathjax3chtml.html` to see an example.
+When MathJax is available, any string contained within `$..$` signs will be rendered using the MathJax engine. This applies to plot titles, axis labels, tick label text, and annotations.
+
+plotly.js's use of the MathJax `svg` renderer should not prevent using other MathJax renderers elsewhere on the page, nor will it affect the global MathJax config. See `devtools/test_dashboard/index-mathjax3chtml.html` for an example of a webpage which uses the MathJax `chtml` renderer in the main page, and also displays Plotly charts containing MathJax equations rendered as `svg`.
 
 ### Need to have several WebGL graphs on a page?
 You may simply load the [virtual-webgl](https://github.com/greggman/virtual-webgl) script for WebGL 1 (not WebGL 2) before loading other scripts.

devtools/test_dashboard/index-mathjax3.html

@@ -17,7 +17,7 @@
 
   <section id="mocks-list"></section>
 
-  <p id="pWithMathJax">MathJax $V^3$ with $svg$ output on the page as well as plotly graphs</p>
+  <p>MathJax \(V^3\) with \(svg\) output on the page as well as plotly graphs</p>
   <h4>no MathJax: Apple: $2, Orange: $3</h4>
 
   <div id="plots">
@@ -27,18 +27,12 @@ <h4>no MathJax: Apple: $2, Orange: $3</h4>
 
   <script>
     window.MathJax = {
-      startup: {
-        elements: [
-          document.getElementById('pWithMathJax')
-        ],
-        // typeset: false,
-        // in case the elements array is empty one could disable startup typeset
-        // https://docs.mathjax.org/en/latest/options/startup/startup.html#the-configuration-block
-      }
+      // MathJax config options can be set here, although
+      // none are strictly needed for this page.
     };
   </script>
   <script src="../../node_modules/@plotly/mathjax-v3/es5/tex-svg.js"></script>
-  <script charset="utf-8" id="source" src="../../build/plotly.js" type="module"></script>
+  <script charset="utf-8" id="source" src="../../build/plotly.js"></script>
   <script charset="utf-8" src="../../build/test_dashboard-bundle.js"></script>
 </body>
 </html>

devtools/test_dashboard/index-mathjax3chtml.html

@@ -17,52 +17,24 @@
 
   <section id="mocks-list"></section>
 
-  <p>MathJax $V^3$ with $chtml$ output on the page and <b>svg</b> output on the plotly graphs</p>
+  <p>MathJax \(V^3\) with \(chtml\) output on the page and <b>svg</b> output on the plotly graphs</p>
   <div id="plots">
     <div id="graph"></div>
   </div>
   <div id="snapshot"></div>
 
   <script>
-    window.MathJax = window.MathJax || {
-      // see https://github.com/mathjax/MathJax/issues/2705#issuecomment-859742446
+    window.MathJax = {
+      // It's possible for MathJax CHTML output to coexist on the same page with
+      // a plotly chart with renders MathJax as SVG; *however*, the loader must be
+      // configured to load the SVG output module so that it's available for plotly
+      // (in addition to the CHTML output module, which is implicitly loaded by
+      // tex-chtml.js below).
       loader: {load: ['output/svg']},
-      startup: {
-        ready() {
-          // Get the MathJax modules that we need.
-          const {mathjax} = MathJax._.mathjax;
-          const {SVG} = MathJax._.output.svg_ts;
-
-          // Do the normal setup
-          MathJax.startup.defaultReady();
-
-          // Create an SVG output jax and a new MathDocument that uses it.
-          const svgOutput = new SVG(MathJax.config.svg);
-          const svgDocument = mathjax.document(document, {
-            ...MathJax.config.options,
-            InputJax: MathJax.startup.input,
-            OutputJax: svgOutput
-          });
-
-          // Define the SVG-based conversion methods
-          MathJax.tex2svg = (math, options = {}) => {
-            options.format = svgDocument.inputJax[0].name;
-            return svgDocument.convert(math, options);
-          };
-          /*
-          MathJax.tex2svgPromise = (math, options = {}) => {
-            options.format = svgDocument.inputJax[0].name;
-            return mathjax.handleRetriesFor(() => svgDocument.convert(math, options));
-          };
-          */
-          MathJax.svgStylesheet = () => svgOutput.styleSheet(svgDocument);
-        }
-      }
     };
   </script>
   <script src="../../node_modules/@plotly/mathjax-v3/es5/tex-chtml.js"></script>
-
-  <script charset="utf-8" id="source" src="../../build/plotly.js" type="module"></script>
+  <script charset="utf-8" id="source" src="../../build/plotly.js"></script>
   <script charset="utf-8" src="../../build/test_dashboard-bundle.js"></script>
 </body>
 </html>

devtools/test_dashboard/index-mathjax4chtml.html

@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Plotly.js Devtools - MathJax v4 loaded with chtml output</title>
+  <meta charset="utf-8">
+  <link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Open+Sans:600,400,300,200|Droid+Sans|PT+Sans+Narrow|Gravitas+One|Droid+Sans+Mono|Droid+Serif|Raleway|Old+Standard+TT"/>
+  <link rel="stylesheet" type="text/css" href="./style.css">
+</head>
+<body>
+  <header>
+    <img src="http://images.plot.ly/logo/plotlyjs-logo@2x.png" onClick="Tabs.reload();" />
+    <span id="reload-time"></span>
+
+    <input id="mocks-search" type="text" placeholder="mocks search" />
+    <input id="css-transform" type="text" placeholder="css transform" />
+  </header>
+
+  <section id="mocks-list"></section>
+
+  <p>MathJax \(V^4\) with \(chtml\) output on the page and <b>svg</b> output on the plotly graphs</p>
+  <div id="plots">
+    <div id="graph"></div>
+  </div>
+  <div id="snapshot"></div>
+
+  <script>
+    window.MathJax = {
+      // It's possible for MathJax CHTML output to coexist on the same page with
+      // a plotly chart with renders MathJax as SVG; *however*, the loader must be
+      // configured to load the SVG output module so that it's available for plotly
+      // (in addition to the CHTML output module, which is implicitly loaded by
+      // tex-chtml.js below).
+      loader: {load: ['output/svg']},
+    };
+  </script>
+  <script src="../../node_modules/@plotly/mathjax-v4/tex-chtml.js"></script>
+  <script charset="utf-8" id="source" src="../../build/plotly.js"></script>
+  <script charset="utf-8" src="../../build/test_dashboard-bundle.js"></script>
+</body>
+</html>

devtools/test_dashboard/index.html

@@ -27,7 +27,7 @@
   <!-- Update UI elements if strict mode is enabled -->
   <script src="./strict.js"></script>
 
-  <script src="../../node_modules/@plotly/mathjax-v2/MathJax.js?config=TeX-AMS-MML_SVG"></script>
+  <script src="../../node_modules/@plotly/mathjax-v4/tex-svg.js"></script>
   <script charset="utf-8" id="source" src="../../build/plotly.js"></script>
   <script charset="utf-8" src="../../build/test_dashboard-bundle.js"></script>
 </body>

devtools/test_dashboard/server.mjs

@@ -11,6 +11,7 @@ var PORT = args.port || 3000;
 var strict = args.strict;
 var mathjax3 = args.mathjax3;
 var mathjax3chtml = args.mathjax3chtml;
+var mathjax4chtml = args.mathjax4chtml;
 
 if (strict) localDevConfig.entryPoints = ['./lib/index-strict.js'];
 
@@ -60,6 +61,7 @@ function devServer() {
     let indexName = 'index';
     if (mathjax3) indexName += '-mathjax3';
     else if (mathjax3chtml) indexName += '-mathjax3chtml';
+    else if (mathjax4chtml) indexName += '-mathjax4chtml';
     indexName += '.html';
 
     // open up browser window

draftlogs/7898_change.md

@@ -0,0 +1 @@
+- **Breaking:** Add support for MathJax v4, and **drop support for v2** [[#7898](https://github.com/plotly/plotly.js/pull/7898)]

package.json

@@ -56,6 +56,7 @@
     "b64": "python3 test/image/generate_b64_mocks.py && node devtools/test_dashboard/server.mjs",
     "mathjax3": "node devtools/test_dashboard/server.mjs --mathjax3",
     "mathjax3chtml": "node devtools/test_dashboard/server.mjs --mathjax3chtml",
+    "mathjax4chtml": "node devtools/test_dashboard/server.mjs --mathjax4chtml",
     "strict": "node devtools/test_dashboard/server.mjs --strict",
     "start": "node devtools/test_dashboard/server.mjs",
     "baseline": "node test/image/make_baseline.mjs",
@@ -115,8 +116,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",
-    "@plotly/mathjax-v2": "npm:mathjax@2.7.5",
-    "@plotly/mathjax-v3": "npm:mathjax@^3.2.2",
+    "@plotly/mathjax-v3": "npm:mathjax@3.2.2",
+    "@plotly/mathjax-v4": "npm:mathjax@^4.1.2",
     "@types/d3": "3.5.34",
     "@types/node": "^24.10.0",
     "amdefine": "^1.0.1",