Julien Maury


Render hooks in Hugo

Render hooks in Hugo

Julien Maury's photo
Julien Maury
·Nov 28, 2021·

1 min read

Subscribe to my newsletter and never miss my upcoming articles

In Hugo, content is generally written in markdown and then translated in HTML during the build.

Markdown provides a nice and clean syntax with various options, such as adding some HTML classes, but if you need to add HTML attributes or wrap with additional HTML markup, you have to modify the rendering.

Hugo provides a clever way to modify specific markup generated with markdown files. Unfortunately, it won't work with all configurations:

Note that this is only supported with the Goldmark renderer.

Source: Hugo - markdown render hooks

However, Goldmark is the default Markdown handler in Hugo.

You just have to create the layouts/_default/_markup folder and add specific files within to modify the rendering:

  • images: layouts/_default/_markup/render-image.html
  • links: layouts/_default/_markup/render-links.html
  • headings: layouts/_default/_markup/render-heading.html

It's a pretty clean way to alter the HTML markup, and you can use variables to receive the context. For example, to add an anchor link to all headings:

<!-- layouts/_default/_markup/render-heading.html -->
<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a class="anchor-link" href="#{{ .Anchor | safeURL }}"><span class="visually-hidden">Permalink to heading {{ .Text | safeHTML }}</span></a></h{{ .Level }}>

Then, you only have to style your anchors with the class .anchor-link {}, and add, for example, an icon or something.

No javaScript is needed.


Share this