hugo/content/templates/shortcode-templates.md

title	linktitle	description	date	publishdate	lastmod	categories	menu	weight	sections_weight	draft	aliases	toc
Create Your Own Shortcodes	Shortcode Templates	You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages.	2017-02-01	2017-02-01	2017-02-01	templates	docs parent weight templates 100	100	100	false		true

Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between page and list templates and basic content files.

{{% note %}} Hugo also ships with built-in shortcodes for common use cases. (See Content Management: Shortcodes.) {{% /note %}}

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 Placement

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 /*/%}} depending on the type of parameters you choose.

Shortcode Template Lookup Order

Shortcode templates have a simple lookup order:

1. /layouts/shortcodes/<SHORTCODE>.html
2. /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 }}

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:

{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }}

.Inner

If a closing shortcode is used, the .Inner variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of .Inner as an indicator of its existence.

A shortcode with content declared via the .Inner variable can also be declared without the inline content and without the closing shortcode 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 params; 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.

.IsNameParams

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.

{{% warning %}} While you can create shortcode templates that accept both positional and named parameters, you cannot declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like {{</* image src="images/my-image.jpg" "This is my alt text" */>}} will return an error. {{% /warning %}}

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.

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 */>}}

{{< code file="/layouts/shortcodes/year.html" >}} {{ .Page.Now.Year }} {{< /code >}}

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:

{{< code file="/layouts/shortcodes/youtube.html" >}}

{{< /code >}}

{{< code file="youtube-embed.html" copy="false" >}}

{{< /code >}}

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:

{{< code file="content-image.md" >}} {{</* img src="/media/spf13.jpg" title="Steve Francia" */>}} {{< /code >}}

You have created the shortcode at /layouts/shortcodes/img.html, which loads the following shortcode template:

{{< code file="/layouts/shortcodes/img.html" >}}

{{ with .Get "link"}}{{ end }} {{ if .Get "link"}}{{ end }} {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}

{{ if isset .Params "title" }}

{{ .Get "title" }}

{{ end }} {{ if or (.Get "caption") (.Get "attr")}}

{{ .Get "caption" }} {{ with .Get "attrlink"}} {{ end }} {{ .Get "attr" }} {{ if .Get "attrlink"}} {{ end }}

{{ end }}

{{ end }}

{{< /code >}}

Would be rendered as:

{{< code file="img-output.html" copy="false" >}}

Steve Francia

{{< /code >}}

Single Flexible Example: vimeo

{{</* vimeo 49718712 */>}}
{{</* vimeo id="49718712" class="flex-video" */>}}

Would load the template found at /layouts/shortcodes/vimeo.html:

{{< code file="/layouts/shortcodes/vimeo.html" >}} {{ if .IsNamedParams }}

{{ else }}

{{ end }} {{< /code >}}

Would be rendered as:

{{< code file="vimeo-iframes.html" copy="false" >}}

{{< /code >}}

Paired Example: highlight

The following is taken from highlight, which is a built-in shortcode that ships with Hugo.

{{< code file="highlight-example.md" >}} {{</* highlight html */>}}

<html> This HTML </html> {{}} {{< /code >}}

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:

{{< code file="syntax-highlighted.html" copy="false" >}}

<html>
    <body> This HTML </body>
</html>

{{< /code >}}

{{% note %}} The preceding shortcode makes use of a Hugo-specific template function called highlight, which uses Pygments to add syntax highlighting to the example HTML code block. See the developer tools page on syntax highlighting for more information. {{% /note %}}

Nested Shortcode: Image Gallery

Hugo's .Parent shortcode variable returns a boolean value depending on whether 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:

{{< code file="layouts/shortcodes/gallery.html" >}}

{{.Inner}}

{{< /code >}}

You also have an image 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 image:

{{< code file="layouts/shortcodes/image.html" >}} {{- $src := .Get "src" -}} {{- with .Parent -}} <img src="{{$src}}" class="{{.Get "class"}}-image"> {{- else -}} {{- end }} {{< /code >}}

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 image shortcodes inherit the class value of content-gallery set with the call to the parent gallery, whereas the third image 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">

More Shortcode Examples

More shortcode examples can be found in the shortcodes directory for spf13.com and the shortcodes directory for the Hugo docs.