MathJax version 3 support

[bryanwweber]

On the Math & Equations page, there is a note that MathJax 3 can be used by configuring the mathjax_path. However, if you have any other MathJax configuration (e.g., custom macros) these will not be converted to the new configuration format for MathJax 3. It seems that Sphinx does not yet support the new configuration format either; the pull request that switched Sphinx over to MathJax version 3 didn't address the configuration changes. See also: http://docs.mathjax.org/en/latest/web/configuration.html#converting-your-v2-configuration-to-v3

I think one way to resolve this issue would be to modify the note in the Jupyter Books docs to say something about other configuration options not being suported at the moment.

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[chrisjsewell]

Thanks, there is an open issue about the macros; #917, but yeh we can make it clearer in the docs, the reason why it is not the default yet 👍

[bryanwweber]

Thanks @chrisjsewell Yeah, I think the issue has to be fixed upstream in Sphinx first, to be able to add the configuration correctly. I'm not sure how they'll be able to support arbitrary configuration, if the mathjax_path is configurable. Maybe they'll have to be less complete about how they handle it, and require users of MathJax v2 to put the Mathjax.Hub.Config into the js.

[chrisjsewell]

You can set Mathjax.Hub.Config via the sphinx config though: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config. Is that not enough?

[bryanwweber]

No, the configuration settings are completely changed in v3. It will require an update in how Sphinx generates the configuration js script... The options live at the global level of the MathJax object now, rather than MathJax.Hub.Config.

Following the conversion guide here: https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html

This generated configuration with current JB (using Sphinx 3 and MathJax v2):

MathJax.Hub.Config({

  "TeX": {"Macros": {"vector": ["\\vec{#1}", 1]}}, "tex2jax": {"inlineMath": [["\\(", "\\)"]], "displayMath": [["\\[", "\\]"]], "processRefs": false, "processEnvironments": false}

});

with this config parameter: MathJax.js?config=TeX-AMS-MML_HTMLorMML results in this new MathJax v3 configuration:

<script>
window.MathJax = {
  tex: {
    macros: {
      vector: ["\\vec{#1}", 1]
    },
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processRefs: false,
    processEnvironments: false,
    autoload: {
      color: [],
      colorV2: ['color']
    },
    packages: {'[+]': ['noerrors']}
  },
  options: {
    ignoreHtmlClass: 'tex2jax_ignore',
    processHtmlClass: 'tex2jax_process'
  },
  loader: {
    load: ['[tex]/noerrors']
  }
};
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" id="MathJax-script"></script>

The last line there is handled by the mathjax_path, but the rest of it can't be handled by the current mathjax_config option.

[chrisjsewell]

thanks for the info!

[bryanwweber]

You can see the link there, but I cross posted this at sphinx-doc/sphinx#8195, since this is really a problem with Sphinx. I suppose depending on how the fix is handled there, the configuration in JB might have to change slightly.

[chrisjsewell]

thanks, I also need to keep track of this for myst-parser, where I am currently overriding some of the default behaviour of MathJax.js?config=TeX-AMS-MML_HTMLorMML; to stop MathJax from parsing $ delimited math (since this is already handled by the Markdown parser)
(see https://myst-parser.readthedocs.io/en/latest/using/syntax.html#mathjax-and-math-parsing)

Really, the ideal behaviour for MathJax, would be to only render text in specific HTML elements, like

<math-block id="mylabel">a=1</math-block>
<p> <math-inline>\gamma</math-inline> </p>

rather than arbitrarily searching in the text for delimiters like \\[...\\].
Because with myst-parser/sphinx, that search has already been performed, and the math encoded in the AST in an output agnostic manner.
I imagine this would be more reliable and performant.

I wonder if this is possible with MathJax/KaTex; natively or with some minor JS additions?

[bryanwweber]

Can you encoded the output as MathML? See http://danielscully.co.uk/projects/mathml-guide/index.php and the W3 page https://www.w3.org/Math/

MathJax can be configured to load/render only MathML elements, see http://docs.mathjax.org/en/latest/basic/mathematics.html#mathml-input and http://docs.mathjax.org/en/latest/web/components/combined.html#mml-chtml

You can also control the TeX delimiters, see http://docs.mathjax.org/en/latest/input/tex/delimiters.html#tex-delimiters

[mgeier]

@chrisjsewell

Really, the ideal behaviour for MathJax, would be to only render text in specific HTML elements [...] rather than arbitrarily searching in the text for delimiters like \\[...\\].

I don't know whether that's possible, but it's possible to limit the search for delimiters to certain HTML elements.

In the pre-MathJax-3 era this was done with ignoreClass and processClass (which, for example, I've used there: https://github.com/spatialaudio/nbsphinx/blob/d5d352c5440cc7a185751bdf0d1ba263b7a2026d/src/nbsphinx.py#L2237-L2245).

With MathJax 3, this should become something like the following (but I haven't tested this yet!):

window.MathJax = {
  options: {
    ignoreHtmlClass: "document",
    processHtmlClass: "math|output_area"
  }
};

[mgeier]

This issue is still waiting for a solution: sphinx-doc/sphinx#8195

Does anyone here have a good idea how to tackle this?

[mgeier]

I've created a PR at sphinx-doc/sphinx#9094, are there any further comments or suggestions?

[chrisjsewell]

Yes I just noticed that thanks, will check it out 👍

[mmcky]

We have been looking into mathjax@v3 and found there to be a couple issues with fonts when browsing chtml rendering on safari and discovered this open issue: mathjax/MathJax#2435. On quantecon projects we may use svg for now.

[choldgraf]

@mmcky do you have any update on the situation with Mathjax 3? Have you found it to improve at all since last May?

[mmcky]

@choldgraf just enabled chtml on one of our projects for testing as I just saw that mathjax=3.2 has been released that has

better handling of adaptive CSS in the CommonHTML output

QuantEcon/lecture-python.myst#179

[mmcky]

@choldgraf did some testing today and we are finding there are still incorrect renderings of math using chtml on safari as per comments in QuantEcon/lecture-python.myst#179.

[bryanwweber]

FYI, I've been using Sphinx 4.1.2 with Mathjax 3 and I've had no problems that I've noticed. The book is over here: https://orbital-mechanics.space

[mmcky]

thanks @bryanwweber -- nice book! (coming from an ex: aerospace engineer :-))

We get issues with missing fraction underlines in some equations but on the whole looks pretty good.

[bryanwweber]

Thanks @mmcky!

[veikopalge]

Hello

Upgrading to sphinx 4.x breaks TeX macros in _config.yml. The jupyterbook own documentation renders it broken, see

https://jupyterbook.org/advanced/sphinx.html#defining-tex-macros

where the "\bmat" macro is shown in red.

I stumbled upon this commit (unrelated to jupyterbook)

AMReX-Astro/Castro@95a36ed

which resolves the issue: in _config.yml, change "TeX" and "Macro" to lowercase:

mathjax3_config:
  tex:
    macros:

and it works fine.

Maybe this can be included in the migration notes?

Thanks

[bryanwweber]

Several years later, I assume this issue is resolved? I don't notice any problems in my book, so I'll close it. It can be reopened if necessary 😁