Insight Vault

Fixing MathJax Rendering After Instant Navigation In MkDocs Material

2 min read

Symptom

When the Riemann zeta function page was opened directly from the browser address bar, MathJax rendered the formulas correctly.

When the same page was reached by clicking an internal link from the Artifacts page, the formulas stayed in their raw source form instead of being rendered.

Cause

MkDocs Material’s navigation.instant feature does not perform a full browser reload for internal navigation. It fetches the next page HTML and replaces the current page body.

Direct URL entry is a full page load, so MathJax runs automatically during the initial load. With instant navigation, the MathJax runtime is already loaded, and newly inserted .arithmatex blocks are not automatically processed again.

The problem was not the Markdown syntax. It was that a DOM post-processing library was not rerun after the page body changed.

Fix

The fix was to connect MathJax rerendering to Material for MkDocs’ document$ event.

let initialPage = true;
 
document$.subscribe(() => {
  if (initialPage) {
    initialPage = false;
    return;
  }
 
  MathJax.startup.output.clearCache();
  MathJax.typesetClear();
  MathJax.texReset();
  MathJax.typesetPromise();
});

The first event was skipped because MathJax already performs its normal automatic rendering on the initial page load. Running the same rendering logic again during the first event could duplicate the formula DOM.

Because the MathJax configuration file itself can be cached by the browser, the extra_javascript entry in mkdocs.yml used a version query string.

extra_javascript:
  - javascripts/mathjax.js?v=20260621-1
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

Verification

  • When the Riemann page was opened directly by URL, 70 .arithmatex blocks rendered into 70 mjx-container elements.
  • When the Riemann page was reached through an internal link from the Artifacts page, the same 70 mjx-container elements were rendered.
  • Both direct entry and internal navigation were checked on the deployed GitHub Pages site.

Durable Rule

Even in a static site, enabling instant navigation makes some behavior SPA-like.

Libraries that post-process the DOM, such as MathJax, Mermaid, or image lightboxes, may need to run not only on the initial page load but also after the page body is replaced.

Reference: Material for MkDocs MathJax configuration

Graph View