Skip to content

Load Mermaid and Highlight.js only when needed #865

Description

@LukasWallrich

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.

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions