When to Use Hugo Shortcodes or Render Hooks

Hugo shortcodes and render hooks both produce custom HTML, but I choose between them by looking at the source content. If the author is writing a normal link, image, heading, or code block, use a render hook. If the content introduces a gallery or another custom object, use a shortcode.

A shortcode is explicit custom content

A shortcode starts inside the Markdown:

{{< gallery images="one.jpg,two.jpg" >}}

Its template can interpret those parameters and render a component. Hugo documents the built-in and custom forms in the shortcode guide.

This is appropriate when “gallery” has meaning that Markdown does not natively express. The downside is portability: another Markdown renderer sees Hugo-specific syntax.

A render hook changes existing Markdown

Authors keep writing an ordinary link:

[MDN](https://developer.mozilla.org/)

A link render hook decides the HTML Hugo emits:

<a href="{{ .Destination | safeURL }}">
  {{ .Text | safeHTML }}
</a>

The same mechanism can process images, add heading anchors, or change code-block rendering. The Hugo render hooks documentation lists the supported kinds and lookup rules.

I prefer hooks when the content is still honestly Markdown. Responsive image processing, for example, can happen behind normal image syntax rather than making authors remember a special image shortcode.

Keep special syntax special

A gallery with layout options is a good shortcode. A normal link with a class is not. Turning every paragraph, callout, image, and heading into shortcode notation makes content difficult to read and move.

Shortcode notation also affects whether inner content is processed as Markdown, so choose the delimiter deliberately. Hugo’s RenderShortcodes reference covers rendering shortcode markup held in page content.

My rule is: render hooks customise the site’s interpretation of existing Markdown; shortcodes add a content type Markdown cannot describe. A site can use both, but keeping that boundary clear prevents Markdown from turning into a template language wearing a trench coat.

← Back to all articles