Demystifying Hugo Shortcodes: Your Ultimate Guide

Demystifying Hugo Shortcodes: Your Ultimate Guide. A list of useful hugo shortcodes.

Last Update: September 19, 2023

What is Hugo

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

If you’re a web developer or a blogger using Hugo, you’ve probably heard of shortcodes. Shortcodes are one of the many powerful features that make Hugo, a static site generator, so versatile and user-friendly. In this article, we’ll dive into the world of Hugo shortcodes, exploring what they are, how to create them, and how to use them effectively with real-world examples.

What Are Hugo Shortcodes?

Hugo shortcodes are small, reusable snippets of code that allow you to insert dynamic content or complex functionality into your Hugo content files. They provide a way to keep your content DRY (Don’t Repeat Yourself) and make it easier to manage and maintain your Hugo site.

Shortcodes are typically enclosed in double curly braces, like

{{< myshortcode param1="value1" param2="value2" >}}

and they can be used for a wide range of purposes, from embedding videos and images to creating custom components and widgets.

Creating Your Own Hugo Shortcodes

Creating your own Hugo shortcode is a straightforward process. Here’s a step-by-step guide:

Choose a Name: Pick a name for your shortcode that is unique and easy to remember. It’s a good practice to use lowercase letters and hyphens for readability. For example, if you’re creating a shortcode to embed a YouTube video, you might name it youtube.
Create a New HTML File: In your Hugo project’s layouts/shortcodes directory, create a new HTML file with the same name as your shortcode. For example, if your shortcode is named youtube, create a file called youtube.html.
Define the Shortcode Template: Inside the youtube.html file, define the HTML and Go template code that makes up your shortcode. Here’s a simple example for embedding a YouTube video:

<iframe src="https://www.youtube.com/embed/{{ .Get "video_id" }}" frameborder="0" allowfullscreen></iframe>

In this example, we use the .Get method to retrieve the value of the video_id parameter passed to the shortcode.

Add Parameters (Optional): You can make your shortcode more versatile by allowing users to pass parameters. To do this, define the parameters in the shortcode’s front matter:

---
title: "My Hugo Shortcode"
parameters:
  - name: "video_id"
    type: "string"
---

Use Your Shortcode: Now that you’ve created your shortcode, you can use it in your Hugo content files. For example:

Here’s an embedded YouTube video:

{{< youtube video_id="your_video_id_here" >}}

Using Hugo Shortcodes: Examples

Let’s explore some practical examples of Hugo shortcodes to give you a better understanding of their versatility.

Embedding a YouTube Video

We’ve already seen how to create a youtube shortcode. Here’s how you can use it:

{{< youtube video_id="your_video_id_here" >}}

Highlighting Code Blocks

You can create a code shortcode to highlight code blocks with syntax highlighting:

{{< code language="python" >}}
func main() {
    fmt.Println("Hello, Hugo Shortcodes!")
}
{{< /code >}}

Adding Custom Alerts

Create an alert shortcode to add custom alerts to your content:

{{< alert type="info" >}}
This is an informational message.
{{< /alert >}}

Displaying Images with Captions

Use a figure shortcode for displaying images with captions:

{{< figure src="/images/my-image.jpg" alt="A beautiful image" caption="This is a beautiful image." &#x25;}}

Displaying all the pages with same tag

Create a shortcode relatedpages in layouts/shortcodes/relatedpages.html, as following content:

{{ with $tag := .Get 0 }}
  {{ with where site.RegularPages "Params.tags" "intersect" (slice $tag) }}
    {{ with where . "Permalink" "ne" $.Page.Permalink }}
      <h2>Related pages:</h2>
      <ul>
        {{ range . }}
          <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
        {{ end }}
      </ul>
    {{ end }}
  {{ end }}
{{ else }}
  {{ errorf "The %q shortcode requires a tag name as parameter. See %s" .Name .Position }}
{{ end }}

Usage:

{{</* relatedpages "Hugo" >}}

Conclusion

Hugo shortcodes are a powerful tool in your static site generation arsenal. They allow you to extend the functionality of your Hugo site without diving into complex code. By creating your own custom shortcodes and using existing ones creatively, you can enhance the presentation and interactivity of your Hugo-powered website or blog. So, go ahead, experiment with shortcodes, and make your Hugo site stand out!

References

Hugo: Configure Markup

OmniLock - Block / Hide App on iOS

Block distractive apps from appearing on the Home Screen and App Library, enhance your focus and reduce screen time.

DNS Firewall for iOS and Mac OS

Encrypted your DNS to protect your privacy and firewall to block phishing, malicious domains, block ads in all browsers and apps

← Previous