Create Custom Shortcodes To Embed Content In Hugo Posts And Pages

I’ve mentioned this numerous times before, but The Polyglot Developer is powered by Hugo which is a static site generator that takes Markdown and converts it to HTML. While Markdown is easy to use and can accomplish quite a bit, the syntax doesn’t accomplish everything that you’d hope to accomplish when it comes to a website. For example audio and video aren’t a thing in Markdown while it is in HTML. So how do you add custom components to a Hugo article?

In Hugo, you can create what is called a shortcode, which is a custom tag that gets processed differently than standard Markdown syntax. We’re going to see how to create shortcodes to take Hugo posts and pages to the next level.

Developing a Shortcode for the Hugo Static Site Generator

The concept of shortcodes in Hugo is simple. The idea is that you create a snippet of HTML and give that snippet a name. The snippet can be embedded in an article by calling the name in Markdown.

Take the following snippet for example:

<audio controls style="width: 100%; margin-bottom: 20px">
    {{ with .Get "ogg" }}<source src="{{ . }}" type="audio/ogg">{{ end }}
    {{ with .Get "mp3" }}<source src="{{ . }}" type="audio/mpeg">{{ end }}
    {{ with .Get "wav" }}<source src="{{ . }}" type="audio/wav">{{ end }}
    Your browser does not support the audio element.
</audio>

Let’s assume that the above snippet is called audio. This snippet has ogg, mp3, and wav placeholder variables that can be defined within the Markdown. Now let’s look at the following:

{{< audio mp3="filename.mp3" >}}

The above line is how you’d add the audio HTML into your Markdown. Notice we are using the mp3 variable which gets inserted where appropriate in the HTML. This line can be used as many times as you want in any Markdown file.

So how do you really use shortcodes in Hugo?

I’ve defined my shortcodes as part of my theme, but you don’t have to. In your project you can have either a layouts/shortcodes or a theme/layouts/shortcodes directory. Remember how I said the snippet was called audio? Each shortcode in your directory will have a name with an HTML extension.

Let’s take a look at another shortcode, this time slideshare.html:

{{ with .Get "id" }}
    <iframe
        src="//www.slideshare.net/slideshow/embed_code/key/{{ . }}"
        title="SlideShare Presentation"
        height="400"
        frameborder="0"
        marginwidth="0"
        marginheight="0"
        scrolling="no"
        style="border: 1px solid #CCC; border-width: 1px; margin-bottom: 20px; width: 100%;"
        allowfullscreen="true">
    </iframe>
{{ end }}

The same rules apply here. We have some HTML and an id placeholder variable. This variable is added within the HTML and defined when we call the shortcode in the Markdown. We would call it like this:

{{< slideshare id="1234" >}}

Not so bad right?

Let’s look at one more shortcode scenario. I had previously written a tutorial titled, Convert Amazon Links in a Hugo Site to Affiliate Links with Gulp. That tutorial demonstrated adding affiliate links via post-processing. A member of the community asked why I hadn’t made a shortcode to accomplish the job instead. There was no particular reason, but if I wanted to create a shortcode for the job, I could do something like this:

<a href="https://www.amazon.com/gp/product/{{ .Get "asin" }}?tag={{ .Get "affiliate" }}">
    {{ .Get "title" }}
</a>

An Amazon Associates affiliate link requires a product id and a member id, but it also makes sense to give the link a title as well. If I wanted to use this throughout my articles, I could add the following to my Markdown:

{{< amazon asin="B078Y4FR14" affiliate="nraboy-20" title="Dark Souls Remastered" >}}

Of course you could probably hardcode the affiliate variable if you really wanted to, but I’m sure you get the idea.

Conclusion

You just saw how to create and use shortcodes in Hugo. I gave three examples, but essentially shortcodes are just HTML snippets that are embedded on top of tag names within the Markdown files.

To learn more about shortcodes, visit the Hugo official documentation.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.