developer/galaxy-game
1
1
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

fix(site): formulas — downgrade markdown-it-mathjax3 to v4 (fix hydration)
Build · Site / build (push) Successful in 8s
Details
Tests · Integration / integration (pull_request) Successful in 1m42s
Details
Build · Site / build (pull_request) Successful in 8s
Details
Tests · Go / test (pull_request) Successful in 3m18s
Details
Tests · UI / test (pull_request) Successful in 3m24s
Details

Browse Source 
The duplicate-then-disappearing formulas were a Vue hydration mismatch,
not a CSS problem. markdown-it-mathjax3 v5 pulls the `mathxyjax3` fork,
which emits each formula's CSS as an in-content `<style>` block scoped to
a per-container `#mjx-<id>` that the static build never sets. The orphaned
scoped CSS left the screen-reader MathML twin visible (the duplicate), and
the in-`<main>` `<style>` elements break VitePress/Vue hydration
("Hydration completed but contains mismatches"), which strips the SVG
glyph `<path>`s and blanks every formula after the page finishes loading.

Downgrade to markdown-it-mathjax3 ^4.3.2 — the mathjax-full-based version
VitePress officially supports. It uses `juice` to inline all CSS into the
element `style` attributes (no in-content `<style>`), so hydration is
clean (glyphs survive) and the MathML twin is hidden by its own inlined
style (no duplicate). This also drops the earlier custom.css workaround,
which only treated the symptom and itself blanked the formulas.

Verified with a headless Chromium render of the built /ru/rules: all 10
formulas keep their glyph paths after hydration, no console mismatch, no
duplicate copies.
This commit is contained in:
Ilia Denisov
2026-05-31 17:03:16 +02:00
parent 9b689b2885
commit f9f725f657
3 changed files with 300 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files
site/.vitepress/theme/custom.css
-23
View File
@@ -8,26 +8,3 @@
"Fira Code", "DejaVu Sans Mono", Menlo, Consolas, monospace;
--vp-font-family-mono: var(--vp-font-family-base);
}
/*
* markdown-it-mathjax3 renders each formula as a visible SVG plus a MathML
* twin (<mjx-assistive-mml>) for screen readers, and hides the twin with CSS
* scoped to a per-container `#mjx-<id>` selector. In the static build the
* containers carry no `id`, so that scoped rule matches nothing and the twin
* shows up as a second, oversized (theme-monospaced) copy of every formula.
* Hide it globally with the standard visually-hidden pattern: it stays in the
* DOM for assistive tech but is removed from view and from layout.
*/
mjx-assistive-mml {
position: absolute !important;
top: 0;
left: 0;
width: 1px !important;
height: 1px !important;
padding: 0 !important;
border: 0 !important;
overflow: hidden !important;
clip: rect(0 0 0 0) !important;
clip-path: inset(50%) !important;
white-space: nowrap !important;
}