sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Current mathjax loading on per-page basis breaks math in table of contents

Open burp opened this issue 2 years ago • 3 comments

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

2021-09-29-133959_1084x394_scrot

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

burp avatar Sep 29 '21 17:09 burp

@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.

mmcky avatar Feb 17 '22 04:02 mmcky

For what it's worth, a quick workaround is to include some invisible text:

:math:`\phantom{~}`

K20shores avatar Jul 25 '22 19:07 K20shores

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.

humitos avatar Jul 26 '22 08:07 humitos