In this article, you’ll learn how Hugo shortcodes package reusable presentation without embedding repeated HTML in Markdown. That matters because durable engineering comes from understanding trade-offs, not merely reproducing a command or pattern.

My first attempt

Here’s my first effort at creating a shortcode.

This shortcode is available here

Information

Basic

{{< note Sample text >}}

With italics

{{< note italic=“true” Sample text >}}

With header

{{< note title=“With header”> Sample text >}}

Warning

Basic

{{< note warning=“true”> Sample text >}}

With italic

{{< note warning=“true” italic=“true” Sample text >}}

With header

{{< note warning=“true” title=“With header” Sample text >}}

Error

Basic

{{< note error=“true” Sample text >}}

With italic

{{< note error=“true” italic=“true” Sample text >}}

With header

{{< note error=“true” title=“With header” Sample text >}}

Deepening the article

Treat a shortcode as an interface

A shortcode has callers, parameters, defaults, and rendered output; changing any of them can break old content. Prefer named parameters once a shortcode has more than one meaningful input, validate required values, and fail the build with a useful message rather than silently emitting malformed HTML.

{{ $text := .Get "text" }}
{{ if not $text }}
  {{ errorf "notice shortcode requires text: %s" .Position }}
{{ end }}
<aside class="notice notice--{{ .Get "type" | default "info" }}">
  {{ $text | markdownify }}
</aside>

Hugo templates escape values according to context. Do not mark arbitrary author input as safeHTML simply to make rendering work; that bypasses an important boundary. Decide explicitly whether a parameter accepts plain text, Markdown, or trusted HTML.

Keep presentation in the theme or asset pipeline and semantics in the shortcode. An aside with meaningful text survives a CSS failure and works better for assistive technology than a collection of decorative div elements.

References

• Hugo documentation
• Hugo shortcode documentation

Closing thought

A shortcode becomes worthwhile when it centralises semantics and safety, not merely when it saves an author from typing the same HTML twice.