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?
- Debugging SCSS – 16th November 2024
- Settings transfer – 16th October 2024
- Added value – 16th September 2024
Nice post Gareth 🙂
I can see how Hugo can be used to add functionality to Markdown – very interesting !