sphinx

sphinx copied to clipboard

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.