Optimizing My Hugo Blog: From 3.6 MB of JavaScript to Zero

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

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.