Automatic Responsive Images in Hugo: How the Built‑In Pipeline Works

Problem: Manual Image Resizing Slows Down Content

When preparing a blog post, authors often create several copies of the same picture at different widths (e.g., 400px, 800px, 1200px) and then write the srcset attribute by hand. This extra step adds time, introduces naming mistakes, and makes it easy to forget a size when the design changes.

How Hugo’s Built‑In Image Processing Works

Hugo’s extended edition bundles libvips, a fast image‑processing library. During site generation, any image placed in the assets/ folder can be accessed via resources.Get. Chaining transformation methods such as .Resize, .Fit, or .Crop creates new image resources on the fly. Each resource exposes fields like .RelPermalink (the public URL) and .Width/.Height, which you can use to build a srcset attribute automatically.

Configuration and Basic Usage

1. Make sure you have the Hugo extended binary installed. Run hugo version and look for the word "extended" in the output.
2. Store your source images inside the assets/ directory of your project (e.g., assets/photos/my-picture.jpg).
3. In a layout, shortcode, or markdown render hook, retrieve the image and apply the desired transformations:

{{ $src := resources.Get "assets/photos/my-picture.jpg" }}
{{ $img := $src.Resize "800x" }}  

To generate a responsive srcset, you can create several widths and join them:

{{ $src := resources.Get "assets/photos/my-picture.jpg" }}
{{ $widths := slice "400" "800" "1200" }}
{{ $variants := slice }}
{{ range $widths }}
  {{ $variants = $variants | append ($src.Resize (printf "%sx" .)) }}
{{ end }}

Worked Example: Figure Shortcode

Many themes ship a figure shortcode that already does the above. A simplified version looks like this:

{{/* figure shortcode */}}
{{ $src := resources.Get .Get "src" }}
{{ $widths := slice "400" "800" "1200" }}
{{ $variants := slice }}
{{ range $widths }}
  {{ $variants = $variants | append ($src.Resize (printf "%sx" .)) }}
{{ end }}

  
  {{ if .Get "caption" }}{{ .Get "caption" }}{{ end }}

When you call {{ /* figure src="assets/photo.jpg" alt="A scenic view" */ }} during hugo build, Hugo will produce files such as:

• public/photos/photo.400x.jpg
• public/photos/photo.800x.jpg
• public/photos/photo.1200x.jpg

The resulting HTML will contain a srcset attribute that lists those three files with their widths, allowing the browser to pick the most appropriate size.

Trade‑offs and Limitations

• Extended binary required: The pipeline depends on libvips, which is only compiled into the Hugo extended edition. On minimal containers or systems without CGO support, you must fall back to manual resizing.
• Build time: Generating many variants increases the site build duration. For a site with hundreds of large source images, consider limiting the number of widths or using .Quality 80 to reduce file size.
• Default quality: Hugo’s default JPEG quality is 82; if you need smaller files, add .Quality 75 (or another value) to the transformation chain.

Practical Verification Steps

1. Confirm the extended version: hugo version should output something like hugo v0.140.0 extended.
2. Run a full build: hugo --minify.
3. Inspect the public/ folder for the generated image files (look for the width suffix in the filename).
4. Open the generated HTML page in a browser, right‑click the image, and choose “Inspect”. Verify that the img tag contains a srcset attribute with the expected widths and that the sizes attribute matches your layout.

Actionable Closing

Switch to the Hugo extended edition, place your source images in assets/, and use the resources.Get pattern (or a figure shortcode) in your templates. After building, check the public/ directory for the auto‑generated variants and the srcset in the rendered HTML. You’ll get responsive images without maintaining multiple files or writing extra markup.