Why this needs addressing
The site currently enables both Mermaid and syntax highlighting globally:
config/_default/params.toml sets diagram = true and highlight = true.
- The theme then emits Mermaid and Highlight.js assets for every page.
- The live homepage currently includes both
mermaid.min.js and highlight.min.js.
The repository contains no Mermaid blocks and only a small number of code blocks, so these libraries are not a reasonable site-wide default. Mermaid alone is a large render-blocking payload.
Requested change
- Make Mermaid opt-in at page level (or detect actual Mermaid content during the Hugo build) instead of enabling it globally.
- Make Highlight.js opt-in for pages that contain highlighted code, while preserving the existing language support where needed.
- Add
defer or an equivalent non-blocking loading strategy to remaining non-critical scripts where that is safe.
- Do not remove functionality from pages that genuinely use diagrams or code highlighting.
Acceptance criteria
- Normal pages, including the homepage, do not request Mermaid or Highlight.js.
- Pages containing Mermaid/code still render correctly.
- Generated HTML and a representative mobile performance trace confirm the conditional behaviour.
Why this needs addressing
The site currently enables both Mermaid and syntax highlighting globally:
config/_default/params.tomlsetsdiagram = trueandhighlight = true.mermaid.min.jsandhighlight.min.js.The repository contains no Mermaid blocks and only a small number of code blocks, so these libraries are not a reasonable site-wide default. Mermaid alone is a large render-blocking payload.
Requested change
deferor an equivalent non-blocking loading strategy to remaining non-critical scripts where that is safe.Acceptance criteria