Updated: , Published:
When you write link or image in markdown then it renders to fixed html format. And there is no way of customizing it without custom shortcodes in hugo.
For example the following markdown code
will generate the following html code
Sometimes you want default behavior for all links e.g. All links must open in separate browser tab. Similarly you may want default behavior for every image e.g. Every image is a link pointing to the actual image file. If some part of image is not clear then you can open full size image and zoom into it.
Now you can do the same with Markdown Render Hooks. And the cherry on top is that it renders 15% faster and requires less memory.
- You need min Hugo 0.62 or above installed on your computer.
- You need to use Goldmark as your markdown renderer.
In very short you are going to define how all markdown links and images should be rendered to html using single template file for each. So you have direct control over how markdown is rendered. Create two new files as following.
Then inside the
render-link.html write following code. One thing I personally like to use it for is to open non https links in new tab.
So let’s talk about properties available in the template
.Destinationis the link url and required
.Titleis the optional title field.
.PlainTextis the link text and required.
If you want to open link in new tab then you need to set
rel="noopener" is for your security. So the link website cannot access referring website (your website) through browser. This is commonly done when you don’t trust the link website or if you are opening link in different browser tab.
In case of images personally I don’t keep images in static folder. I make use of Page Bundles to store all page specific images. Link and image template both have access to
.Page variable. Write the following code inside
So just based on image name you can find image from all page images. And with that image you can get width and height for each image.
There are 2 considerations required for link accessability
- Link text should stand out from regular text
- Show icon if you are opening link on new browser tab
After many year’s of internet, people have come to terms that any text that has underline is a link. So please don’t remove default link underline with CSS. If you really have to remove underline then make sure underline appears on
Now just having underline is not enough. You need 3:1 contrast from link text color and surrounding non-link text color. Now you maybe inclined to use opposite color for link to make link stand out. So you are solely relying on color to convey meaning. But this will not work for color blind people. So changing color is good but please don’t rely on color to convey meaning.
Instead you can make text bold or italics in markdown itself. But
.PlainText would remove all the formatting. And if you want markdown to be rendered to html before adding to template then make following changes in
.Text the markdown written inside link text is rendered before adding to the link template. So the following markdown
will generate following link
Don’t forget to convert to
safeHTML otherwise it will show
<strong> tag in final text.
Also for accessibility its important that you open link in the same browser tab. It’s not recommended to open link in separate tab. But if you really have to open link in different browser tab then you can show an icon image with
alt text for screen readers like following example.
I am setting fixed width and height because I don’t want to change icon size on any screen size.
Have you found any mistake or improvement for this post then let me know in the comments below.