Skip to content

Upgrade to MathJax v3 (replaces retired cdn.mathjax.org)#38

Open
aoboturov wants to merge 2 commits intodeepgenerativemodels:masterfrom
aoboturov:fix-mathjax-cdn
Open

Upgrade to MathJax v3 (replaces retired cdn.mathjax.org)#38
aoboturov wants to merge 2 commits intodeepgenerativemodels:masterfrom
aoboturov:fix-mathjax-cdn

Conversation

@aoboturov
Copy link
Copy Markdown

@aoboturov aoboturov commented May 5, 2026

Summary

The site loaded MathJax from //cdn.mathjax.org/..., retired in 2017, so all math on the rendered notes (e.g. the autoregressive page) was broken — symbols like \mathcal{D} showed up as tofu boxes.

This PR migrates from MathJax v2 (dead CDN) to MathJax v3 on jsDelivr. v3 was chosen over a v2-on-jsDelivr swap because v2's HTML-CSS renderer was failing to load its calligraphic webfont in testing, and v3 ships fonts inline in a single bundle, which is more robust.

Changes

  • Replace the dead cdn.mathjax.org script tag with https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js.
  • Move the MathJax config from _layouts/post.html into _includes/head.html, since v3 requires window.MathJax = {...} to be set before the loader runs.
  • Convert the v2 MathJax.Hub.Config({ TeX: { Macros: ... } }) syntax to v3 window.MathJax = { tex: { macros: ... } }. All custom macros (\Dc, \Exp, \KL, \note, etc.) are preserved.
  • Explicitly enable $...$ / $$...$$ delimiters — v3 defaults to only \(...\) / \[...\], but the source markdown uses $.
  • Add a startup.pageReady shim that converts kramdown's legacy <script type="math/tex">...</script> wrappers into \(...\) / \[...\] before typesetting. v3 doesn't recognise the v2 script-tag protocol, and the built HTML in docs/ already contains those wrappers.
  • Load the TeX color package so \textcolor{...} (used in the \note macro) keeps working.
  • Apply the same edits to the pre-built docs/**/index.html files so the fix takes effect on GitHub Pages without a Jekyll rebuild (_config.yml has destination: docs).

Test plan

  • Open any notes page (e.g. /notes/autoregressive/) — \mathcal{D}, n, \mathbf{x}, display equations, and macros all render properly.
  • Browser console shows no cdn.mathjax.org has been retired warning and no MathJax errors.
  • Verified locally by serving docs/ under the /notes baseurl and confirming math renders end-to-end.

Artem Oboturov added 2 commits May 5, 2026 13:30
The cdn.mathjax.org CDN was retired in 2017
(see https://www.mathjax.org/cdn-shutting-down/), which broke all
math rendering on the site. Switch to jsdelivr's MathJax v2 mirror,
keeping v2 because the inline MathJax.Hub.Config is v2-API.
The v2 jsdelivr swap got the script loading again, but two follow-up
issues remained: v2's HTML-CSS renderer was missing the calligraphic
webfont (\mathcal{D} rendered as tofu), and v3 by default ignores
kramdown's <script type="math/tex"> wrappers and $...$ inline math.

Changes:
- Move MathJax config from _layouts/post.html into _includes/head.html
  so it's set before the loader (required by v3).
- Convert v2 MathJax.Hub.Config syntax to v3 window.MathJax = {...}.
- Enable $...$ / $$...$$ delimiters explicitly (v3 default is only
  \(...\) and \[...\]).
- Add a pageReady shim that unwraps kramdown's <script type="math/tex">
  tags into raw \(...\) / \[...\] before typesetting.
- Load tex-mml-chtml.js v3 bundle from jsdelivr (ships fonts inline).
@aoboturov aoboturov changed the title Replace retired cdn.mathjax.org with jsdelivr CDN Upgrade to MathJax v3 (replaces retired cdn.mathjax.org) May 5, 2026
@aoboturov
Copy link
Copy Markdown
Author

Live preview of this branch: https://aoboturov.github.io/notes/autoregressive/ (and other notes paths). Compare against the broken https://deepgenerativemodels.github.io/notes/autoregressive/ — the calligraphic $\mathcal{D}$, inline italics, and display equations should all render here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant