Diagnosing Missing srcset and sizes in Hugo Pipes to Eliminate Cumulative Layout Shift

Recognizable Condition

Pages built with Hugo render <img> tags that lack srcset and sizes attributes. Browsers cannot reserve space for the image, so content jumps when the image loads — a measurable Cumulative Layout Shift (CLS) above the 0.1 threshold.

Cause / Diagnostic Table

Ordered Checks

1. Inspect the image pipeline in the template. Open the layout file (e.g., layouts/_default/single.html) and locate the image handling block. It should resemble:

   {{ $src := resources.Get .File.Path }}
   {{ $img := $src | resources.Resize "800x" | resources.Fill "800x450" }}
   <img src="{{ $img.RelPermalink }}"
        srcset="{{ $img.SrcSet }}"
        sizes="(max-width: 800px) 100vw, 800px"
        alt="{{ .Title }}">
   

   If the pipe chain stops at resources.Get, the resize step is missing.
2. Confirm ResolveResources is enabled. In config.toml (or config.yaml) ensure:

   [build]
     writeStats = true
   [imaging]
     resampleFilter = "Lanczos"
   

   Absence of these settings can prevent resource resolution.
3. Verify Hugo Extended binary. Run in the project root:

   hugo version
   

   Expected output includes extended (e.g., hugo v0.124.0+extended linux/amd64). Without it, WEBP, AVIF, and SVG codecs are unavailable.
4. Generate srcset and sizes attributes. After a successful resize, call .SrcSet on the processed resource and add a sizes attribute that matches your CSS breakpoints. Example for a two‑column layout:

   sizes="(min-width: 1200px) 50vw, 100vw"
   

5. Clear the build cache and rebuild. Stale resources can hide fixes. Execute:

   hugo --cleanDestinationDir
   

   Run from the site root; this removes public/ and forces a fresh pipeline pass.

Fixes Tied to Findings

• Missing resize pipe → Insert | resources.Resize "800x" (or Fit/Fill) before rendering the <img> tag.
• ResolveResources disabled → Add the [build] and [imaging] sections shown above; restart hugo server.
• Standard Hugo binary → Install Hugo Extended (e.g., brew install hugo on macOS or download the extended tarball from GitHub releases). Replace the binary in your PATH.
• Incorrect sizes value → Align sizes with actual CSS media queries; test with Chrome DevTools device toolbar.

Escalation Criteria

If CLS remains above 0.1 after completing the checks:

1. Audit every custom image shortcode (e.g., {{< figure >}}) for missing pipeline calls.
2. Confirm that all image formats required (WEBP, AVIF) are listed under [mediaTypes] in config.
3. Run hugo --gc --cleanDestinationDir to garbage‑collect unused resources.
4. Profile with Lighthouse (Chrome DevTools → Lighthouse → Performance) and note the “Avoid large layout shifts” audit. Persistent shifts may indicate CSS‑only layout issues (e.g., missing aspect‑ratio boxes) rather than Hugo pipeline problems.

Verification Steps

1. Start the development server: hugo server -D (run in project root, no elevated permissions).
2. Open the rendered page, view source, and search for srcset= and sizes= on content images.
3. Run Lighthouse or web.dev/measure on the live URL; confirm CLS < 0.1 and that the “Properly size images” audit passes.

Limitations

Hugo Pipes image processing for modern formats (WEBP, AVIF, SVG) requires the Hugo Extended binary; the standard build cannot transcode these formats. The diagnostic steps assume a single‑language site; multilingual setups may need per‑language resource resolution.