Upgrade to MathJax 4.1.2 (#21)

Author: zerolab

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## Unreleased
 
+- Dropped support for Django < 5.2
+- Upgraded to MathJax 4.1.2, using [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity)
+  for the CDN script. The template tag has also changed to `mathjax_script`. See upgrade considerations
+
+### Upgrade considerations
+
+#### The project namespace changed to `wagtail_polymath`
+
+```diff
+# Old
+- from wagtailmath.blocks import MathBlock
+# New
++ from wagtail_polymath.blocks import MathBlock
+```
+
+and
+
+```diff
+# Old
+- {% load wagtailmath %}
+# New
++ {% load wagtail_polymath %}
+```
+
+#### The template tag has changed
+The `mathjax` template tag has changed to `mathjax_script` and should no longer be wrapped in `<script></script>`
+
+```diff
+# Old
+- {% load wagtailmath %}
+- <script src="{% mathjax %}"></script>
+# New
++ {% load wagtail_polymath %}
++ {% mathjax_script %}
+```
+
 ## 2.0.0.dev1 (2026-06-18)
 
 - The project namespace has changed from wagtailmath to wagtail_polymath.

README.md

@@ -71,14 +71,14 @@ class MyPage(Page):
     ])
 ```
 
-Use the `mathjax` template tag in your front end template to load the
+Use the `mathjax_script` template tag in your front end template to load the
 MathJax library:
 
 ```django+html
 {% load wagtail_polymath %}
 ...
 
-<script src="{% mathjax %}"></script>
+{% mathjax_script %}
 ```
 
 

pyproject.toml

@@ -31,7 +31,7 @@ classifiers = [
 requires-python = ">=3.10"
 dynamic = ["version"]
 dependencies = [
-    "Django>=4.2",
+    "Django>=5.2",
     "Wagtail>=7.0"
 ]
 [project.optional-dependencies]

src/wagtail_polymath/static/wagtail_polymath/js/mathjax_init.js

@@ -0,0 +1,4 @@
+window.MathJax = {
+  loader: { load: ["input/asciimath"] },
+  tex: { inlineMath: { '[+]': [['$', '$']] } },
+};

src/wagtail_polymath/static/wagtail_polymath/js/wagtail_polymath.js

@@ -1,26 +1,18 @@
-// Update the preview area on input. Lifted directly from mathjax website examples
 class Preview {
-
-  //  Get the preview and buffer DIV's
-  //
   constructor(previewId, bufferId, inputId) {
     this.preview = document.getElementById(previewId);
     this.buffer = document.getElementById(bufferId);
     this.input = document.getElementById(inputId);
     this.delay = 150;        // delay after keystroke before updating
-    this.timeout = null;     // store setTimout id
+    this.timeout = null;     // store setTimeout id
     this.mjRunning = false;  // true when MathJax is processing
     this.mjPending = false;  // true when a typeset has been queued
     this.oldText = null;     // used to check if an update is needed
   }
 
-  //
-  //  Switch the buffer and preview, and display the right one.
-  //  (We use visibility:hidden rather than display:none since
-  //  the results of running MathJax are more accurate that way.)
-  //
-  SwapBuffers() {
-    var buffer = this.preview, preview = this.buffer;
+  // Swap buffer/preview so the freshly typeset one is shown.
+  swapBuffers() {
+    let buffer = this.preview, preview = this.buffer;
     this.buffer = buffer;
     this.preview = preview;
     buffer.style.visibility = "hidden";
@@ -29,76 +21,80 @@ class Preview {
     preview.style.visibility = "";
   }
 
-  //
-  //  This gets called when a key is pressed in the textarea.
-  //  We check if there is already a pending update and clear it if so.
-  //  Then set up an update to occur after a small delay (so if more keys
-  //    are pressed, the update won't occur until after there has been
-  //    a pause in the typing).
-  //  The callback function is set up below, after the Preview object is set up.
-  //
-  Update() {
+  // Debounce: typeset only after a pause in typing.
+  update() {
     if (this.timeout) {
       clearTimeout(this.timeout);
     }
-    this.timeout = setTimeout(this.callback, this.delay);
+
+    this.timeout = setTimeout(() => this.createPreview(), this.delay);
   }
 
-  //
-  //  Creates the preview and runs MathJax on it.
-  //  If MathJax is already trying to render the code, return
-  //  If the text hasn't changed, return
-  //  Otherwise, indicate that MathJax is running, and start the
-  //    typesetting.  After it is done, call PreviewDone.
-  //
-  CreatePreview() {
+  // Render input into the hidden buffer, then typeset it.
+  createPreview() {
     this.timeout = null;
-    if (this.mjPending) return;
-    var text = this.input.value;
-    if (text === this.oldtext) return;
-    if (this.mjRunning) {
-      this.mjPending = true;
-      MathJax.Hub.Queue(["CreatePreview", this]);
-    } else {
-      this.buffer.innerHTML = this.oldtext = text;
-      this.mjRunning = true;
-      MathJax.Hub.Queue(
-        ["Typeset", MathJax.Hub, this.buffer],
-        ["PreviewDone", this]
-      );
-    }
+    this.mjRunning = true;
+    this.mjPending = false;
+
+    const text = this.input.value;
+    if (text === this.oldText) return;
+    this.oldText = text;
+
+    let buffer = this.buffer;  // capture: SwapBuffers may run before the promise settles
+
+
+    MathJax.typesetClear([buffer]);  // drop metadata from the previous render
+
+    buffer.innerHTML = text;
+
+    MathJax.typesetPromise([buffer])
+      .then(() => {
+        this.mjRunning = false;
+        if (this.mjPending) {
+          this.update();
+        }
+        else {
+          this.previewDone();
+        }
+      })
+      .catch((err) => console.error("MathJax typeset failed:", err));
   }
 
-  //
-  //  Indicate that MathJax is no longer running,
-  //  and swap the buffers to show the results.
-  //
-  PreviewDone() {
+  previewDone() {
     this.mjRunning = this.mjPending = false;
-    this.SwapBuffers();
+    this.swapBuffers();
   }
 }
 
 
 function initMathJaxPreview(id) {
-  window.wagtailMathPreviews = window.wagtailMathPreviews || {};
+  const target = document.getElementById(id);
+  if (!target) {
+    return;
+  }
 
-  window.wagtailMathPreviews[id] = new Preview(
-    "MathPreview-" + id,
-    "MathBuffer-" + id,
-    id
-  );
+  const preview = new Preview("MathPreview-" + id, "MathBuffer-" + id, id);
 
-  // Cache a callback to the CreatePreview action
-  window.wagtailMathPreviews[id].callback = MathJax.Callback(["CreatePreview", window.wagtailMathPreviews[id]]);
-  window.wagtailMathPreviews[id].callback.autoReset = true; // make sure it can run more than once
-  window.wagtailMathPreviews[id].Update();
+  window.wagtailMathPreviews = window.wagtailMathPreviews || {};
+  window.wagtailMathPreviews[id] = preview;
 
-  // attach a keyup event listener so we update the preview
-  const target = document.getElementById(id);
-  if (target) {
-    target.addEventListener("keyup", function() {
-      window.wagtailMathPreviews[id].Update();
-    })
+  if (target.value) {
+    preview.update();
   }
+
+  target.addEventListener("keyup",  () => {
+    if (this.mjRunning) {
+      this.mjPending = true;
+    }
+    else {
+      preview.update()
+    }
+  });
 }
+
+window.MathJax = {
+  loader: { load: ["input/asciimath"] },  // "AM" isn't in tex-mml-chtml; add it explicitly
+  tex: {
+    inlineMath: { '[+]': [['$', '$']] }
+  },
+};

src/wagtail_polymath/templatetags/wagtail_polymath.py

@@ -1,11 +1,20 @@
 from django import template
+from django.forms.utils import flatatt
+from django.utils.html import format_html
+from wagtail.admin.staticfiles import versioned_static
 
-from wagtail_polymath.widgets import MATHJAX_VERSION
+from wagtail_polymath.widgets import MATHJAX_SRI, MATHJAX_VERSION
 
 
 register = template.Library()
 
 
 @register.simple_tag
-def mathjax(config="TeX-MML-AM_CHTML"):
-    return f"https://cdnjs.cloudflare.com/ajax/libs/mathjax/{MATHJAX_VERSION}/MathJax.js?config={config}"
+def mathjax_script():
+    attributes = {"crossorigin": "anonymous", "integrity": MATHJAX_SRI, "defer": True}
+    return format_html(
+        '<script src="{init_path}"></script><script src="{path}"{attributes}></script>',
+        init_path=versioned_static("wagtail_polymath/js/mathjax_init.js"),
+        path=f"https://cdn.jsdelivr.net/npm/mathjax@{MATHJAX_VERSION}/tex-mml-chtml.js",
+        attributes=flatatt(attributes),
+    )

src/wagtail_polymath/widgets.py

@@ -1,8 +1,10 @@
 from django import forms
+from django.forms import Script
 from wagtail.admin.staticfiles import versioned_static
 
 
-MATHJAX_VERSION = "2.7.9"
+MATHJAX_VERSION = "4.1.2"
+MATHJAX_SRI = "sha256-dPV35kaoLq1rg+JbYf8p1kTrZamwMY+XIwaWUPwqtpU="
 
 
 class MathJaxWidget(forms.Textarea):
@@ -18,7 +20,14 @@ def build_attrs(self, *args, **kwargs):
     def media(self):
         return forms.Media(
             js=(
-                f"https://cdnjs.cloudflare.com/ajax/libs/mathjax/{MATHJAX_VERSION}/MathJax.js?config=TeX-MML-AM_HTMLorMML",
+                Script(
+                    f"https://cdn.jsdelivr.net/npm/mathjax@{MATHJAX_VERSION}/tex-mml-chtml.js",
+                    **{
+                        "crossorigin": "anonymous",
+                        "integrity": MATHJAX_SRI,
+                        "defer": True,
+                    },
+                ),
                 versioned_static("wagtail_polymath/js/wagtail_polymath.js"),
                 versioned_static(
                     "wagtail_polymath/js/wagtail_polymath-mathjax-controller.js"

tests/testapp/templates/testapp/math_page.html

@@ -1,7 +1,7 @@
 {% load wagtail_polymath %}
 <html>
 <head>
-    <script src="{% mathjax %}"></script>
+    {% mathjax_script %}
 </head>
 <body>
 <h1>{{ page.title }}</h1>

tox.ini

@@ -2,7 +2,7 @@
 min_version = 4.30
 
 envlist =
-    python{3.10}-django{4.2}-wagtail{7.0}-{sqlite}
+    python{3.10}-django{5.2}-wagtail{7.0}-{sqlite}
     python{3.11,3.12}-django{5.2}-wagtail{7.0,7.4}-{sqlite}
     python{3.13,3.14}-django{6.0}-wagtail{7.4}-{sqlite}
     python{3.14}-django{6.0}-wagtail{main}-{sqlite}
@@ -35,7 +35,6 @@ setenv =
 deps =
     coverage>=7.0,<8.0
 
-    django4.2: Django>=4.2,<4.3
     django5.2: Django>=5.2,<5.3
     django6.0: Django>=6.0,<6.1