Shortcodes

Introduction

A shortcode is a template invoked within markup, accepting any number of arguments. They can be used with any content format to insert elements such as videos, images, and social media embeds into your content.

There are three types of shortcodes: embedded, custom, and inline.

Embedded

Hugo’s embedded shortcodes are pre-defined templates within the application. Refer to each shortcode’s documentation for specific usage instructions and available arguments.

Details

Insert an HTML details element into your content using the details shortcode.

Figure

Insert an HTML figure element into your content using the figure shortcode.

Gist

Embed a GitHub Gist in your content using the gist shortcode.

Highlight

Insert syntax-highlighted code into your content using the highlight shortcode.

Instagram

Embed an Instagram post in your content using the instagram shortcode.

Param

Insert a parameter from front matter or site configuration into your content using the param shortcode.

QR

Insert a QR code into your content using the qr shortcode.

Ref

Insert a permalink to the given page reference using the ref shortcode.

Relref

Insert a relative permalink to the given page reference using the relref shortcode.

Vimeo

Embed a Vimeo video in your content using the vimeo shortcode.

X

Embed an X post in your content using the x shortcode.

YouTube

Embed a YouTube video in your content using the youtube shortcode.

Custom

Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a global resource:

{{ with resources.Get (.Get "src") }}
  <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
{{ end }}

Then call the shortcode from within markup:

{{< audio src=/audio/test.mp3 >}}

Learn more about creating shortcodes in the shortcode templates section.

Inline

An inline shortcode is a shortcode template defined within content.

Hugo’s security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.

To conform with this security model, creating shortcode templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your site’s configuration:

security:
  enableInlineShortcodes: true

[security]
  enableInlineShortcodes = true

{
   "security": {
      "enableInlineShortcodes": true
   }
}

For more information see configure security.

The following example demonstrates an inline shortcode, date.inline, that accepts a single positional argument: a date/time layout string.

Today is
{{< date.inline ":date_medium" >}}
  {{- now | time.Format (.Get 0) -}}
{{< /date.inline >}}.

Today is {{< date.inline ":date_full" />}}.

In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:

<p>Today is Jan 30, 2025.</p>
<p>Today is Thursday, January 30, 2025</p>

Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available shortcode method.

Learn more about creating shortcodes in the shortcode templates section.

Calling

Shortcode calls involve three syntactical elements: tags, arguments, and notation.

Tags

Some shortcodes expect content between opening and closing tags. For example, the embedded details shortcode requires an opening and closing tag:

{{< details summary="See the details" >}}
This is a **bold** word.
{{< /details >}}

Some shortcodes do not accept content. For example, the embedded instagram shortcode requires a single positional argument:

{{< instagram CxOWiQNP2MO >}}

Some shortcodes optionally accept content. For example, you can call the embedded qr shortcode with content:

{{< qr >}}
https://gohugo.io
{{< /qr >}}

Or use the self-closing syntax with a trailing slash to pass the text as an argument:

{{< qr text=https://gohugo.io />}}

Refer to each shortcode’s documentation for specific usage instructions and available arguments.

Arguments

Shortcode arguments can be either named or positional.

Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded figure shortcode. The src argument, for instance, is required.

{{< figure src=/images/kitten.jpg >}}

Positional arguments, on the other hand, are determined by their position. The embedded instagram shortcode, for example, expects the first argument to be the Instagram post ID.

{{< instagram CxOWiQNP2MO >}}

Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.

{{< figure src=/images/kitten.jpg alt="A white kitten" >}}

Shortcodes accept scalar arguments, one of string, integer, floating point, or boolean.

{{< my-shortcode name="John Smith" age=24 married=false >}}

You can optionally use multiple lines when providing several arguments to a shortcode for better readability:

{{< figure
  src=/images/kitten.jpg
  alt="A white kitten"
  caption="This is a white kitten"
  loading=lazy
>}}

Use a raw string literal if you need to pass a multiline string:

{{< myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted string".` >}}

Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.

Refer to each shortcode’s documentation for specific usage instructions and available arguments.

Notation

Shortcodes can be called using two different notations, distinguished by their tag delimiters.

Markdown notation

Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the TableOfContents method on the Page object.

Standard notation

With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the TableOfContents method on the Page object.

By way of example, with this shortcode template:

{{ .Inner }}

And this markdown:

{{% foo %}} ## Section 1 {{% /foo %}}

{{< foo >}} ## Section 2 {{< /foo >}}

Hugo renders this HTML:

<h2 id="heading">Section 1</h2>

## Section 2

In the above, “Section 1” will be included when invoking the TableOfContents method, while “Section 2” will not.

The shortcode author determines which notation to use. Consult each shortcode’s documentation for specific usage instructions and available arguments.

Nesting

Shortcodes (excluding inline shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:

{{< gallery class="content-gallery" >}}
  {{< image src="/images/a.jpg" >}}
  {{< image src="/images/b.jpg" >}}
  {{< image src="/images/c.jpg" >}}
{{< /gallery >}}

The shortcode templates section provides a detailed explanation and examples.