Create your own shortcodes
Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside your content.
Create custom shortcodes
Hugo’s built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website’s needs.
File location
To create a shortcode, place an HTML template in the layouts/shortcodes
directory of your source organization. Consider the file name carefully since the shortcode name will mirror that of the file but without the .html
extension. For example, layouts/shortcodes/myshortcode.html
will be called with either {{< myshortcode />}}
or {{% myshortcode /%}}
.
You can organize your shortcodes in subfolders, e.g. in layouts/shortcodes/boxes
. These shortcodes would then be accessible with their relative path, e.g:
{{< boxes/square >}}
Note the forward slash.
Shortcode template lookup order
Shortcode templates have a simple lookup order:
/layouts/shortcodes/<SHORTCODE>.html
/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html
Positional vs. named parameters
You can create shortcodes using the following types of parameters:
- Positional parameters
- Named parameters
- Positional or named parameters (i.e, “flexible”)
In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the youtube
shortcode below), positional parameters work very well and require less typing from content authors.
For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order.
Allowing both types of parameters (i.e., a “flexible” shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users.
Access parameters
All shortcode parameters can be accessed via the .Get
method. Whether you pass a key (i.e., string) or a number to the .Get
method depends on whether you are accessing a named or positional parameter, respectively.
To access a parameter by name, use the .Get
method followed by the named parameter as a quoted string:
{{ .Get "class" }}
To access a parameter by position, use the .Get
followed by a numeric position, keeping in mind that positional parameters are zero-indexed:
{{ .Get 0 }}
For the second position, you would just use:
{{ .Get 1 }}
with
is great when the output depends on a parameter being set:
{{ with .Get "class" }} class="{{ . }}"{{ end }}
.Get
can also be used to check if a parameter has been provided. This is
most helpful when the condition depends on either of the values, or both:
{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "title" }}{{ end }}"{{ end }}
.Inner
If a closing shortcode is used, the .Inner
variable will be populated with the content between the opening and closing shortcodes. To check if .Inner
contains anything other than white space:
{{ if strings.ContainsNonSpace .Inner }}
Inner is not empty
{{ end }}
A shortcode with content declared via the .Inner
variable can also be declared without the content and without the closing tag by using the self-closing syntax:
{{< innershortcode />}}
.Params
The .Params
variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic:
$.Params
- these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID)
$.Page.Params
- refers to the page’s parameters; the “page” in this case refers to the content file in which the shortcode is declared (e.g., a
shortcode_color
field in a content’s front matter could be accessed via$.Page.Params.shortcode_color
). $.Page.Site.Params
- refers to global variables as defined in your site’s configuration file.
.IsNamedParams
The .IsNamedParams
variable checks whether the shortcode declaration uses named parameters and returns a boolean value.
For example, you could create an image
shortcode that can take either a src
named parameter or the first positional parameter, depending on the preference of the content’s author. Let’s assume the image
shortcode is called as follows:
{{< image src="images/my-image.jpg" >}}
You could then include the following as part of your shortcode templating:
{{ if .IsNamedParams }}
<img src="{{ .Get "src" }}" alt="">
{{ else }}
<img src="{{ .Get 0 }}" alt="">
{{ end }}
See the example Vimeo shortcode below for .IsNamedParams
in action.
You can also use the variable .Page
to access all the normal page variables.
A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with .Parent
variable. This can be very useful for inheritance of common shortcode parameters from the root.
Checking for existence
You can check if a specific shortcode is used on a page by calling .HasShortcode
in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode.
Custom shortcode examples
The following are examples of the different types of shortcodes you can create via shortcode template files in /layouts/shortcodes
.
Single-word example: year
Let’s assume you would like to keep mentions of your copyright year current in your content files without having to continually review your Markdown. Your goal is to be able to call the shortcode as follows:
{{< year >}}
{{ now.Format "2006" }}
Single positional example: youtube
Embedded videos are a common addition to Markdown content that can quickly become unsightly. The following is the code used by Hugo’s built-in YouTube shortcode:
{{< youtube 09jf3ow9jfw >}}
Would load the template at /layouts/shortcodes/youtube.html
:
<div class="embed video-player">
<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
</iframe>
</div>
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
width="640" height="385"
src="https://www.youtube.com/embed/09jf3ow9jfw"
allowfullscreen frameborder="0">
</iframe>
</div>
Single named example: image
Let’s say you want to create your own img
shortcode rather than use Hugo’s built-in figure
shortcode. Your goal is to be able to call the shortcode as follows in your content files:
{{< img src="/media/spf13.jpg" title="Steve Francia" >}}
You have created the shortcode at /layouts/shortcodes/img.html
, which loads the following shortcode template:
<!-- image -->
<figure {{ with .Get "class" }}class="{{ . }}"{{ end }}>
{{ with .Get "link" }}<a href="{{ . }}">{{ end }}
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "caption" }}{{ end }}"{{ end }} />
{{ if .Get "link" }}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }}
<figcaption>{{ if isset .Params "title" }}
<h4>{{ .Get "title" }}</h4>{{ end }}
{{ if or (.Get "caption") (.Get "attr") }}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink" }}<a href="{{ . }}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink" }}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
Would be rendered as:
<figure>
<img src="/media/spf13.jpg" />
<figcaption>
<h4>Steve Francia</h4>
</figcaption>
</figure>
Single flexible example: vimeo
{{< vimeo 49718712 >}}
{{< vimeo id="49718712" class="flex-video" >}}
Would load the template found at /layouts/shortcodes/vimeo.html
:
{{ if .IsNamedParams }}
<div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
<iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
</div>
{{ else }}
<div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
<iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
</div>
{{ end }}
Would be rendered as:
<div class="vimeo-container">
<iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
<div class="flex-video">
<iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
Paired example: highlight
The following is taken from highlight
, which is a built-in shortcode that ships with Hugo.
{{< highlight html >}}
<html>
<body> This HTML </body>
</html>
{{< /highlight >}}
The template for the highlight
shortcode uses the following code, which is already included in Hugo:
{{ .Get 0 | highlight .Inner }}
The rendered output of the HTML example code block will be as follows:
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672"><html></span>
<span style="color: #f92672"><body></span> This HTML <span style="color: #f92672"></body></span>
<span style="color: #f92672"></html></span>
</pre></div>
Nested shortcode: image gallery
Hugo’s .Parent
shortcode variable provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model for common shortcode parameters.
The following example is contrived but demonstrates the concept. Assume you have a gallery
shortcode that expects one named class
parameter:
<div class="{{ .Get "class" }}">
{{ .Inner }}
</div>
You also have an img
shortcode with a single named src
parameter that you want to call inside of gallery
and other shortcodes, so that the parent defines the context of each img
:
{{- $src := .Get "src" -}}
{{- with .Parent -}}
<img src="{{ $src }}" class="{{ .Get "class" }}-image">
{{- else -}}
<img src="{{ $src }}">
{{- end -}}
You can then call your shortcode in your content as follows:
{{< gallery class="content-gallery" >}}
{{< img src="/images/one.jpg" >}}
{{< img src="/images/two.jpg" >}}
{{< /gallery >}}
{{< img src="/images/three.jpg" >}}
This will output the following HTML. Note how the first two img
shortcodes inherit the class
value of content-gallery
set with the call to the parent gallery
, whereas the third img
only uses src
:
<div class="content-gallery">
<img src="/images/one.jpg" class="content-gallery-image">
<img src="/images/two.jpg" class="content-gallery-image">
</div>
<img src="/images/three.jpg">
Error handling in shortcodes
Use the errorf template func and .Position variable to get useful error messages in shortcodes:
{{ with .Get "name" }}
{{ else }}
{{ errorf "missing value for parameter 'name': %s" .Position }}
{{ end }}
When the above fails, you will see an ERROR
log similar to the below:
ERROR 2018/11/07 10:05:55 missing value for parameter name: "/Users/bep/dev/go/gohugoio/hugo/docs/content/en/variables/shortcodes.md:32:1"
More shortcode examples
More shortcode examples can be found in the shortcodes directory for spf13.com and the shortcodes directory for the Hugo docs.
Inline shortcodes
You can also implement your shortcodes inline – e.g. where you use them in the content file. This can be useful for scripting that you only need in one place.
This feature is disabled by default, but can be enabled in your site configuration:
enableInlineShortcodes: true
enableInlineShortcodes = true
{
"enableInlineShortcodes": true
}
It is disabled by default for security reasons. The security model used by Hugo’s template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then enableInlineShortcodes = true
would be considered safe. But it’s something to be aware of: It allows ad-hoc Go Text templates to be executed from the content files.
And once enabled, you can do this in your content files:
{{< time.inline >}}{{ now }}{{< /time.inline >}}
The above will print the current date and time.
Note that an inline shortcode’s inner content is parsed and executed as a Go text template with the same context as a regular shortcode template.
This means that the current page can be accessed via .Page.Title
etc. This also means that there are no concept of “nested inline shortcodes”.
The same inline shortcode can be reused later in the same content file, with different parameters if needed, using the self-closing syntax:
{{< time.inline />}}