👌 IMPROVE: MathJax 4 compatibility (Sphinx 9) (#1110)

Sphinx 9 introduced `mathjax4_config` alongside the existing
`mathjax3_config`. This PR updates MyST-Parser's mathjax override logic
to handle both.

### Changes

- Remove dead Sphinx 3 / MathJax 2 code path
(`mathjax_config['tex2jax']`) — MyST-Parser requires Sphinx ≥ 8
- Add `mathjax4_config` support: prefer whichever config the user has
explicitly set, falling back to the Sphinx version's default
(`mathjax4_config` for Sphinx 9+, `mathjax3_config` for 8)
- Ensure `processHtmlClass` is always applied even when no user mathjax
config is pre-set
- Simplify `log_override_warning` to use the actual config attribute
name
- Fix typo in module docstring ("mrakdown-it-py" → "markdown-it-py")

### Tests added

- `test_mathjax_default` — verifies `processHtmlClass` is set with no
user config
- `test_mathjax_no_override` — verifies `myst_update_mathjax=False`
skips override
- `test_mathjax4_warning` — verifies warning when overriding
`mathjax4_config` (Sphinx 9+)
- `test_mathjax3_config_on_sphinx9` — verifies explicit
`mathjax3_config` is still respected on Sphinx 9

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>

Author: 3 people

myst_parser/sphinx_ext/mathjax.py

@@ -3,7 +3,7 @@
 This fixes two issues:
 
 1. Mathjax should not search for ``$`` delimiters, nor LaTeX amsmath environments,
-   since we already achieve this with the dollarmath and amsmath mrakdown-it-py plugins
+   since we already achieve this with the dollarmath and amsmath markdown-it-py plugins
 2. amsmath math blocks should be wrapped in mathjax delimiters (default ``\\[...\\]``),
    and assigned an equation number
 
@@ -20,17 +20,13 @@
 logger = logging.getLogger(__name__)
 
 
-def log_override_warning(app: Sphinx, version: int, current: str, new: str) -> None:
+def log_override_warning(app: Sphinx, config_name: str, current: str, new: str) -> None:
     """Log a warning if MathJax configuration being overridden."""
     if logging.is_suppressed_warning("myst", "mathjax", app.config.suppress_warnings):
         return
-    config_name = (
-        "mathjax3_config['options']['processHtmlClass']"
-        if version == 3
-        else "mathjax_config['tex2jax']['processClass']"
-    )
     logger.warning(
-        f"`{config_name}` is being overridden by myst-parser: '{current}' -> '{new}'. "
+        f"`{config_name}['options']['processHtmlClass']` "
+        f"is being overridden by myst-parser: '{current}' -> '{new}'. "
         "Set `suppress_warnings=['myst.mathjax']` to ignore this warning, or "
         "`myst_update_mathjax=False` if this is undesirable."
     )
@@ -59,37 +55,35 @@ def override_mathjax(app: Sphinx):
 
     mjax_classes = app.env.myst_config.mathjax_classes  # type: ignore[attr-defined]
 
-    if "mathjax3_config" in app.config:
-        # sphinx 4 + mathjax 3
-        app.config.mathjax3_config = app.config.mathjax3_config or {}
-        app.config.mathjax3_config.setdefault("options", {})
-        if (
-            "processHtmlClass" in app.config.mathjax3_config["options"]
-            and app.config.mathjax3_config["options"]["processHtmlClass"]
-            != mjax_classes
-        ):
-            log_override_warning(
-                app,
-                3,
-                app.config.mathjax3_config["options"]["processHtmlClass"],
-                mjax_classes,
-            )
-        app.config.mathjax3_config["options"]["processHtmlClass"] = mjax_classes
-    elif "mathjax_config" in app.config:
-        # sphinx 3 + mathjax 2
-        app.config.mathjax_config = app.config.mathjax_config or {}
-        app.config.mathjax_config.setdefault("tex2jax", {})
-        if (
-            "processClass" in app.config.mathjax_config["tex2jax"]
-            and app.config.mathjax_config["tex2jax"]["processClass"] != mjax_classes
-        ):
-            log_override_warning(
-                app,
-                2,
-                app.config.mathjax_config["tex2jax"]["processClass"],
-                mjax_classes,
-            )
-        app.config.mathjax_config["tex2jax"]["processClass"] = mjax_classes
+    # Determine which mathjax config to modify:
+    # prefer whichever the user has explicitly set, falling back to
+    # the Sphinx version's default (mathjax4_config for Sphinx 9+, mathjax3_config for 8).
+    # Note: if a user sets both mathjax3_config and mathjax4_config, we only update
+    # the v4 config (Sphinx emits both but v4 clobbers v3 at runtime anyway).
+    has_mjax4 = hasattr(app.config, "mathjax4_config")
+    if has_mjax4 and app.config.mathjax4_config:
+        config_attr = "mathjax4_config"
+    elif app.config.mathjax3_config:
+        config_attr = "mathjax3_config"
+    elif has_mjax4:
+        config_attr = "mathjax4_config"
+    else:
+        config_attr = "mathjax3_config"
+
+    config: dict = getattr(app.config, config_attr) or {}  # type: ignore[type-arg]
+    config.setdefault("options", {})
+    if (
+        "processHtmlClass" in config["options"]
+        and config["options"]["processHtmlClass"] != mjax_classes
+    ):
+        log_override_warning(
+            app,
+            config_attr,
+            config["options"]["processHtmlClass"],
+            mjax_classes,
+        )
+    config["options"]["processHtmlClass"] = mjax_classes
+    setattr(app.config, config_attr, config)
 
 
 def html_visit_displaymath(self: HTMLTranslator, node: nodes.math_block) -> None:

tests/test_sphinx/sourcedirs/mathjax4/conf.py

@@ -0,0 +1,4 @@
+extensions = ["myst_parser"]
+exclude_patterns = ["_build"]
+
+mathjax4_config = {"options": {"processHtmlClass": "other"}}

tests/test_sphinx/sourcedirs/mathjax4/index.md

@@ -0,0 +1,5 @@
+# Test
+
+```{math}
+a = 1
+```

tests/test_sphinx/sourcedirs/mathjax_default/conf.py

@@ -0,0 +1,2 @@
+extensions = ["myst_parser"]
+exclude_patterns = ["_build"]

tests/test_sphinx/sourcedirs/mathjax_default/index.md

@@ -0,0 +1,5 @@
+# Test
+
+```{math}
+a = 1
+```

tests/test_sphinx/test_sphinx_builds.py

@@ -595,6 +595,107 @@ def test_mathjax_warning(
     )
 
 
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "mathjax_default"),
+    freshenv=True,
+    confoverrides={"myst_enable_extensions": ["dollarmath"]},
+)
+def test_mathjax_default(
+    app,
+    status,
+    warning,
+):
+    """Test mathjax processHtmlClass is set even without user config."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    warnings = warning.getvalue().strip()
+    assert "overridden by myst-parser" not in warnings
+    # Verify processHtmlClass was applied to the appropriate config
+    if hasattr(app.config, "mathjax4_config"):
+        config = app.config.mathjax4_config
+    else:
+        config = app.config.mathjax3_config
+    assert config["options"]["processHtmlClass"] == (
+        "tex2jax_process|mathjax_process|math|output_area"
+    )
+
+
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "mathjax_default"),
+    freshenv=True,
+    confoverrides={
+        "myst_enable_extensions": ["dollarmath"],
+        "myst_update_mathjax": False,
+    },
+)
+def test_mathjax_no_override(
+    app,
+    status,
+    warning,
+):
+    """Test that myst_update_mathjax=False prevents config override."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    # processHtmlClass should NOT have been set
+    if hasattr(app.config, "mathjax4_config"):
+        assert app.config.mathjax4_config is None
+    else:
+        assert app.config.mathjax3_config is None
+
+
+@pytest.mark.skipif(
+    int(__import__("sphinx").__version__.split(".")[0]) < 9,
+    reason="mathjax4_config not available before Sphinx 9",
+)
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "mathjax4"),
+    freshenv=True,
+    confoverrides={"myst_enable_extensions": ["dollarmath"]},
+)
+def test_mathjax4_warning(
+    app,
+    status,
+    warning,
+):
+    """Test mathjax4_config override warning (Sphinx 9+)."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    warnings = warning.getvalue().strip()
+    assert (
+        "overridden by myst-parser: 'other' -> 'tex2jax_process|mathjax_process|math|output_area'"
+        in warnings
+    )
+
+
+@pytest.mark.skipif(
+    int(__import__("sphinx").__version__.split(".")[0]) < 9,
+    reason="mathjax4_config not available before Sphinx 9",
+)
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "mathjax"),
+    freshenv=True,
+    confoverrides={"myst_enable_extensions": ["dollarmath"]},
+)
+def test_mathjax3_config_on_sphinx9(
+    app,
+    status,
+    warning,
+):
+    """Test that explicit mathjax3_config is still respected on Sphinx 9."""
+    app.build()
+    assert "build succeeded" in status.getvalue()
+    warnings = warning.getvalue().strip()
+    # mathjax3_config was explicitly set, so myst should modify it (not mathjax4_config)
+    assert "mathjax3_config" in warnings
+    assert app.config.mathjax3_config["options"]["processHtmlClass"] == (
+        "tex2jax_process|mathjax_process|math|output_area"
+    )
+
+
 @pytest.mark.skipif(
     sys.platform == "win32",
     reason="Unicode encoding issues on Windows",