Coding N Concepts
Useful Hugo Shortcodes
Custom Hugo Shortcodes with examples
If you are using Hugo as a static site generator tool then you might have used hugo built-in shortcodes but here are some amazing hugo shortcodes which can be used in markdown files of your hugo website.
Shortcodes are simple snippets inside your content files calling built-in or custom templates.
Create Custom Shortcode
To create a shortcode, place an HTML template in the layouts/shortcodes directory of your source organization. Consider the file name carefully since the shortcode name will mirror that of the file but without the .html extension. For example, layouts/shortcodes/myshortcode.html will be called with {{< myshortcode >}}
Hugo Shortcode Examples
Current Year
This is useful when you want to show current year in markdown.
shortcode
layouts/shortcodes/year.html
{{ now.Format "2006" }}
usage
content/post/myblogpost.md
---
# front-matter
---
Top 10 things you should know in {{< year >}}
result
post/myblogpost.html
Top 10 things you should know in 2024
Link to open in browser window
By default when you create a link in hugo pages, it opens in same browser window. You can use this shortcode to open links in new browser window or tab.
shortcode
layouts/shortcodes/a_blank.html
<a href="{{ .Get "url" }}" target="_blank">{{ with .Get "title" }}{{.}}{{else}}{{.Get "url"}}{{end}}</a>
usage
content/post/myblogpost.md
---
# front-matter
---
[Coding N Concepts](https://codingnconcepts.com/) opens in same browser window
{{< a_blank title="Coding N Concepts" url="https://codingnconcepts.com/" >}} opens in new browser window.
result
post/myblogpost.html
Coding N Concepts opens in same browser window
Coding N Concepts opens in new browser window.
Add HTML elements in Code Block
Sometime we need support to add some specific styling in our markdown file. Hugo doesn’t support adding raw HTML in markdown files by default but you can enable that by making unsafe property as true in config.toml file:
[markup]
[markup.goldmark.renderer]
unsafe= true
You can now use raw HTML elements in your markdown files but there is still a limitation that you can not use raw HTML in code blocks. That is where span hugo shortcode is useful. It creates a </span> element with given style attributes.
shortcode
layouts/shortcodes/span.html
<span {{ with .Get "style"}} style="{{ . | safeCSS }}"{{ end }}>{{ .Get "text" }}</span>
usage
content/post/myblogpost.md
---
# front-matter
---
```
▼ The trace
first @ {{< span style="color:red;" text="test:1" >}}
second @ {{< span style="color:orange;font-style:italic;" text="test:2" >}}
third @ {{< span style="color:green;background-color:yellow;" text="test:3" >}}
fourth @ {{< span style="color:blue;border:1px solid blue;" text="test:4" >}}
(anonymous) @ {{< span style="color:black;font-weight:bold;" text="test:5" >}}
```
result
post/myblogpost.html
▼ The trace
first @ test:1
second @ test:2
third @ test:3
fourth @ test:4
(anonymous) @ test:5
Highlighter
This is useful when you want to highlight some of the content in markdown.
shortcode
layouts/shortcodes/highlight.html
<mark>{{ with .Get 0 }}{{.}}{{end}}</mark>
usage
content/post/myblogpost.md
---
# front-matter
---
This is the {{< highlight "most trending" >}} post of the decade.
result
post/myblogpost.html
This is the most trending post of the decade.
Strike
This is useful when you want to strike through some of the content in markdown.
shortcode
layouts/shortcodes/strike.html
<strike>{{ with .Get 0 }}{{.}}{{end}}</strike>
usage
content/post/myblogpost.md
---
# front-matter
---
This is {{< strike "not trending" >}} trending post of the decade.
result
post/myblogpost.html
This is the not trending trending post of the decade.
Code Block Output
This is useful when you want to show the output of certain code. It gives a beautiful title “Output”.
shortcode
layouts/shortcodes/code_output.html
<div class="code_output">Output</div>
usage
content/post/myblogpost.md
---
# front-matter
---
```
{{< code_output >}}
1
2
3
```
result
post/myblogpost.html
Output
1
2
3
Escape Hugo Shortcode
Sometime you might need to escape (i.e., prevent from executing) a shortcode in a Hugo markdown (.md) file, and display the shortcode as it is {{< myshortcode >}}
A simple method that works at the time of writing, is adding /* after the opening double curly braces and the angle bracket or percent sign (i.e., {{< or {{%/*) and adding */ after the closing angle bracket or percent sign and double curly braces (i.e., >}} or */%}}). For example, this in markdown (.md) file
{ {</* myshortcode */>}}
will be seen as this in generated HTML
{{< myshortcode >}}
