diff --git a/CHANGES b/CHANGES index a09e1913764..b8375e2df4c 100644 --- a/CHANGES +++ b/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 diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index 780e57ee29d..655364767b3 100644 --- a/doc/usage/extensions/math.rst +++ b/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. diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index cc3cd4ba34e..59eb160472e 100644 --- a/sphinx/ext/mathjax.py +++ b/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') diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py index 4df7d47c7c2..d094def7ae7 100644 --- a/tests/test_ext_math.py +++ b/tests/test_ext_math.py @@ -71,8 +71,8 @@ def test_mathjax_options(app, status, warning): content = (app.outdir / 'index.html').read_text() assert ('' in content) + 'src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">' + '' in content) @pytest.mark.sphinx('html', testroot='ext-math',