Merge pull request #9867 from tk0miya/9864_mathjax_loading_method

Fix #9864: mathjax: Failed to render equations via MathJax v2

CHANGES

@@ -13,6 +13,9 @@ Deprecated
 Features added
 --------------
 
+* #9864: mathjax: Support chnaging the loading method of MathJax to "defer" via
+  :confval:`mathjax_options`
+
 Bugs fixed
 ----------
 
@@ -22,6 +25,8 @@ Bugs fixed
   having invalid __doc__ atribute
 * #9872: html: Class namespace collision between autodoc signatures and
   docutils-0.17
+* #9864: mathjax: Failed to render equations via MathJax v2.  The loading method
+  of MathJax is back to "async" method again
 
 Testing
 --------

doc/usage/extensions/math.rst

@@ -200,6 +200,11 @@ Sphinx but is set to automatically include it from a third-party site.
 
    .. versionadded:: 1.8
 
+   .. versionchanged:: 4.4.1
+
+      Allow to change the loading method (async or defer) of MathJax if "async"
+      or "defer" key is set.
+
 .. confval:: mathjax3_config
 
    The configuration options for MathJax v3 (which is used by default).

sphinx/ext/mathjax.py

@@ -81,10 +81,17 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
     domain = cast(MathDomain, app.env.get_domain('math'))
     if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
         # Enable mathjax only if equations exists
-        options = {'defer': 'defer'}
+        options = {}
         if app.config.mathjax_options:
             options.update(app.config.mathjax_options)
-        app.add_js_file(app.config.mathjax_path, **options)  # type: ignore
+        if 'async' not in options and 'defer' not in options:
+            if app.config.mathjax3_config:
+                # Load MathJax v3 via "defer" method
+                options['defer'] = 'defer'
+            else:
+                # Load other MathJax via "async" method
+                options['async'] = 'async'
+        app.add_js_file(app.config.mathjax_path, **options)
 
         if app.config.mathjax2_config:
             if app.config.mathjax_path == MATHJAX_URL:

tests/test_ext_math.py

@@ -71,7 +71,7 @@ def test_mathjax_options(app, status, warning):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').read_text()
-    assert ('<script defer="defer" integrity="sha384-0123456789" '
+    assert ('<script async="async" integrity="sha384-0123456789" '
             'src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">'
             '</script>' in content)
 
@@ -221,6 +221,7 @@ def test_mathjax3_config(app, status, warning):
 
     content = (app.outdir / 'index.html').read_text()
     assert MATHJAX_URL in content
+    assert ('<script defer="defer" src="%s">' % MATHJAX_URL in content)
     assert ('<script>window.MathJax = {"extensions": ["tex2jax.js"]}</script>' in content)
 
 
@@ -231,12 +232,35 @@ def test_mathjax2_config(app, status, warning):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').read_text()
-    assert MATHJAX_URL in content
+    assert ('<script async="async" src="%s">' % MATHJAX_URL in content)
     assert ('<script type="text/x-mathjax-config">'
             'MathJax.Hub.Config({"extensions": ["tex2jax.js"]})'
             '</script>' in content)
 
 
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax_options': {'async': 'async'},
+                                   'mathjax3_config': {'extensions': ['tex2jax.js']}})
+def test_mathjax_options_async_for_mathjax3(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text()
+    assert MATHJAX_URL in content
+    assert ('<script async="async" src="%s">' % MATHJAX_URL in content)
+
+
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax_options': {'defer': 'defer'},
+                                   'mathjax2_config': {'extensions': ['tex2jax.js']}})
+def test_mathjax_options_defer_for_mathjax2(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text()
+    assert ('<script defer="defer" src="%s">' % MATHJAX_URL in content)
+
+
 @pytest.mark.sphinx('html', testroot='ext-math',
                     confoverrides={'extensions': ['sphinx.ext.mathjax']})
 def test_mathjax_is_installed_only_if_document_having_math(app, status, warning):