Hugo Shortcodes are a specialized markdown syntax that can be used to extend basic markdown. Shortcodes are templates that can be called from your Hugo markdown files to add HTML snippets to the final rendered HTML. Shortcodes can be parameterized, which gives you additional flexibility and powerful reusability. They also keep your markdown *pure* and free of raw HTML.
Before we get to Shortcodes, I'll explain how you can add raw HTML to your Hugo markdown files. If the shortcode you want doesn't exist, and you don't want to create a custom one, this is your only option.
By default Hugo removes raw HTML from markdown documents. Without shortcodes, you can add HTML directly to your markdown documents, but you will have to add the following setting to your config file. I use the toml format, so, to disable HTML removal from markdown I add this to my config.toml file.
[markup]
[markup.goldmark.renderer]
unsafe=true
I find the name choice of the setting interesting. "unsafe" - I guess if you are adding HTML to your doc you run the risk of messing up your page.
With this setting I can add an Unsplash credit link to my page, for example, like this:
<span>Photo by <a href="https://unsplash.com/@danesduet?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Daniel Olah</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span>
If unsafe is set to *false* Hugo will replace embedded HTML with an HTML comment indicating that if has removed the tags.
<!-- raw HTML omitted -->
Photo by
<!-- raw HTML omitted-->
Daniel Olah
<!-- raw HTML omitted -->
on
<!-- raw HTML omitted -->
Unsplash
<!-- raw HTML omitted -->
<!-- raw HTML omitted -->
Every tag is replaced with an HTML comment indicating it has been removed.
Shortcodes are a cleaner way to add custom rendered HTML to markdown without *polluting* the markdown with embedded HTML. Shortcodes ONLY work in markdown files, you can't use them in your HTML template files.
Here is an example of the youtube short code.
{{< youtube 2xkNJL4gJ9E >))This shortcode renders a youtube embed, like this:
<div style="position: relative; padding-bottom:56.25%; height: 0; overflow: hidden;">
<iframe src="https://www.youtube.com/embed/2xkNJL4gJ9E style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" allowfullscreen title="YouTube Video"></iframe>
</div>
You can create your own shortcodes. I have one for links that I want to open in a new tab (I.e. target="_blank").
To create a customer shortcode add an html file to your layouts/shortcodes folder.
I have a file called a_link.html in my site's layouts/shortcodes folder with the following code.
<a href="{{ .Get "url" }}" target="{{ .Get "target" }}">{{ .Get "title" }}</a>
In this example, my shortcode name is the same as the html file name, so *a_link*. The Shortcode takes 3 parameters.
To use the shortcode, I add it to my markdown files like this.
{{< a_link url="www.google.com" title="Google" target="_blank" >}}
This shortcode renders the following
<a href="www.google.com" target="_blank">Google</a>
Shortcodes allow you to keep markdown in your markdown files and keep HTML out. They are also a powerful way to achieve parameter driven, reusable HTML snippets.
Some of my other articles on Hugo include:
Photo by Alex Knight on Unsplash