feat(web): render $…$ and $$…$$ math with KaTeX

[wayne930242]

Summary

Notes showed LaTeX math as raw $…$ / $$…$$ source. This renders it with KaTeX everywhere note Markdown is read:

• renderNote (preview, Screen cards, Study lanes, tables and directive bodies) — a marked extension in apps/web/src/lib/math.ts: a block token for $$…$$ on its own lines (multi-line allowed) and an inline token for $…$ / $$…$$ inside text.
• Live-markdown editor — $…$ and $$…$$ are replaced by a MathFormula widget; the source comes back while the cursor is on the formula's lines, and clicking a formula puts the cursor there. A display formula alone on its lines is drawn as a block. Code, HTML blocks, tables, mermaid fences and collapsed directives are excluded from the scan (tables/directives render their own math through renderNote).

Parsing rules (shared by both surfaces)

Pandoc's tex_math_dollars rules, so prices stay text: an inline opener must be followed by a non-space, the closer must follow a non-space and not be followed by a digit, and inline math stays on one line. Display math may span lines but not a blank line. \$ escapes a dollar. It costs $5 and $10 stays literal.

Safety

• KaTeX runs with trust: false (no \href/\url/\html* output) and throwOnError: false (a bad formula shows as a red error in place).
• output: 'html': DOMPurify drops MathML <semantics>/<annotation> but keeps their text, which would leak the TeX source into the formula. The wrapper <span class="note-math" role="math" aria-label="…TeX…"> carries the source for assistive technology instead.
• The rendered HTML still passes through the existing DOMPurify config unchanged; tests run against the real sanitizer.

Dependency

katex@^0.16.47 — the version mermaid 12 already pins, so the app ships one KaTeX copy and the lockfile gains three lines (0.18.x would add a second copy and re-resolve unrelated peers).

Tests

• apps/web/src/lib/math.test.ts (jsdom + real DOMPurify): scanner rules, inline/display/multi-line rendering, sample-note formulas next to CJK punctuation ($p(9)$, $|\{\text{Socrates}\}|$, $\Box\exists x Fx$, $\#(F)$), prices and code stay literal, tables and directives, sanitizer safety, parse errors. 5 of these failed before the change.
• apps/web/src/components/live-markdown/math.test.ts: editor widgets, cursor reveal, tables excluded.
• pnpm test 196 files / 1400 tests pass; pnpm lint clean; tsc --noEmit and vite build pass. pnpm format:check reports the same 10 pre-existing files as core; none are touched here.

Print / PDF export

note-export.ts builds a standalone srcdoc frame that loads none of the app's stylesheets, so it now inlines KaTeX's stylesheet (katex.min.css?inline). Vite rewrites the font url()s to root-absolute asset paths (/assets/KaTeX_*.woff2 in the build), which the frame resolves against the app's URL. Printing waits for document.fonts.ready so formulas are not laid out in fallback fonts. The print document builder is extracted as printDocument(); note-export.math.test.ts checks it carries the KaTeX rules and font faces (a root vitest.config.ts lets Vitest load KaTeX CSS instead of emptying it).

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
mygitnotes-gitlab-test	Building	Preview	Sep 27, 2026 7:58am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
my-gh-core	Ignored	Preview	Sep 27, 2026 7:58am UTC