Disable Hugo Built-in JS to Improve Core Web Vitals Score

Tested on: Hugo 0.139.4, PaperMod v8, PageSpeed Insights March 2026 Problem: TBT 340ms, 180 KB unused JavaScript from theme features I never enabled.

Audit what's loading

View Source on production → search <script. PaperMod shipped:

theme.js — dark mode toggle + localStorage
search.js + Fuse.js — client-side search
highlight.min.js — code highlighting (duplicate of Hugo Chroma CSS)

I use system dark mode only and Algolia-free custom search (disabled). All three were dead weight.

Step 1: disable search in config

hugo.toml:

[params]
  disableSearch = true

Rebuild — search.js still present in some PaperMod versions. Config alone wasn't enough on v8.0.0.

Step 2: override footer scripts partial

Create layouts/partials/footer.html — copy from theme, then delete script blocks you don't need.

Minimal override — empty extend:

layouts/partials/extend_footer.html:

{{/* intentionally empty — blocks theme footer JS injection in some setups */}}

For PaperMod, override layouts/partials/footer.html and remove:

{{- /* DELETE THESE LINES */ -}}
<script src="{{ "js/theme.js" | relURL }}"></script>
<script src="{{ "js/search.js" | relURL }}"></script>

Keep only analytics if needed.

Step 3: CSS-only dark mode

I dropped JS dark toggle. Users get prefers-color-scheme via CSS:

assets/css/extended/dark-media.css:

:root {
  --theme: #fff;
  --entry: #f5f5f5;
  --primary: #1a1a1a;
}
@media (prefers-color-scheme: dark) {
  :root {
    --theme: #1a1a1a;
    --entry: #2a2a2a;
    --primary: #eee;
  }
}

PaperMod CSS variables match v8 naming — verify in DevTools if you use another theme.

Step 4: Chroma only, no highlight.js

hugo.toml:

[markup.highlight]
  noClasses = false
  style = "monokai"

Disable JS highlighter in theme params if exposed:

[params]
  disableHLJS = true

Error during override

execute of template failed: partial "footer.html" not found

I created layouts/partials/footer.html but forgot {{ partial "footer.html" . }} is called from baseof.html. File must exist at exact path.

Measure before/after

hugo --minify
du -sh public/js/

Before: public/js/ = 192 KB. After: directory empty (no JS shipped).

PageSpeed mobile field data (28-day):

Metric	Before	After
TBT	340 ms	42 ms
INP	210 ms	95 ms
Performance score	71	96

Verify no regressions

Code blocks still styled (Chroma CSS in <head>)
Mobile nav toggle still works (CSS checkbox hack in PaperMod — no JS)
No console errors
Dark mode follows OS setting

hugo server --disableFastRender
# Chrome DevTools → Performance → record reload
# Scripts section should show ~0ms main-thread JS

Trade-off I'll accept

No manual dark-mode button. 96% of my readers never clicked it (Plausible custom event, 30-day sample). Core Web Vitals pass rate went from 62% to 91% URLs in GSC.