Skip to content

Bump MathJax support from v2/v3 to v3/v4#7857

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
emilykl wants to merge 14 commits into from
Closed

Bump MathJax support from v2/v3 to v3/v4 #7857

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c4d8354
migrate mathjax support from v2/v3 to v3/v4
emilykl Jun 22, 2026
6c74b2a
update image baselines
emilykl Jun 22, 2026
da2c2a3
disable automatic line breaks to fix rendering issue
emilykl Jul 7, 2026
04bbe2b
bump kaleido and plotly version in env_image
emilykl Jul 7, 2026
eff00df
revert package-lock.json to match v4.0 branch
emilykl Jul 8, 2026
cf41ca1
update dev dependencies only in package-lock.json
emilykl Jul 8, 2026
df4e823
Revert "bump kaleido and plotly version in env_image"
emilykl Jul 8, 2026
5570d8b
update baseline images
emilykl Jul 8, 2026
6ca90f1
fix issue with interfering async render calls
emilykl Jul 9, 2026
487b9b3
fix text-anchor positioning bug
emilykl Jul 9, 2026
7e79b06
await Axes.draw before returning from doTicksRelayout
emilykl Jul 9, 2026
3c8d51f
update image baselines
emilykl Jul 9, 2026
5dd56ee
remove mathjax render queue
emilykl Jul 9, 2026
5690527
update mathjax3 baseline images
emilykl Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 1 addition & 6 deletions devtools/test_dashboard/index-mathjax3chtml.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -49,12 +49,7 @@
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);
}
}
Expand Down
2 changes: 1 addition & 1 deletion devtools/test_dashboard/index.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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>
Expand Down
29 changes: 20 additions & 9 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -115,8 +115,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",
Comment on lines +118 to +119

@archmojarchmojJun 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The packages looks quite confusing.
#7394 seems to hide a security issue?
Is that still relevant?

"@types/d3": "3.5.34",
"@types/node": "^24.10.0",
"amdefine": "^1.0.1",
Expand Down
216 changes: 91 additions & 125 deletions src/lib/svg_text_utils.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -74,22 +74,29 @@ exports.convertToTspans = function(_context, gd, _callback) {
}

if(tex) {
((gd && gd._promises) || []).push(new Promise(function(resolve) {
_context.style('display', 'none');
var fontSize = parseInt(_context.node().style.fontSize, 10);
var config = {fontSize: fontSize};

_context.style('display', 'none');
var fontSize = parseInt(_context.node().style.fontSize, 10);
var config = {fontSize: fontSize};
// capture the anchor now: the callback runs async, by which point a
// positioning pass may have changed text-anchor and would mis-place the svg
var textAnchor = _context.attr('text-anchor');

((gd && gd._promises) || []).push(
texToSVG(tex[2], config, function(_svgEl, _glyphDefs, _svgBBox) {
parent.selectAll('svg.' + svgClass).remove();
parent.selectAll('g.' + svgClass + '-group').remove();

var newSvg = _svgEl && _svgEl.select('svg');
if(!newSvg || !newSvg.node()) {
showText();
resolve();
return;
}

// Re-hide the source text. It should already be hidden, but it's possible
// another code path has made it visible again before the async render finishes,
// so we hide it again here now that the MathJax has actually been rendered
_context.style('display', 'none');

var mathjaxGroup = parent.append('g')
.classed(svgClass + '-group', true)
.attr({
Expand DownExpand Up@@ -151,11 +158,9 @@ exports.convertToTspans = function(_context, gd, _callback) {
x = 0;
y = dy;
} else {
var anchor = _context.attr('text-anchor');

x = x - w * (
anchor === 'middle' ? 0.5 :
anchor === 'end' ? 1 : 0
textAnchor === 'middle' ? 0.5 :
textAnchor === 'end' ? 1 : 0
);
y = y + dy - h / 2;
}
Expand All@@ -166,9 +171,8 @@ exports.convertToTspans = function(_context, gd, _callback) {
});

if(_callback) _callback.call(_context, mathjaxGroup);
resolve(mathjaxGroup);
});
}));
})
);
} else showText();

return _context;
Expand All@@ -187,68 +191,73 @@ function cleanEscapesForTex(s) {

var inlineMath = [['$', '$'], ['\\(', '\\)']];

function texToSVG(_texString, _config, _callback) {
var MathJaxVersion = parseInt(
(MathJax.version || '').split('.')[0]
);

if(
MathJaxVersion !== 2 &&
MathJaxVersion !== 3
) {
Lib.warn('No MathJax version:', MathJax.version);
return;
}

var originalRenderer,
originalConfig,
originalProcessSectionDelay,
tmpDiv;
// Configure MathJax, then build its startup document by calling MathJax.startup.defaultReady().
// Once the startup document is built, we can reset the config immediately,
// and reuse the same document for all render calls.
var mathjaxReadyPromise = null;

var setConfig2 = function() {
originalConfig = Lib.extendDeepAll({}, MathJax.Hub.config);
// Verify that the MathJax output is set to SVG
function mathjaxOutputIsSvg() {
var doc = MathJax.startup && MathJax.startup.document;
return !!(doc && doc.outputJax && doc.outputJax.name === 'SVG');
}

originalProcessSectionDelay = MathJax.Hub.processSectionDelay;
if(MathJax.Hub.processSectionDelay !== undefined) {
// MathJax 2.5+ but not 3+
MathJax.Hub.processSectionDelay = 0;
function ensureMathJax(MathJaxVersion) {
if(mathjaxReadyPromise && mathjaxOutputIsSvg()) return mathjaxReadyPromise;

var config = MathJax.config;
var origTex = config.tex;
var origSvg = config.svg;
var origOutput = config.startup.output;

try {
// Configure MathJax the way we need it for plotly
config.tex = Lib.extendFlat({}, origTex, {inlineMath: inlineMath});
config.startup.output = 'svg';

// MathJax v4 enables automatic inline linebreaking by default,
// which breaks a lot of our layout assumptions. Disabling it
// gives behavior consistent with v3.
if(MathJaxVersion === 4) {
config.svg = Lib.extendFlat({}, origSvg, {
linebreaks: Lib.extendFlat({}, origSvg && origSvg.linebreaks, {inline: false})
});
}

return MathJax.Hub.Config({
messageStyle: 'none',
tex2jax: {
inlineMath: inlineMath
},
displayAlign: 'left',
});
};
MathJax.startup.defaultReady();
} finally {
// Reset the config to its original values
config.tex = origTex;
config.svg = origSvg;
config.startup.output = origOutput;
}

var setConfig3 = function() {
originalConfig = Lib.extendDeepAll({}, MathJax.config);
mathjaxReadyPromise = MathJax.startup.promise;
return mathjaxReadyPromise;
}

if(!MathJax.config.tex) {
MathJax.config.tex = {};
}
function texToSVG(_texString, _config, _callback) {
const MathJaxVersion = parseInt(
(MathJax.version || '').split('.')[0]
);

MathJax.config.tex.inlineMath = inlineMath;
};
if(
MathJaxVersion !== 3 &&
MathJaxVersion !== 4
) {
Lib.warn('Unsupported MathJax version:', MathJax.version);
_callback();
return Promise.resolve();
}

var setRenderer2 = function() {
originalRenderer = MathJax.Hub.config.menuSettings.renderer;
if(originalRenderer !== 'SVG') {
return MathJax.Hub.setRenderer('SVG');
}
};
return renderTex(_texString, _config, _callback, MathJaxVersion);
}

var setRenderer3 = function() {
originalRenderer = MathJax.config.startup.output;
if(originalRenderer !== 'svg') {
MathJax.config.startup.output = 'svg';
}
};
function renderTex(_texString, _config, _callback, MathJaxVersion) {
var tmpDiv;

var initiateMathJax = function() {
var randomID = 'math-output-' + Lib.randstr({}, 64);
const initiateMathJax = function() {
const randomID = 'math-output-' + Lib.randstr({}, 64);
tmpDiv = d3.select('body').append('div')
.attr({id: randomID})
.style({
Expand All@@ -258,81 +267,38 @@ function texToSVG(_texString, _config, _callback) {
})
.text(cleanEscapesForTex(_texString));

var tmpNode = tmpDiv.node();
const tmpNode = tmpDiv.node();

return MathJaxVersion === 2 ?
MathJax.Hub.Typeset(tmpNode) :
MathJax.typeset([tmpNode]);
return MathJax.typesetPromise([tmpNode]);
};

var finalizeMathJax = function() {
var sel = tmpDiv.select(
MathJaxVersion === 2 ? '.MathJax_SVG' : '.MathJax'
);
const finalizeMathJax = function() {
const sel = tmpDiv.select('.MathJax');

var node = !sel.empty() && tmpDiv.select('svg').node();
const node = !sel.empty() && tmpDiv.select('svg').node();
if(!node) {
Lib.log('There was an error in the tex syntax.', _texString);
_callback();
} else {
var nodeBBox = node.getBoundingClientRect();
var glyphDefs;
if(MathJaxVersion === 2) {
glyphDefs = d3.select('body').select('#MathJax_SVG_glyphs');
} else {
glyphDefs = sel.select('defs');
}
const nodeBBox = node.getBoundingClientRect();
const glyphDefs = sel.select('defs');
_callback(sel, glyphDefs, nodeBBox);
}

tmpDiv.remove();
};

var resetRenderer2 = function() {
if(originalRenderer !== 'SVG') {
return MathJax.Hub.setRenderer(originalRenderer);
}
};

var resetRenderer3 = function() {
if(originalRenderer !== 'svg') {
MathJax.config.startup.output = originalRenderer;
}
};

var resetConfig2 = function() {
if(originalProcessSectionDelay !== undefined) {
MathJax.Hub.processSectionDelay = originalProcessSectionDelay;
}
return MathJax.Hub.Config(originalConfig);
};

var resetConfig3 = function() {
MathJax.config = originalConfig;
};

if(MathJaxVersion === 2) {
MathJax.Hub.Queue(
setConfig2,
setRenderer2,
initiateMathJax,
finalizeMathJax,
resetRenderer2,
resetConfig2
);
} else if(MathJaxVersion === 3) {
setConfig3();
setRenderer3();
MathJax.startup.defaultReady();

MathJax.startup.promise.then(function() {
initiateMathJax();
finalizeMathJax();

resetRenderer3();
resetConfig3();
// start from a resolved promise so a synchronous throw in ensureMathJax
// routes to the catch below instead of rejecting the gd._promises entry
return Promise.resolve()
.then(function() { return ensureMathJax(MathJaxVersion); })
.then(initiateMathJax)
.then(finalizeMathJax)
.catch((err) => {
Lib.log('MathJax typesetting failed.', _texString, err);
if(tmpDiv) tmpDiv.remove();
_callback();
});
}
}

var TAG_STYLES = {
Expand Down
2 changes: 1 addition & 1 deletion src/plot_api/plot_config.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -27,7 +27,7 @@ var configAttributes = {
dflt: true,
description: [
'Determines whether math should be typeset or not,',
'when MathJax (either v2 or v3) is present on the page.'
'when MathJax (either v3 or v4) is present on the page.'
].join(' ')
},

Expand Down
Loading