Track KaTeX upgrades: own the stylesheet href, bump to 0.16.x now, 0.18.x in lockstep with QuantEcon/mystmd

[mmcky]

Summary

Three KaTeX versions are in play on our published pages, and only one of them is currently pinned where we control it directly:

Layer	Version	Where
Page stylesheet	0.15.2 (CDN)	KatexCSS link descriptor inherited from @myst-theme/site, imported in app/routes/_index.tsx and app/routes/$.tsx
Theme's own katex dependency	^0.16.21	package.json
Equation markup baked into node.html	^0.15.2 today; ^0.16 after QuantEcon/mystmd#80	QuantEcon/mystmd build (myst-transforms)

Why it matters: KaTeX 0.18.0 (2026-07-17) renamed/prefixed the internal CSS classes (KaTeX/KaTeX#4229 — e.g. the equation-tag column went from class="tag" to class="katex-tag"), so markup and stylesheet must stay on the same side of the 0.18 boundary or equations render unstyled. Full analysis in QuantEcon/mystmd#80. This issue tracks getting the theme's KaTeX current in two steps that respect that boundary.

Step 1 — now, safe: own the stylesheet href and bump it to 0.16.x

Replace the imported KatexCSS with our own link descriptor pointing at a katex@0.16.x stylesheet (matching the resolved version of our own katex dependency, currently the 0.16 line). This is a one-line change in each of the two routes plus a small constant, and needs no myst-theme fork. The 0.16 line kept the 0.15-era class vocabulary, so a 0.16.x stylesheet renders markup from both current mystmd (0.15.6) and post-bump mystmd (0.16.47) correctly, and additionally picks up the .eqn-num::before counter rules and four years of CSS fixes the 0.15.2 sheet lacks.

Nice-to-have while we are in there: derive the href version from the installed katex package version at build time, so the stylesheet can never silently skew from the dependency again.

Step 2 — later, coordinated: move to latest (0.18.x) in lockstep with QuantEcon/mystmd

The jump to the 0.18 line must happen simultaneously in the markup generator (the katex pin in QuantEcon/mystmd's myst-transforms / myst-to-jats) and here (the katex dependency and the stylesheet href) — crossing one without the other breaks rendering in either direction. Since both repos are ours, this needs no upstream coordination, but there is no urgency: everything the per-row equation numbering work (QuantEcon/mystmd#73) needs landed in 0.16.0.

Upstream note: stock myst-theme still hardcodes the 0.15.2 CDN href (packages/site/src/loaders/links.ts in jupyter-book/myst-theme), so an upstream PR bumping that to 0.16.x would help the broader community and is a low-effort companion to step 1.

Related

• Bump KaTeX ^0.15.2 → ^0.16 (per-row equation numbering machinery; prerequisite for #73) mystmd#80 — bump katex pin ^0.15.2 → ^0.16 in the markup generator
• Number align/gather rows per-row (amsmath semantics) — honor per-row \label, \tag, \nonumber mystmd#73 — per-row align / gather equation numbering (consumer of the 0.16 features)

[mmcky]

Status update (2026-08-20 tracker audit): Step 1 is delivered — shipped in v2.3.0 via #125.

#125 replaced the imported KatexCSS descriptor with a self-hosted one: app/links.ts bundles the stylesheet directly from the installed katex package (import katexCss from 'katex/dist/katex.min.css'), and both routes (app/routes/_index.tsx, app/routes/$.tsx) now import it. Since the theme's katex dependency is ^0.16.21, the served stylesheet is on the 0.16 line — and because the CSS is bundled from the installed package, the nice-to-have is covered too: the stylesheet version can never silently skew from the dependency again. It also goes further than this issue asked (the CDN origin is gone entirely, not just re-versioned).

Remaining scope of this issue is Step 2 only: the coordinated jump to the 0.18 line, in lockstep with the katex pin in QuantEcon/mystmd's myst-transforms (the 0.18 class-rename boundary, KaTeX/KaTeX#4229). No urgency — everything the per-row equation numbering needs landed in 0.16.