How to Create a Custom Shortcode in HUGO

Hugo is one of the most popular open-source static site generators. Hugo greatly appreciates Markdown due to its straightforward content structure, yet there are times when Markdown's capabilities are limited. Often, content creators have to insert raw HTML into Markdown-based content, which goes against the beautiful simplicity of Markdown’s syntax.

To overcome these limitations, HUGO introduced Shortcodes. In Hugo, shortcodes are a method for inserting reusable HTML snippets into markdown pages. Hugo includes a set of predefined shortcodes designed to help us effortlessly incorporate elements like videos, images, tweets, and many more. Furthermore, we can create custom shortcodes as well.

Create a Custom Shortcode in Your Hugo Project

Create a Shortcode Directory

So, How can we create a custom shortcode? The answer is fairly easy. All we need to do is place an HTML template in the layouts/shortcodes or /themes/<THEME>/layouts/shortcodes/ directory of your source file. If there is not any shortcodes folder, we have to create one. The filename (without the.html extension) will become the name of your custom shortcodes.

Shortcode Parameters

In Hugo shortcodes, both positional and named parameters are applicable. In shortcodes with positional parameters, the order of the parameters is essential. A shortcode with a single required value can be more helpful. For, more complex shortcodes, named parameters work well. I prefer named parameters, as it is easy to remember the name and does not have order issues. Furthermore, we can use both types of parameters can be used at the same time in Hugo shortcodes.

Access Parameters

All parameters within a shortcode can be accessed using the “.Get” method. Whether you use a key (a string) or a number with the “.Get” method depends on whether you're accessing a named parameter or a positional one, respectively.

To retrieve a named parameter, employ the “.Get” method followed by the parameter's name enclosed in quotation marks:

{{ .Get "class" }}

To access a parameter based on its position, use the “.Get” method followed by a numerical index, considering that positional parameters start with zero:

{{ .Get 0 }}

When a closing shortcode is employed, the “.Inner” variable captures the content enclosed between the opening and closing shortcodes. To show the inner content of a closing shortcode use:

{{ .Inner  }}

Examples

First, let’s look into a single-line shortcode. Let’s add a link that will be opened on a new tab. Create an “a_blank.html” file inside the “layouts/shortcodes” folder of our Hugo project with the following codes:

<a href="{{ .Get "url" }}" target="_blank">{{ with .Get "title" }}{{.}}{{else}}{{.Get "url"}}{{end}}</a>

Now in the “sample.md” file in the content folder, add the shortcode:

---

title: "Open New Tab"

date: 2020-01-01T14:17:03-05:00

draft: false

---

{{< a_blank title="open new tab" url="https://codingnconcepts.com/" >}}

In the body of the post, add a shortcode by encapsulating it within double curly braces {{ }}, and placing the shortcode along with its parameters within angle brackets < >. In our example, this approach will lead to the HTML for embedding the link to be inserted into the page, which will open in a new tab.

Finally, let’s look into another example of a closing shortcode. Let’s assume we want to build a simple notice shortcode. This is our HTML file called notice.html. Now, add it to the layouts/shortcodes folder of our Hugo project:

<div class="alert {{.Get "class"}}" role="alert">

  <h4 class="alert-heading">{{.Get "title"}}</h4>

  {{.Inner}}

</div>

Look at the class=”{{ .Get “class” }}” in the first line and {{.Get "title"}} in the second line. This is how we pass parameters to our shortcode. Hugo will execute the “.Get” commands and place the parameter we pass in the attribute. “.Inner” will execute the values inside the closing shortcode.

Now in the “sample. md” file in the content folder, add the shortcode:

---

title: "Sample Notice"

date: 2020-01-01T14:17:03-05:00

draft: false

---

{{< notice class="alert-success" title="Sample Notice">}}

Aww yeah, you successfully read this important alert message. This example text is going to run a bit longer so that you can see how spacing within an alert works with this kind of content.

{{</notice>}}

That’s it we have successfully added a shortcode with an Inner value. A beautiful notice will be shown on the site.

Summary

In summary, Hugo shortcodes offer a convenient way to enhance your content creation process, improve maintainability, and create a consistent and modular website. They are particularly useful for avoiding code duplication and ensuring a clean separation of concerns between content and code. Thus, These represent the most basic approach to utilizing shortcodes.

However, please note that there exist more sophisticated functionalities. For a comprehensive understanding of the various ways in which you can leverage shortcodes, I recommend referring to the Hugo documentation provided below. It will offer detailed insights into their advanced capabilities.

Learn Hugo Documentation