Drop-in replacement for Hugo figure shortcode with responsive img srcset

When I moved this blog over to Hugo slightly more than a year ago, I started using Laura Kalbag’s special img shortcode with img srcset support.

To make a long and interesting story short, srcset enables us to tell the browser that we have for example 5 different resolutions of an image available, and that it should choose the best one based on the user’s device.

Pretty neat actually!

Anyways, I tweaked the code a bit over time, and most recently I combined it with the stock Hugo figure shortcode.

What this means, is that you can now use just the straight Hugo figure shortcode as per the documentation, and my modified shortcode will do all of image processing and srcset specification fully automatically.

In other words, you only have to refer to your fullest resolution image in the figure shortcode, and hugo will take care of creating a number of downscaled versions, and offer them to modern browsers in a way that gives the user the best experience.

Install and use

To install, simply download the figure.html gist (embedded below) into the layouts/shortcodes directory in your hugo blog and then rebuild your blog.

NOTE: It’s very important that images have to be in the page bundle if you want automatic resizing and srcset. The shortcode will fall back to stock Hugo behaviour otherwise.

Example result

I’ve posted the image below so you can see the shortcode in action.

It started as {{< figure src="20200324_stillbaai_beach.jpg" link="20200324_stillbaai_beach.jpg" caption="..." >}} and ended up as the image below.

If you right click, and then inspect, you’ll see the srcset specification. Even better if you switch to the network panel in devtools, then reload, and note that your browser downloads a lower resolution image if you’ve narrowed your viewport, or switched devtools to mobile emulation.

Updates

• On 2020-05-10 I updated the shortcode to fall back to stock Hugo behaviour instead of just breaking when the image was not part of the page bundle. However, if you want resizing and srcset (the whole point of this post), your images should be in the page bundle. :)