Useful Hugo Shortcodes Useful Hugo Shortcodes

Custom Hugo Shortcodes with examples

Page content

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

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 >}}