Hugo image processing and responsive images

Hi everyone,
I’m using Hugo for building my websites. I’m trying image processing of hugo, currently, we are using 1000+ images and it will grow with time. I’m using the shortcode for rendering images from markdown. I wanted to try the image processing of hugo, I wanted to make it responsive to reduce layouts shifts and improve CLS. Is there any way to build responsive images either with hugo processing or some other alternatives?
I’m using mounts to change the directory of images from static to assets.

  source = 'assets'
  target = 'assets'

  source = 'static'
  target = 'assets' 

Here is the shortcode I’m using for my image.

{{ if .Get "caption" }}
{{ $.Scratch.Set "caption" (.Get "caption") }}
{{ end }}

<!-- resolve absolute image path -->
{{ $permalink := $.Page.Permalink }}
{{ $image := .Get "src" }}

{{- $url := (relURL $image) -}}

{{/*  {{- if not (fileExists (print "static" $url) ) -}}
  {{- errorf "%s references an image does not exist — %q" $.Page.Path $url -}}
{{- end -}}  */}}

<figure class="image--main {{ with .Get "class" }} {{.}} {{ end }}" {{ with .Get "width" }}style="width: {{ . }};" {{
    end }} {{ with .Get "height" }}style="height: {{ . }};" {{ end }}>
    <a {{ if .Get "lightbox" }} data-lightbox="{{ .Get "lightbox" | markdownify | plainify }}" {{ else }}
        data-lightbox="image-{{ $image }}" {{ end }} href="{{ $url }}"
        {{ with .Get "target" }} target="{{ . }}" {{ end }}
        {{ with .Get "rel" }} rel="{{ . }}" {{ end }}>
        <img src="{{ $url }}" 
        {{ if .Get "alt" }} alt="{{ .Get "alt" | markdownify | plainify }}" {{ end }} 
        {{ with .Get "align" }}align="{{ . }}" {{ end }} 
        {{ with .Get "title" }}title="{{ . }}" {{ end }} 
        decoding="async" loading="lazy" class="lazyload img-shortcode"/>
    {{ if ($.Scratch.Get "caption") }}
        <span class="img--caption">
            Figure {{ $.Page.Scratch.Get "fig" }}. {{ $.Scratch.Get "caption" | markdownify | plainify }}
            {{ if .Get "attr" }}
            [{{- with .Get "attrlink"}}<a href="{{ . | relURL }}">{{ end }}{{ .Get "attr" | markdownify }}{{ if .Get
                "attrlink"}}</a>{{ end -}}]
            {{ end }}
    {{ end }}
{{ .Page.Scratch.Add "fig" 1 }}
{{ $.Scratch.Delete "caption"}}


You can set default image processing with standard markdown images using a render hook
Markdown Render Hooks | Hugo (
If one image type is standard, that might be useful.

If you have many images per post you might find images in page bundles suit better than all in one folder.
Page Bundles | Hugo (

On to the shortcode
First, not sure why you need to use Scratch, you should just be able to set variables simply: {{- $alt := .Get "alt" -}}

For the responsiveness you can use .Resize and .RelPermalink to create and link to different sizes of the image.
Image Processing | Hugo (

How you want to use them, img with srcset, media queries, srcset & sizes is up to you to code.
Personally I try to choose sizes that get reused, so the retina x3 image size for the common 1920x1080 android phones is also used as the x1 image on desktop.

You will find your initial build time increases significantly with 1000 images but they will be cached. If you change sizes or quality you’ll hit a rebuild and it’ll have to create a new cache. You might want to test on a smaller set of images.

Can you give me your image shortcode, I wanted to take some references from that.

Mine is specific to my own needs (e.g. images in page bundles) I think it is best to roll your own to some extent.

Some examples, Bryce’s stuff on Hugo is always worth reading:

And this is a simple render hook:

1 Like

If you are after a somewhat non-opinionated module to automate responsive images I have developed this one.

1 Like