DEF-1 — Make math render on buckyverse WikiJS (Phase 1) — Design

Status: Approved 2026-07-01
Source item: DEF-1 (work/DEFERRED.md) — re-scoped from “full codexis book build” to the actual root-cause fix
Branch: pluck/def-1-codexis-dome-cookbook-render-math

Goal

Make mathematics render as typeset math on buckyverse WikiJS — both wiki-wide
(by enabling the renderer) and specifically on the Dome Cookbook of Geodesic
Geometry page (by giving its transcription clean, consistent math markup). The
full codexis LaTeX/ebook build remains a deferred follow-up.

Root cause (investigated 2026-07-01)

Math on buckyverse does not render — formulas display as raw literal
$$…$$ / $…$ source, even on the completed codexis build
geodesic_math_and_how_to_use_it/ (which ships 396 inline + 76 block math
markers). The renderers table (from the 2026-03-15 prod backup) shows:

• markdownKatex = disabled ({"useInline":true,"useBlocks":true})
• markdownMathjax = enabled — but WikiJS’s MathJax path defers to client-side
  JS that isn’t loading on this theme, so math passes through as literal text.
  (Evidence: some html-editor pages inject their own <script>MathJax.js</script>
  as a per-page workaround; a codexis TODO note reads “Render math with MathJax
  when served as HTML.”)

Server-side KaTeX renders to static HTML/MathML at save time and needs no
client JS, so enabling it is the robust fix.

Architecture

Three independent pieces: (1) a one-time WikiJS renderer config change
(user-applied), (2) a re-render of affected pages (WikiJS re-renders on
save), and (3) a content markup cleanup of the Dome Cookbook transcription.
They compose: clean the markup and re-push, have the user enable KaTeX, re-push
to re-render, verify.

Components

1. Enable server-side KaTeX (wiki-wide fix) — user-applied

The user toggles in Administration → Rendering → Markdown: enable KaTeX,
disable MathJax (avoid double-processing $$). Native, reversible, safest.
This design does not write to the prod DB. I coordinate timing and verify;
I do not perform this step.

2. Re-render affected pages

WikiJS caches rendered HTML per page and only re-renders on save. After KaTeX is
enabled:

• Dome Cookbook — re-pushed in step 4, which re-renders it with KaTeX.
• geodesic_math and other math pages — need re-rendering too, but that is a
  wiki-wide operation (WikiJS admin rebuild, or re-saving each page). Treated as
  verify-and-report: I confirm the effect on geodesic_math and report what a
  full re-render would cover; I do not silently re-render 23K pages.

3. Clean the Dome Cookbook math markup

Current transcriptions have inconsistent math (only 12/48 pages carry any $,
and those mix $\angle$-style symbols with plain-text formulas like
ALT. = 10 sin 60°). Fix:

• Identify the math-bearing pages — the Trig Review, Frequency, Spherical
  Trig, Chord Factors, Comparison-with-Fuller, and Dihedral Angles derivation
  pages (roughly pages 3–44; the exact set determined by scanning transcriptions
  and page images for formula content).
• Re-transcribe those pages via OpenRouter qwen2.5-vl-72b with a
  KaTeX-strict prompt: wrap every formula/equation in $…$ (inline) or
  $$…$$ (display), use standard LaTeX (\sin, \cos, \overline{},
  \frac{}{}, \angle, \therefore, ^\circ), transcribe prose normally, and
  describe diagrams/tables in italics (as before).
• Preserve the prose-only pages’ existing transcriptions unchanged, and
  re-apply the known correction (page 14 ICOSAHEDRON).
• Page images remain the authoritative diagram source; the cleaned transcription
  is the rendered-math + search layer beneath each image.
• Rebuild dome_cookbook_of_geodesic_geometry/index.md (same assembly + heading
  demotion as the original ingest) and re-push via publish-to-buckyverse.

4. Verify

• Fetch the live Dome Cookbook page; confirm formulas render as KaTeX
  (class="katex" / MathML present) and no raw $$…$$ remains in the math
  sections.
• Re-render + spot-check geodesic_math as the wiki-wide proof (bonus).

Sequence

1. Clean markup → rebuild index.md → re-push Dome Cookbook (git commit + live push).
2. Ask the user to enable KaTeX / disable MathJax in the Admin UI.
3. Re-push the Dome Cookbook page to re-render it under KaTeX.
4. Verify KaTeX renders live; spot-check geodesic_math; report wiki-wide re-render status.

Scope / risk

• Enabling KaTeX is a production, site-wide renderer change, but reversible
  (a single admin toggle) and a net win for every math page. The user applies it.
• Re-pushing to prod publishes content other people read — done deliberately,
  verified after.
• Out of scope (still deferred): the full codexis LaTeX/EPUB/PDF ebook build
  with typeset math + diagram reconstruction. Re-filed as its own deferred item
  in housekeeping.

Testing / verification

Content/ops task; no unit tests. Success =

1. Dome Cookbook math markup is consistent and KaTeX-valid.
2. Live Dome Cookbook page renders math (real class="katex" output, no raw $$).
3. geodesic_math confirms the wiki-wide effect after re-render.