[kevinhowbrook]

What is the context of this PR?

This PR upgrades wagtailmath 1.4 to wagtail-polymath 2.0.3, which moves equations from using MathJax 2.7.9 to MathJax 4.1.3.

MathJax 4 is served from the ONS CDN: ONSdigital/cdn.ons.gov.uk-vendor#54 added MathJax 4.1.3 and its font package. That PR is merged, but waiting on deployment (it deployed fine last time - I've no idea why it's 404ing still)

Upstream issues raised during this upgrade

• MathJax admin preview is blank when MathJax hasn't finished starting up wagtail-nest/wagtail-polymath#31: admin preview blank until MathJax had loaded (Information page test rebase 6 #32)
• polymath_stylesheets outputs src instead of href, so the Katex stylesheet never loads wagtail-nest/wagtail-polymath#33: KaTeX stylesheet never loaded (Update design system to 72.1.0 #34)
• Single dollar signs in page text are typeset as maths wagtail-nest/wagtail-polymath#35: single dollar signs typeset as maths (Update the README #36)

all fixed in polymath 2.0.3

How to review

MathJax 4 isn't up on cdn.ons.gov.uk yet, so maybe wait for that, or locally serve the vendor repo (see below).

1. Before switching, on main, create or find a page with a few equation blocks, so you can check existing content
   survives the upgrade. For example:
   • $$\bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i$$ (display)
   • \(E = mc^2\) (inline)
   • \[a + b = c\] (display)
   • a rich-text paragraph with "prices rose from $5 to $10"
2. Check out this branch
3. Run the upgrade: poetry install (swaps wagtailmath for wagtail-polymath 2.0.3).
4. Open the page from step 1:
   • Published page, "View draft" and the preview panel: all equations render, and "$5 to $10" stays as text
   • Editor: the equation previews render as soon as the page opens, and update as you type a new equation
   • Save and publish without changing anything: no validation errors
5. no console errors or CSP errors should be seen

Serving the vendor repo locally until the CDN is live

In a checkout of ONSdigital/cdn.ons.gov.uk-vendor main, serve it with CORS on port 8001:

python3 -c "
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
class H(SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header('Access-Control-Allow-Origin', '*'); super().end_headers()
ThreadingHTTPServer(('127.0.0.1', 8001), H).serve_forever()"

Then point dis-wagtail at it in cms/settings/local.py (after step 3, because main uses a different
WAGTAIL_POLYMATH format):

from cms.settings.base import SECURE_CSP, WAGTAIL_CSP, WAGTAIL_POLYMATH

LOCAL_CDN = "http://localhost:8001"
WAGTAIL_POLYMATH["libraries"][0]["url"] = f"{LOCAL_CDN}/vendor/mathjax/4.1.3/tex-mml-chtml.js"
for _csp in (SECURE_CSP, WAGTAIL_CSP):
    for _directive in ("script-src", "style-src", "font-src", "img-src"):
        _csp[_directive].append(LOCAL_CDN)

Deployment Safety

Bleed and Sandbox deploy automatically on merge, so PRs should be safe to deploy immediately.

Please select one:

• Safe to auto-deploy
• Not safe to auto-deploy (at the moment)

Blocked on the CDN. https://cdn.ons.gov.uk/vendor/mathjax/4.1.3/tex-mml-chtml.js must 200 before this can merge. Once it does, then this is OK to auto deploy.

Follow-up Actions

• Confirm the CDN files are live, then re-run the equation functional test (it fails until then) and do a final
  check without local overrides
• Check the no-JS fallback (the SVG rendered with matplotlib) still works - Checked locally, this looks fine to me
• As requested by Mebin, document the MathJax 2 to 4 changes and what might break for publishers, under the
  NWP Confluence folder
• KaTeX: polymath 2 also supports KaTeX, which looks much the same to publishers but is smaller and loads faster
  • Raise a card for what needs to happen before we can use KaTeX
  • Add a Confluence doc for publishers on using KaTeX

---

Ticket: CMS-1419

[github-actions]

This PR is being prevented from merging because you have added one of our blocking labels: do not merge, status: Blocked

You'll need to remove it before this PR can be merged.

[zerolab]

q: would the fonts loader trick work with the defaults too? If so, we could make that change in the library

[kevinhowbrook]

Looking into this - it might be worth defining an extra config dict polymath side - meaning I wouldn't have to do some juggling I'm doing in this pr, e.g

WAGTAIL_POLYMATH = {
    "engine": "mathjax",
    "libraries": [{"url": ".../4.1.3/tex-mml-chtml.js", "sri": "..."}],
    "mathjax_fonts_url": f"{ONS_CDN_URL}/vendor/mathjax/4.1.3/fonts",  # optional
    ... and perhaps speech/braille settings true/flase
}

[kevinhowbrook]

An idea here wagtail-nest/wagtail-polymath#38

[kevinhowbrook]

Some CI failures here are expected because the ons cdn vendor needs publishing

[kevinhowbrook]

This exists to adjust polymath's MathJax config, in the admin and on the front end:

• fonts load from the ONS CDN instead of jsdelivr
• speech and braille are off, because MathJax 4 runs them in a blob: worker (not CSP friendly.

This can go once polymath can take the config itself (wagtail-nest/wagtail-polymath#38). More detail is in docs/custom-features/equations.md.

[kevinhowbrook]

Marking as blocked for the moment, mostly because the CDN isn't published yet so the tests cannot pass, and ideally it would be nice to address wagtail-nest/wagtail-polymath#38 (that's not a blocker per se though)