Static shortcodes

Introduction

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.

Disclaimers

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.

References

• gohugo.io/content-management/shortcodes
• gohugo.io/templates/shortcode-templates
• gohugo.io/methods/shortcode/inner
• gohugo.io/methods/shortcode/innerdeindent

Shortcodes

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:

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

Upcoming

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

Conclusion

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?

• About
• Latest Posts

Gareth Barnard

Developer at HRDNZ

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.

Latest posts by Gareth Barnard (see all)

• Moodle 4 Security – A Review – 16th April 2024
• A little bit #fab – 16th March 2024
• Static framework – 16th February 2024