felipeweber.com – felipeweber.com

Shipping a Hugo site on Cloudflare Pages without the headache

weberecomp@gmail.com (Felipe Weber) — Wed, 02 Sep 2026 00:00:00 +0000

Putting a static site online stopped being a project. What still eats time is the first half hour — the one between “works on my machine” and “works in production, with HTTPS and automatic deploys”.

Here is the path I use today.

The minimum contract

Cloudflare Pages needs three things: a Git repository, a build command and an output directory. For Hugo:

# Build command
hugo --gc --minify

# Build output directory
public

The rest is environment configuration. And that is where almost every first deploy fails.

Trap 1: the Hugo version

The Pages runner does not use the version you have locally. Without pinning, you get an old one — usually without the extended build, which breaks any theme that touches SCSS.

Set the environment variable in the project settings:

HUGO_VERSION = 0.165.0

Pin the version in the repository too, in a file people can actually read. An invisible environment variable is technical debt waiting to happen.

Trap 2: Hugo Modules need Go

If the theme ships as a Hugo Module — and most do now — the runner needs Go available before hugo runs:

GO_VERSION = 1.27.1

Without it the build dies with a module not found that says nothing about the actual cause.

Trap 3: `baseURL` and previews

Every branch gets its own preview URL. If baseURL is hardcoded in the config, the preview’s absolute links point at production. The fix is to let Pages inject the value:

hugo --gc --minify --baseURL "$CF_PAGES_URL"

In production CF_PAGES_URL is the final domain, so one command covers both cases with no branching.

What you get for free

After that, every git push to main is a deploy. Branches become previews. The certificate is issued and renewed on its own. And the cost stays at zero up to traffic most personal blogs will never see.

The official docs live at developers.cloudflare.com/pages, and the build configuration section is worth reading before the first deploy.

Hugo Modules in practice: versioned themes without submodules

weberecomp@gmail.com (Felipe Weber) — Tue, 18 Aug 2026 00:00:00 +0000

Every Hugo tutorial starts with git submodule add. It works, but it turns the theme into a frozen copy inside your repository, with no declared version and no upgrade path.

Hugo Modules fix that by treating the theme as what it is: a dependency.

The setup

hugo mod init github.com/your-user/your-site
hugo mod get github.com/imfing/hextra

The generated go.mod records the exact version:

module github.com/your-user/your-site
go 1.27.1
require github.com/imfing/hextra v0.12.3

In the config, the import replaces the old theme: key:

module:
 imports:
 - path: github.com/imfing/hextra

Why this is better

Upgrading is one command, and so is rolling back:

hugo mod get -u github.com/imfing/hextra # latest
hugo mod get github.com/imfing/hextra@v0.12.3 # back to a specific one

No theme file ever enters your repository. The diff of an upgrade is one line in go.mod.

File-by-file overrides

The part that sold me: project files beat module files, one at a time. If you want to change only the footer, you create only the footer:

layouts/_partials/footer.html

The rest of the theme keeps coming from the module and keeps receiving fixes on upgrade. Compared to vendoring the whole theme, the maintenance difference is large.

Rule of thumb: if you have copied more than three theme files, check whether the problem is actually configuration.

The cost

You need Go installed — locally and in CI. That is the entry fee, and it is worth paying, because from then on the theme stops being an opaque blob in your commit history.

Hextra’s source lives at github.com/imfing/hextra and is a good reference for how a modular theme is organized.

A static search index that fits in 40 KB

weberecomp@gmail.com (Felipe Weber) — Tue, 04 Aug 2026 00:00:00 +0000

Search on a static site has three paths: a paid external service, your own server, or a JSON index built at compile time and queried in the browser. For a blog the third one is almost always right — as long as the index stays thin.

What makes an index fat

The common mistake is indexing the full body of every post. Fifty 1,500-word articles turn into a multi-megabyte JSON file the visitor downloads before typing a single letter.

What actually matters for blog search:

Field	Good for	Cost
title	finding the post	tiny
description	context in results	low
headings	finding the section	low
full body	matching an exact phrase	enormous

In practice title + description + headings answer nearly every real query and keep the index in the tens of kilobytes.

Generating it at build time

In Hugo the index is just another output template. The relevant part:

{{- $index := slice -}}
{{- range where site.RegularPages "Section" "blog" -}}
 {{- $index = $index | append (dict
 "title" .Title
 "url" .RelPermalink
 "desc" .Description
 "headings" (apply .Fragments.Headings "index" "." "Title")
 ) -}}
{{- end -}}
{{ $index | jsonify }}

No extra pipeline step: the file is born alongside the HTML.

Load it late

The index does not need to exist at first paint. Fetch it when the field is first focused:

let indexPromise;

input.addEventListener("focus", () => {
 indexPromise ??= fetch("/search-index.json").then((r) => r.json());
}, { once: true });

Visitors who never search never pay for it. Those who do pay once, and the browser caches it.

The best optimization is still not downloading the file.

Where this breaks

If your use case is matching an exact phrase inside a long document — a manual, a knowledge base — the reduced index will not do. There it is worth evaluating Pagefind, which shards the index and only downloads the pieces it needs.

For a blog, that is optimizing a problem you do not have.

Dark mode with no flash: what happens before first paint

weberecomp@gmail.com (Felipe Weber) — Tue, 21 Jul 2026 00:00:00 +0000

You implement dark mode, you test it, it works. Then you reload and see a white flash before the dark theme appears. The classic FOUC.

The cause is not in the CSS. It is in when the JavaScript runs.

The race

The browser builds the page in order: parse HTML, fetch CSS, compute style, paint. If the script that decides the theme runs after that paint, the user sees the default theme first.

parse HTML → fetch CSS → first paint → DOMContentLoaded → your script
▲ │
flash happens here theme applied here

Any script with defer, async, or bound to DOMContentLoaded loses the race by construction.

The fix

A synchronous inline script in <head>, before any stylesheet that depends on the theme:

<script>
 (function () {
 var stored = localStorage.getItem("color-theme");
 var theme = stored === "light" || stored === "dark"
 ? stored
 : (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
 document.documentElement.classList.add(theme);
 document.documentElement.style.colorScheme = theme;
 })();
</script>

It blocks the parser for well under a millisecond, and the class is already on <html> when the first pixel appears.

The two details almost everyone forgets

color-scheme. Without it the browser still paints scrollbars, form controls and the default canvas in light. It is one line, and it is the difference between “dark” and actually dark.

localStorage can throw. In some browsers’ private mode, accessing it raises. Wrap it in try/catch — the site has to load even when the preference cannot be read.

Three states, not two: light, dark and system. System is the correct default, and the only one that respects someone who changed their OS preference after visiting your site.

Verifying it

The honest test is with CPU throttling on, 6x slowdown, cache disabled. The flash you cannot see on your desktop shows up immediately on a mid-range phone.

Writing CSS that survives the next redesign

weberecomp@gmail.com (Felipe Weber) — Tue, 30 Jun 2026 00:00:00 +0000

Every frontend project reaches the point where nobody wants to touch the CSS. Not because it is badly written — because nobody knows what will break.

The symptom is always the same: the same decision is written in fifteen places.

Tokens before components

Before styling anything, define the vocabulary:

:root {
 --surface: #faf7f0;
 --text: #23201c;
 --text-muted: rgb(35 32 28 / 62%);
 --accent: #9a5b18;
 --radius: 8px;
 --measure: 68ch;
}

Swapping the whole theme becomes swapping that block. Without tokens, it is a find-and-replace with risk attached.

One theme, one inversion

Dark mode is not a second stylesheet. It is the same sheet with the tokens redefined:

html.dark {
 --surface: #1a1714;
 --text: #ece7de;
 --accent: #e2a05a;
}

If you had to write html.dark .component { ... }, the component is reading a color that should have been a token.

`color-mix` kills the twelve-shade palette

Half the variables in a design system are opacity variants of the same color. color-mix derives them on the spot:

.card {
 border: 1px solid color-mix(in srgb, var(--text) 12%, transparent);
}

.card:hover {
 border-color: color-mix(in srgb, var(--accent) 48%, transparent);
}

The border follows the theme on its own, in both modes, with no new variable.

Measure is a decision, not an accident

.prose { max-width: 68ch; line-height: 1.7; }

Two lines that do more for readability than any font choice. ch tracks the text size — if the font grows, the measure grows with it.

If you cannot explain why a value is 1.7 and not 1.5, it will become 1.6 in the next PR and nobody will be able to say whether that helped.

The test

Take the stylesheet and try to change the site’s accent color. If it is one line, it survives the next redesign. If it takes five files, you already know where refactoring starts.

Measuring Core Web Vitals for real on a static site

weberecomp@gmail.com (Felipe Weber) — Thu, 14 May 2026 00:00:00 +0000

Static sites have an unfair advantage in performance: no server thinking, no hydration, no API waterfall. Scoring 100 in Lighthouse is easy.

Which is exactly why the number misleads.

Lab is not field

Lighthouse runs a simulation: one machine, one network, one cold load. The Core Web Vitals Google actually uses come from CrUX — real users, real devices, real networks, at the 75th percentile.

The two disagree often, and the field wins.

Measurement	Where it lives	What it answers
Lighthouse	your terminal / CI	“did I regress since last commit?”
CrUX	aggregated real data	“are my visitors suffering?”
Your own RUM	your site	“which pages, which devices?”

The three metrics, one sentence each

LCP — when the largest visible element finished painting. On a blog it is almost always the title or the first image. A badly configured web font delays it more than any image will.

INP — how long the page takes to respond to an interaction. Static sites rarely fail here, unless a third-party script is holding the main thread.

CLS — how much content jumps during load. Cause number one: images without width/height. Cause number two: a font swap that changes text height.

Measuring on your own site

The official library fits in a few lines and reports real numbers:

import { onLCP, onINP, onCLS } from "web-vitals";

function send(metric) {
 navigator.sendBeacon("/vitals", JSON.stringify({
 name: metric.name,
 value: metric.value,
 rating: metric.rating,
 path: location.pathname,
 }));
}

onLCP(send);
onINP(send);
onCLS(send);

sendBeacon does not hold navigation — the payload goes out even after the user has left the page.

What to fix first on a static site

Fonts. font-display: swap, preload only the files used above the fold, and serve them from your own domain.
Image dimensions. Always width and height, even with responsive CSS on top.
Third-party scripts. Each one is an INP risk you do not control.

Optimize from the inside out: first what you serve, then what you borrow.

The reference that keeps up with metric definition changes is web.dev/vitals.