Merge pull request #7961 from hameerabbasi/mathjax-3

Move to MathJax 3.

CHANGES

@@ -12,6 +12,9 @@ Incompatible changes
 
 * #4826: py domain: The structure of python objects is changed.  A boolean value
   is added to indicate that the python object is canonical one
+* #7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom
+  MathJax configuration may have to set the old MathJax path or update their
+  configuration for version 3. See :mod:`sphinx.ext.mathjax`.
 * #7784: i18n: The msgid for alt text of image is changed
 
 Deprecated

doc/usage/extensions/math.rst

@@ -140,6 +140,12 @@ are built:
 .. module:: sphinx.ext.mathjax
    :synopsis: Render math using JavaScript via MathJax.
 
+.. warning::
+   Version 4.0 changes the version of MathJax used to version 3. You may need to
+   override ``mathjax_path`` to
+   ``https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML``
+   or update your configuration options for version 3.
+
 .. versionadded:: 1.1
 
 This extension puts math as-is into the HTML files.  The JavaScript package
@@ -161,14 +167,14 @@ Sphinx but is set to automatically include it from a third-party site.
    MathJax.
 
    The default is the ``https://`` URL that loads the JS files from the
-   `cdnjs`__ Content Delivery Network. See the `MathJax Getting Started
+   `jsdelivr`__ Content Delivery Network. See the `MathJax Getting Started
    page`__ for details. If you want MathJax to be available offline or
    without including resources from a third-party site, you have to
    download it and set this value to a different path.
 
-   __ https://cdnjs.com
+   __ https://www.jsdelivr.com/
 
-   __ https://docs.mathjax.org/en/latest/start.html
+   __ https://www.mathjax.org/#gettingstarted
 
    The path can be absolute or relative; if it is relative, it is relative to
    the ``_static`` directory of the built docs.

sphinx/ext/mathjax.py

@@ -96,8 +96,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     # more information for mathjax secure url is here:
     # https://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
     app.add_config_value('mathjax_path',
-                         'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?'
-                         'config=TeX-AMS-MML_HTMLorMML', 'html')
+                         'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js',
+                         'html')
     app.add_config_value('mathjax_options', {}, 'html')
     app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
     app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')

tests/test_ext_math.py

@@ -71,8 +71,8 @@ def test_mathjax_options(app, status, warning):
 
     content = (app.outdir / 'index.html').read_text()
     assert ('<script async="async" integrity="sha384-0123456789" '
-            'src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?'
-            'config=TeX-AMS-MML_HTMLorMML"></script>' in content)
+            'src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">'
+            '</script>' in content)
 
 
 @pytest.mark.sphinx('html', testroot='ext-math',