Fix MathJax equations not re-rendering after instant navigation - #543
Merged
Conversation
scrise/plotting/__init__.py unconditionally imports stability.py, which imports tlviz.factor_tools. tlviz was only listed in the "analysis" dependency group, not in the package's core dependencies, so a plain `pip install scRISE` followed by `import scrise.plotting` raised ModuleNotFoundError. Add tlviz to core dependencies, matching the existing precedent of matplotlib/seaborn/hdf5plugin being both core deps and members of the analysis group, and regenerate uv.lock. Fixes #541 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The theme enables navigation.instant, which swaps page content via client-side fetch instead of a full page load. MathJax's default startup only typesets once on initial load, so pymdownx.arithmatex equations on any page reached via instant navigation stayed as raw LaTeX source instead of rendering. Add docs/javascripts/mathjax.js, which configures MathJax's tex delimiters/options to match arithmatex's generic mode and subscribes to document$ (mkdocs-material's instant-navigation event) to clear and re-typeset MathJax on every page swap, per mkdocs-material's documented MathJax + instant navigation setup. Load it before the polyfill/MathJax CDN scripts in extra_javascript. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Root cause
mkdocs.ymlalready hadpymdownx.arithmatex(withgeneric: true) enabled and included the MathJax CDN script viaextra_javascript, so equations render correctly on a page's first load.However, the theme also enables
navigation.instant, which swaps page content client-side (fetch + DOM replace) instead of doing a full page load when navigating between docs pages. MathJax's default runtime only auto-typesets once, on the initial page load — it has no way to know thatnavigation.instantswapped in new<span class="arithmatex">…</span>markup on a subsequent page, so any docs page reached via in-app navigation showed raw$...$/$$...$$LaTeX source instead of rendered math.This is a documented gotcha for MathJax + mkdocs-material's instant navigation feature: MathJax needs to be explicitly re-typeset via a
document$.subscribe(...)hook (mkdocs-material's instant-navigation event) on every page swap.Fix
docs/javascripts/mathjax.js, which:tex.inlineMath/tex.displayMathdelimiters andoptions.processHtmlClassto match whatpymdownx.arithmatex(generic mode) emitsdocument$and clears/re-typesets MathJax on every instant-navigation page swapextra_javascriptinmkdocs.yml, loaded before the polyfill and MathJax CDN scripts (sowindow.MathJaxconfig is set before the MathJax runtime script parses it).Test plan
uv sync --group docsuv run mkdocs build --strictcompletes with no errors/warningssite/component_ordering/index.html,site/tutorial/index.html, etc.) contains<span class="arithmatex">spans from equations indocs/component_ordering.md,docs/tutorial.md, anddocs/unequal_cell_counts.mddocs/javascripts/mathjax.jsis emitted in the page<head>before the polyfill/MathJax CDN<script>tags, in the correct order for MathJax to pick up the configpyproject.toml/dependency changes — that's tracked separately in scrise.plotting.stability imports tlviz, which is not declared as a dependency #541)Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
🤖 Generated with Claude Code