How to Resize Images With Hugo
Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. I started the task of moving the site you’re looking at from WordPress to Hugo back in March, and the more I work with Hugo, the more I like it.
One of the very convenient things about WordPress was that it made using images in my posts very easy. I just dumped an image in the WordPress’ Gutenberg editor, and made sure it was resized to all necessary images size, and that everything was displayed correctly. In Hugo, there’s no such thing as the Gutenberg editor. There are some content management systems like Forestry.io and Netlify that you can put on top of Hugo, but one of the reasons I wanted to move to a static site generator was to avoid any sort of vendor lock-in.
No CMS or built-in editor means that Hugo users have to manage stuff like image resizing ourselves. But fear not. Like a lot of other things, Hugo makes this surprisingly easy.
Hooks and Processing
First off, let’s talk about Hugo’s Markdown render hooks. A render hook triggers whenever Goldmark - the Markdown parser used by Hugo - parses a particular piece of Markdown. As of Hugo v0.71.0, the hooks trigger on images, links, and headings. To resize images, we’ll create an image render hook.
The next thing we need to know about is Hugo’s image processing capabilities. As long as - and this is important - an image is available to Hugo as a page resource, i.e. part of a page bundle, Hugo can do all kinds of processing of the image. In this particular use-case, we’ll only resize the image, but it’s also possible to fit, fill, extract EXIF data, and apply various filters.
But enough talk, let’s get to work.
To create the image render hook, all you have to do is to create a file called render-image.html in layouts folder structure. The layout folder is probably hiding inside the theme you’re using.
layouts
└── _default
└── _markup
├── render-image.html
Then we add the following to the render-image.html file:
{{ $image := (.Page.Resources.GetMatch .Destination).Resize "640x" }}
<img src="{{ $image.RelPermalink | safeURL }}" />
And that’s all you need, really. Hugo will now automatically resize all the images in your markdown to a 640 pixels wide image.
Beyond the Basics
The example above is rather basic, and we should make a few changes to make it a bit more intelligent. There is, for instance, no need to resize images that are already less than 640 pixels wide. This can be done with a some additional code.
{{ $image := .Page.Resources.GetMatch .Destination }}
{{ if gt $image.Width 640 }}
{{ $image = $image.Resize "640x" }}
{{ end }}
<img src="{{ $image.RelPermalink | safeURL }}" />
The above change makes sure we only resize images that are wider than 640 pixels.
Next we want to make sure we render the alt and title attributes from the Markdown file as part of the generated HTML. This is done with a few simple changes to the last line.
{{ $image := .Page.Resources.GetMatch .Destination }}
{{ if gt $image.Width 640 }}
{{ $image = $image.Resize "640x" }}
{{ end }}
<img src="{{ $image.RelPermalink | safeURL }}" {{ with .Text }} alt="{{ . }}" {{ end }} {{ with .Title }} title="{{ . }}" {{ end }}/>
Now both the alt and title attributes will be added if they exist in the Markdown file. Marvelous!
The final thing we want to add is a nice visual representation of the title in the form of a figcaption element. This also involves wrapping the img element in a figure element, but it’s still a very easy thing to do.
{{ $image := .Page.Resources.GetMatch .Destination }}
{{ if gt $image.Width 640 }}
{{ $image = $image.Resize "640x" }}
{{ end }}
<figure>
<img src="{{ $image.RelPermalink | safeURL }}" {{ with .Text }} alt="{{ . }}" {{ end }} {{ with .Title }} title="{{ . }}" {{ end }}/>
{{ with .Title}} <figcaption>{{ . | markdownify }}</figcaption> {{ end }}
</figure>
And there you go! With only 8 lines of code, Hugo is now resizing all your Markdown images, and making sure everything is rendered as valid HTML.
Now go ahead and throw a couple of bucks at the lead Hugo developer for making this as easy as pie.
Feedback
Do you have any thoughts you want to share? A question, maybe? Or is something in this post just plainly wrong? Then please send an e-mail to vegard at vegard dot net with your input. You can also use any of the other points of contact listed on the About page.
Hello Vegard,
thank you very much for your discription, resizing images with/in Hugo. I will test and then report. Beside this, I am totally addicted to Hugo since July this year.
If you would like to have a look on my site : klaus.zieglers.de
For now it is all written in german, but perhaps, later on, it will be translated into english as a multilingual solution. But that’s far away.
best wishes
Klaus
Thank you for your feedback, good to hear that my articles are useful. Can I add your e-mail as feedback to the article?
I tried to visit your site, but I get an internal server error.
Sorry fort the wrong link
here ist the rightone : https://klaus-zieglers.de/
And of course you can add my email-adress, but until now I‘m not at the point of realisation yout “receipt”.
later in this theatre ;))
Have a nice weekend and stay healthy and save
