For the online learning world

Elearning WorldTechnical

Static shortcodes


In my previous posts about using Hugo we’ve been creating a statically generated website. In this post, we’ll look ‘Shortcodes’.

If you’ve not read my previous posts, then please do so that this one will make sense.


Names / logos can be trademarks of their respective owners. Please review their website for details.

I am independent from the organisations mentioned and am in no way writing for or endorsed by them.

The information presented in this article is written according to my own understanding, there could be technical inaccuracies, so please do undertake your own research.

The featured image is my copyright, please don’t use without my permission.



Shortcodes allow Hugo to add functionality to Markdown when it doesn’t support it with preventing the need to write pure HTML. If we look at the available shortcodes, https://gohugo.io/content-management/shortcodes/, then we find that there is not one to open a link in a separate tab / window, the ‘target’ attribute (www.w3schools.com/tags/att_a_target.asp) set to ‘_blank’. This is where we can now define our own, called ‘extref’.

Our custom shortcode

To jump straight to the solution, a file called ‘extref.html’ placed in our theme’s ‘layouts/shortcodes’ folder (github.com/gjb2048/hugo-elw/blob/Jan_2024/themes/elw/layouts/shortcodes/extref.html):

{{ if .IsNamedParams }}
    {{ if strings.ContainsNonSpace .Inner }}
        <a href="{{ .Get "href" }}" target="_blank" title="{{ .Get "title" }}">{{ trim .InnerDeindent "\r\n" }}</a>
    {{ else }}
        <a href="{{ .Get "href" }}" target="_blank">{{ .Get "title" }}</a>
    {{ end }}
{{ else }}
    {{ if strings.ContainsNonSpace .Inner }}
        <a href="{{ .Get 1 }}" target="_blank" title="{{ .Get 0 }}">{{ trim .InnerDeindent "\r\n" }}</a>
    {{ else }}
        <a href="{{ .Get 1 }}" target="_blank">{{ .Get 0 }}</a>
    {{ end }}
{{ end }}

Is telling Hugo how to render our shortcode markdown, in ‘content/_index.md’ (github.com/gjb2048/hugo-elw/blob/Jan_2024/content/_index.md?plain=1#L11-L17):

# Shortcode link example
- Positional parameters:
    - {{< extref "eLearningWorld" "https://www.elearningworld.org" />}}
    - {{< extref "eLearningWorld" "https://www.elearningworld.org" >}}This is eLearningWorld{{< /extref >}}
- Named parameters:
    - {{< extref title="eLearningWorld" href="https://www.elearningworld.org" />}}
    - {{< extref title="eLearningWorld" href="https://www.elearningworld.org" >}}This is eLearningWorld{{< /extref >}}

and generate the correct link (www.w3schools.com/tags/tag_a.asp). The first bit of logic, ‘if .IsNamedParams’ deduces if we are naming the attributes of our shortcode to be used in the link tag. This if we state ‘href’ and ‘title’ or rely on the order being the title then the URL itself. The other bit of logic is ‘if strings.ContainsNonSpace .Inner’ and this determines if the shortcode has content to be rendered between the opening and closing ‘a’ tags. Because of this then the shortcode needs a closing forward slash ‘/’ for some reason. In addition if the ‘%’ is used as the outer delimiter in the shortcode instead of ‘<’ and ‘>’, e.g.

{{% extref title="eLearningWorld" href="https://www.elearningworld.org" %}}This is eLearningWorld{{% /extref %}}

then for some reason the resulting markup is rendered as code. I don’t know why!

This all being said, the result you’ll now get is:

Shortcode link examples

Have a go yourself, examine the output in the browser and see what the links do.


In the next few posts about Hugo, I intend to look at integrating Bootstrap into our markup, render hooks and using different languages.


I hope that you’ve been able to understand how to create and use a custom shortcode.

You can get all of the code for this post from: github.com/gjb2048/hugo-elw/tree/Jan_2024.

What do you think please?

Gareth Barnard
Latest posts by Gareth Barnard (see all)

Gareth Barnard

Gareth is a developer of numerous Moodle Themes including Essential (the most popular Moodle Theme ever), Foundation, and other plugins such as course formats, including Collapsed Topics.

One thought on “Static shortcodes

  • Anonymous

    Nice post Gareth 🙂
    I can see how Hugo can be used to add functionality to Markdown – very interesting !


Add a reply or comment...