👌 IMPROVE: Simplify and fix mathjax config override for Sphinx 8/9

- Remove dead Sphinx 3 / MathJax 2 code path (`mathjax_config['tex2jax']`)
  since only Sphinx >=8 is supported.
- Add mathjax4_config support for Sphinx 9, preferring whichever config
  the user has explicitly set.
- Fix default case: processHtmlClass is now always applied even when no
  user mathjax config is set.
- Simplify log_override_warning to use the actual config attribute name
  instead of a version number.
- Add tests for default config, myst_update_mathjax=False, and
  mathjax4_config override warning (Sphinx 9 only).

Author: chrisjsewell

myst_parser/sphinx_ext/mathjax.py

@@ -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,43 +55,33 @@ def override_mathjax(app: Sphinx):
 
     mjax_classes = app.env.myst_config.mathjax_classes  # type: ignore[attr-defined]
 
-    mathjax_opt = None
-    for opt in ("mathjax4_config", "mathjax3_config"):
-        if getattr(app.config, opt, None):
-            mathjax_opt = opt
-            break
-    if mathjax_opt is not None:
-        # sphinx 4 + mathjax 3
-        # sphinx 9 + mathjax 4
-        config = getattr(app.config, opt, {}) or {}
-        config.setdefault("options", {})
-        if (
-            "processHtmlClass" in config["options"]
-            and config["options"]["processHtmlClass"] != mjax_classes
-        ):
-            log_override_warning(
-                app,
-                3,
-                config["options"]["processHtmlClass"],
-                mjax_classes,
-            )
-        config["options"]["processHtmlClass"] = mjax_classes
-        setattr(app.config, opt, config)
-    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)
+    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,81 @@ 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(
     sys.platform == "win32",
     reason="Unicode encoding issues on Windows",