Since writing the how-to article on
using nextgen formats for images in Hugo, I’ve been investigating Hugo’s markdown render hooks and found that they are much simpler to implement. There is less of a faff passing lots of parameters into a shortcode. In this tutorial, I will show you how to get the same result using much less code. In addition, this article will show you a simple way to achieve
What are Markdown Render Hooks
Render hooks enable you to change the rendering of markdown elements such as images or links. In Hugo, we can create render hooks for
You write templates that allow you to change the rendering from the standard format to one that matches your custom requirements.
To create a render hook template, you create a HTML file where the filename corresponds to the singular version of the names stated above hence:
- images become
- links become
- codeblocks becomes
- headings become
These HTML files will hold the code that transforms your content into the rendered HTML.
From Shortcodes to Render Hooks
In this tutorial, I will focus on images and links. You may remember in the previous tutorial, I used the figure shortcode to render images in my markdown, which looked like this.
Using the above, we can add things like classes or alt text, but you may also remember there was a slew of potential parameters passed into the shortcode to render the height and width, extra style, links and more.
Instead of using the above template, we will use a simpler one that takes the regular format for an image in markdown, which looks like this:
or if the image has a link, one that looks like this.
and renders it using the same image resource processing that we built in the previous article.
Render Hook Templates
Render hook templates live in the
layouts/_default/_markup folder either in your theme or the top-level
layouts folder. You can also create type or section-specific render hook templates, as you would for any list or single templates, if you need images or links rendered differently for alternate content types/sections.
Since I have the same format for images in all the sections of my site, I will add my template to the
Both the image and link render hooks get the following context passed to them.
- Page - the page that is being rendered
- Destination - the URL of the image/link
- Title - any title attribute
- Text - the rendered HTML link text
- PlainText - the plain text equivalent of the Text
Image Render Hook Template
Do you remember the Figure shortcode from the previous article
This code can all be replaced by
We are still doing the same thing, getting the same result but with much less code. Also, I don’t have to remember to add a ‘figure’ shortcode statement in the file; I can use regular markdown.
So what’s the code here doing:
- Ln 2-4: We assign two parameters to local variables to work with them in the
_images/picturepartial. I want all images to have a caption for the most part, so I’ve opted to add the alt text to the title element if no title has passed.
- Ln 4: We use a
withstatement so that Hugo will not error if it can’t find the image.
- Ln 5: Because I want my images to have a
figcaption, I wrap it in a
- Ln 6: In the previous tutorial, we spoke about the
_images/picturepartial. It’s the one that does all the image processing
- Ln 7: We use another
withstatement so that the
figcaptionis only rendered if we have
And that’s it!
Link Render Hook Template
I wanted links to external websites to open using
render-link.html file and add the following.
Ln 4 is where the magic happens. Add a check to see if the link begins with
http, and that will add the
_target=blank attribute to your link. Otherwise, it will open the link in the same browser window. Simples!
Using Hugo’s render hook templates, we can write less code and render images how we want them to appear. Using these hooks, we can achieve a standardised way of generating pictures and links consistently on our site.