My Hugo blog was downloading 3.6 MB of JavaScript and 40 KB of external CSS on every page load. For a static blog with mostly text and a few diagrams, that was absurd. Here is how I fixed it.
Baseline
- HTML: 86 KB
- JavaScript: 3.6 MB (Mermaid + KaTeX)
- CSS: 40 KB (KaTeX stylesheets)
- Problem: render-blocking scripts loaded on every page for math and diagrams
Optimization 1: HTML minification
Adding minifyOutput = true to hugo.toml shrunk HTML by 16%. Small win, zero risk.
Optimization 2: Inline CSS
I removed the external main.css link and inlined the styles directly into the HTML. The HTML grew slightly, but I eliminated one render-blocking network request. First Contentful Paint improved because the browser no longer waits for a CSS fetch.
Optimization 3: Native MathML
My blog used KaTeX to render equations. That meant JavaScript, CSS, and font files for every page with math. I switched to Hugo's Goldmark passthrough extensions, which output native MathML. Browsers render this directly.
Result: 278 KB of JavaScript removed, all external stylesheets eliminated. Math now renders without any scripts or fonts.
Optimization 4: Conditional asset loading
Mermaid.js was loading on every page, even text-only posts. I used Hugo's .Store to set a hasMermaid flag during Markdown processing. The script tag only injects when a page actually contains a diagram.
Text-only pages no longer download Mermaid. Diagram pages still get it, but only when needed.
Optimization 5: Server-side rendering for Mermaid
Even conditional loading left a 3.3 MB script on diagram pages. I added a Node.js build step that pre-renders Mermaid blocks into static SVG files at build time. The frontend outputs <img src="diagram.svg"> instead of a <script> tag.
Result: zero JavaScript on the frontend. Total Blocking Time dropped because the browser no longer executes JS to calculate layouts.
Optimization 6: Early Hints and caching
I generated a _headers file with strict Cache-Control rules for immutable assets. The build script also injects Link: rel=preload headers for images and SVGs. Cloudflare returns 103 Early Hints, telling the browser to fetch assets before the HTML document finishes downloading.
Summary
| Metric | Before | After |
|---|---|---|
| JavaScript | 3.6 MB | 0 bytes |
| External CSS | 40 KB | 0 bytes |
| HTML | 86 KB | 72 KB (minified) |
The site is now 100% JavaScript-free on the frontend. Performance matters, and static sites do not need a heavy JS framework to be fast.
For the full hugo.toml config, build scripts, and Lighthouse score breakdown: Optimizing My Hugo Blog.
Top comments (0)