How do I make the Images on my Hugo site responsive

How do I make the Images on my Hugo site responsive

I’ve only been using Hugo for about a month, but the first thing I noticed was, that by default presenting images is a bit poo. I started off manually resizing my images to make them fit the text in my post, but then they weren’t really centered - which was annoying. Worse still if I viewed the site on my mobile the images were massive and I had to scroll sideways to view them.

Surely, I thought to myself, Hugo can’t be this lame considering how great it is generally? It isn’t, well out of the box it might be, but I started reading about these things called short codes. describes them as…

Shortcodes are simple snippets inside your content files calling built-in or custom templates.

The documentation goes into great detail about shortcodes and they look awesome, but I was struggling to get my head round the language used to create them. Also as much as I want to learn hugo, I needed to fix this issue fast.

Luckily I found this amazing article by Laura Kalbag. I’ve read a few on this subject, but this was the only one that helped me get this working. She has written a nice shortcode that will make your images responsive. The only slight issue, is that your posts need to be formatted as page bundles. Which was a bit of a wrench, as I spent ages cleaning up my posts after the move from WordPress and it would have been easier for me to implement this then. I hate having to make massive changes to any code as this normally causes more problems than its worth. However, in this instance, the extra effort is definity worth it.

Read Laura’s article, it explains the whole process and goes into detail about components such as Archetypes which i’m probably not far enough along my hugo journey to really appreciate. The only thing that I would love to have been added to the article (and the reason for writing this) was a simple example setup.

The first thing you need to do is create the file img.html in your layouts/shortcodes folder. I use the theme liva-hugo and my layouts/shortcode folder is in the theme folder.

{{/* get file that matches the filename as specified as src="" in shortcode */}}
{{ $src := .Page.Resources.GetMatch (printf "*%s*" (.Get "src")) }}

{{/* set image sizes, these are hardcoded for now, x dictates that images are resized to this width */}}

{{ $tinyw := default "500x" }}
{{ $smallw := default "800x" }}
{{ $mediumw := default "1200x" }}
{{ $largew := default "1500x" }}

{{/* resize the src image to the given sizes */}}

{{ .Scratch.Set "tiny" ($src.Resize $tinyw) }}
{{ .Scratch.Set "small" ($src.Resize $smallw) }}
{{ .Scratch.Set "medium" ($src.Resize $mediumw) }}
{{ .Scratch.Set "large" ($src.Resize $largew) }}

{{/* add the processed images to the scratch */}}

{{ $tiny := .Scratch.Get "tiny" }}
{{ $small := .Scratch.Get "small" }}
{{ $medium := .Scratch.Get "medium" }}
{{ $large := .Scratch.Get "large" }}

{{/* only use images smaller than or equal to the src (original) image size, as Hugo will upscale small images */}}
{{/* set the sizes attribute to (min-width: 35em) 1200px, 100vw unless overridden in shortcode */}}

  {{ with .Get "sizes" }}sizes='{{.}}'{{ else }}sizes="(min-width: 35em) 1200px, 100vw"{{ end }}
  {{ if ge $src.Width "500" }}
    {{ with $tiny.RelPermalink }}{{.}} 500w{{ end }}
  {{ end }}
  {{ if ge $src.Width "800" }}
    {{ with $small.RelPermalink }}, {{.}} 800w{{ end }}
  {{ end }}
  {{ if ge $src.Width "1200" }}
    {{ with $medium.RelPermalink }}, {{.}} 1200w{{ end }}
  {{ end }}
  {{ if ge $src.Width "1500" }}
    {{ with $large.RelPermalink }}, {{.}} 1500w {{ end }}
  {{ end }}'
  {{ if .Get (print $medium) }}
    src="{{ $medium.RelPermalink }}" 
  {{ else }}
    src="{{ $src.RelPermalink }}" 
  {{ end }}
  {{ with .Get "alt" }}alt="{{.}}"{{ else }}alt=""{{ end }}>

You then need to change the layout of your content/post folder to use Hugo page bundles. This involves creating a folder for each post (Called the post name) and renaming the post file to You also need to put all of the images used in the post, in the post folder.

Original content folder structure


    etc etc

New folder structure using page bundles


    <Image in Post 1>.jpg
    <Image in Post 2>.PNG

    <Image in Post 1>.jpg
    <Image in Post 2>.PNG
    <Image in Post 3>.PNG
    etc etc

In a hugo post you will see the link to the post in the header, this can stay as it is (See the first arrow below). Also I didn’t see any way to make the post image responsive, but im probably being dim. So I left that path as it is as well (The second arrow below).

title: Add responsive images to a  Hugo site

type: "featured"
date: 2020-06-02T19:54:31+00:00
--> url: /2020/06/06/add-responsive-images-to-a-hugo-site/
--> image: "/images/post/azureWordPressToHugo.PNG"

  - Hugo

  - Hugo

Next you need to put the below code in your post for images. I’ve had to spread this one line command over a few lines in this post to stop the shortcode from inserting the image. When you add it to your code, make sure its all on one line.

The important part is picking the right size. 500px, 800px, 1200px or 1500px are your options. Anything else will error

< img sizes="(min-width: 35em) 800px, 100vw" src="clippySocks.jpg" alt="Clippy Socks" >

Now I just need to make the example code blocks responsive. Oh and convert all my previous posts to page bundles…yeh!