sphinx
sphinx copied to clipboard
Current mathjax loading on per-page basis breaks math in table of contents
Describe the bug
When a page doesn't use mathjax (:math:) it doesn't load mathjax. This breaks titles in the table of contents that do use math.
How to Reproduce
- perform a sphinx-quickstart
- add 'sphinx.ext.mathjax' to extensions
- create otherpage.rst
:math:`1+1=\alpha`
==================
Test page with math in title.
add otherpage to toctree of index.rst.
- make html
Expected behavior
Math is properly rendered in table of contents of index.html
Your project
n/a
Screenshots
OS
Linux
Python version
3.9.1
Sphinx version
3.5.1 and also 4.2.0 (probably also newer)
Sphinx extensions
sphinx.ext.mathjax
Extra tools
No response
Additional context
See implementation on per-page loading https://github.com/sphinx-doc/sphinx/issues/6241
@chrisjsewell I have taken a look but can't see anywhere in sphinx
if there is a state variable tracking the presence of math on a page. I suspect it might not be flagged anyway if there was given this issue. Do you think the best "technical" way forward here would be a post_transform
that parses pages checking for math markup in references and then to ensure MathJax
loads on that page?
I came up against this issue in sphinx-exercise
when math is used in titles (and the referenced location doesn't render the math due to missing MathJax
. This could be fixed at the extension level but given this issue it seems to be a broader problem.
For what it's worth, a quick workaround is to include some invisible text:
:math:`\phantom{~}`
I've hit a similar problem some time ago (see https://github.com/sphinx-doc/sphinx/pull/9174). You could set Sphinx.set_html_assets_policy("always")
to force Sphinx including assets in all the pages, not only on those ones that are used.