Customize `img` rendering using Markdown Render Hooks

I’m moving a conversation from the timeline over here for posterity and easier code sharing.

Is it possible to automatically use’s image scaling feature for all my images? Right now, there’s a lot of manual labor prepending each image URL.

@g (paraphrased and translated from Swedish by me).

So Gunnar wants all his image URLs prefixed with automatically. And that’s possible! But you have to use Markdown syntax when adding images in your posts. Markdown syntax looks like this:

![A cute kitten.](

By default, will take that Markdown and render HTML looking like this:

<img src="" alt="A cute kitten.">

But thanks to Hugo and something called Markdown Render Hooks we can override that behavior and render whatever we want. In this case, Gunnar wants HTML like this:

<img src="" alt="A cute kitten." />

Let’s implement that!

How to use Markdown Render Hooks in to customize the rendering of img elements

  1. Make sure you have a Custom theme set for your blog.
  2. Navigate to DesignEdit Custom Themes and click on your custom theme.
  3. Click New Template.
  4. Enter the following path and filename layouts/_default/_markup/render-image.html. Naming is important, make sure it’s correct.
  5. As content, paste the code snippet below and then click Update Template.
  6. You’re done! Give your site time to rebuild. From now on, all images embedded with Markdown syntax should have the prefix.

Content of layouts/_default/_markup/render-image.html:

<img src="{{ (print "" (.Destination | urlquery)) | safeURL }}" alt="{{ .Text }}" />

This is a bare-bones example. There are a lot of bells and whistles you could potentially add, like support for width and height attributes, lazy loading, and so on.


Thank you @sod! My first one: -
And 173 KB is a lot better than 2.6 MB. And you get the full image if you click it.
Money is in the bucket at Stripe Checkout

1 Like

Nice twist adding a link to the full-resolution image. And thanks for the donation, much appreciated. :pray:

1 Like

For another example of this, I implemented render hooks a while back in the glightbox plugin. I originally defaulted to using thumbnails, but ultimately didn’t like the quality that came out of’s resizing.

This is great! By the way, wherever you use a URL like “…” you can replace it with “…” and it will automatically cache the image in the content-delivery network, for faster serving around the world.


The twist was unintentionally, but was really nice. Next step is to show EXIF Data in Hugo

That’s a cool idea! Unfortunately, that won’t work as @manton strips away all EXIF data when uploading photos to

Yes I just read about it here Width and height of photos on Photos page? - #6 by kottkrig

So what does that 600x business actually do to how the phot appears?

It scales the image at the provided URL to be 600 px wide. The original photo @g posted above is 1800 px wide, so adding the prefix will reduce the file size quite a lot. You can change 600x to any value that suits your needs. Or not use this at all, if you have no use for scaled down images. :blush:

That makes sense. Thanks.

My 2 cents, it’s usually a good idea to have the size be at least 2x what you expect most people to view it as, so it looks nicer on modern phone screens that are high resolution. The timeline currently defaults to scaling down to 1000 pixels wide. The client apps usually resize to 1800 pixels before uploading, then add a width tag of 600 making it roughly 3x the display size, but it’s not an exact science with so many different screen sizes.

Tried this on my MIcroblog but it doesn’t seem to work. The URLs seem different to me. They’re as follows:

Has something changed since this post was discussed back in December? Would changing the markup to something like this work:

<img loading="lazy" src="{{ (print "" (.Destination | urlquery)) | safeURL }}" alt="{{ .Text }}" />

Markdown render hooks were introduced in Hugo 0.62. You’re probably on Hugo 0.54. Navigate to Design and change Hugo version to 0.91. After your site has been rebuilt, your custom render hook should work. You should not have to change anything in the render hook.

The URL you’re seeing in the rendered HTML of your page is caused by the setting Use content delivery network for images (also on the Design page). The original URL for that photo is

Thanks @sod, I was already on 0.91 and I’m still not sure if it’s working correctly or not. The resulting image is smaller than the source, but it still isn’t 600px, and my addition of loading="lazy" to the render doesn’t seem to be present either.

It’s possible that the change to using the CDN by default means that this no longer works. I believe you can turn off the CDN by going to the Design page and un-clicking “Use content delivery network for images”.

@manton does the CDN make the resizing endpoint fail?

Disabling the CDN didn’t work either. :frowning:

CDN probably doesn’t have anything to do with this.

Your custom rendering hook is not running, as you’re not seeing the loading attribute. The question is why it’s not running. :blush: It’s always a challenge to troubleshoot from the outside, but here are some things to try.

  1. Do a full rebuild of the site. Sometime, making changes to a custom theme doesn’t trigger a rebuild, and you could, in theory, be looking at old versions of your pages.
  2. When doing the rebuild, keep an eye on the logs for any errors or hints of anything going wrong.
  3. Make sure the right custom theme is selected on the Design page.
  4. Double-check that the name of the template is layouts/_default/_markup/render-image.html.
  5. If you’ve made any changes to my original template at the top of this thread, revert them.
  6. If you have more than one blog (or a test blog) – make sure you’re doing all this on the right one.

We will figure this out, sooner or later.

Update: I just followed my own instructions in the top post with success. So at lest we know, “it works on my machine” (or Manton’s servers, rather). If there’s any comfort in that. :sweat_smile:

Well this is good news - at least we know it works and it’s just me being an idiot somewhere along the line! (sorry about that)

OK, so I’ve confirmed the following:

  • The file path is layouts/_default/_markup/render-image.html
  • The contents of that file are below (I removed my customisation to add loading="lazy"
  • My custom theme is selected
  • I’m using v0.91 of Hugo
<img src="{{ (print "" (.Destination | urlquery)) | safeURL }}" alt="{{ .Text }}" />

Unfortunately, I don’t know how to trigger a full rebuild I’m afraid. I had a look through the UI, but I can’t find an option for that. I published a test post with an image to see if it worked, wouldn’t that trigger a rebuild?


Sorry, I meant to link that text but forgot before publishing. Rebuild button and logs can be found here.