Advanced Hugo Shortcodes: Build Custom Components

Hugo is already among the fastest, most flexible static site generators. But the true power emerges when you start writing custom shortcodes. Shortcodes allow you to incorporate complex HTML, UI components, scripts, and reusable content blocks directly into Markdown without putting a mess of code on your pages.

In this guide we take a deep dive into advanced Hugo shortcode development—how to create your own components, pass parameters, use inner content, create conditional logic, and even build dynamic UI blocks like cards, embeds, alerts, tabs, buttons, and more.

What Are Hugo Shortcodes?

Shortcodes in Hugo are reusable snippets stored in:

1/layouts/shortcodes/

Then inserted inside Markdown with:

1{{< shortcode >}}

or with content:

1{{< shortcode >}}
2Content here
3{{< /shortcode >}}

1. Why Use Advanced Shortcodes?

Advanced shortcodes allow you to:

• Build reusable components across your site
• Reduce repetitive HTML in posts
• Maintain design consistency
• Allow non-technical editors to embed complex UI
• Add conditional logic and dynamic rendering
• Generate components using front-matter values

They are like mini React components, but for Hugo.

2. Basic Shortcode with Parameters

Example: a button shortcode

File: /layouts/shortcodes/button.html

1<a href="{{ .Get "href" }}" class="btn {{ .Get "type" }}">
2  {{ .Get "text" }}
3</a>

Use it in Markdown:

1{{< button href="/contact" text="Contact Us" type="primary" >}}

3. Shortcodes with Inner Content

Useful for cards, notices, quotes, etc.

File: /layouts/shortcodes/notice.html

1<div class="notice notice-{{ .Get "type" }}">
2  {{ .Inner | markdownify }}
3</div>

Usage:

1{{< notice type="warning" >}}
2Always back up your Hugo site while editing themes.
3{{< /notice >}}

4. Shortcodes With Conditional Logic

Example: a responsive YouTube embed that supports both ID and URL.

File: /layouts/shortcodes/youtube.html

 1{{ $id := .Get "id" }}
 2{{ if not $id }}
 3  {{ $id = replaceRE ".*v=([^&]+).*" "$1" (.Get "url") }}
 4{{ end }}
 5
 6<div class="yt-container">
 7  <iframe loading="lazy"
 8    src="https://www.youtube.com/embed/{{ $id }}"
 9    allowfullscreen></iframe>
10</div>

Usage:

1{{< youtube url="https://www.youtube.com/watch?v=abcd1234" >}}

Or:

1{{< youtube id="abcd1234" >}}

5. Dynamic Cards Component

A flexible card shortcode with image, title, link, and content.

File: /layouts/shortcodes/card.html

 1<div class="card">
 2  {{ with .Get "image" }}
 3    <img src="{{ . }}" alt="{{ $.Get "title" }}" class="card-img" />
 4  {{ end }}
 5  
 6  <h3 class="card-title">{{ .Get "title" }}</h3>
 7
 8  <div class="card-content">
 9    {{ .Inner | markdownify }}
10  </div>
11
12  {{ with .Get "link" }}
13    <a href="{{ . }}" class="card-btn">Read More</a>
14  {{ end }}
15</div>

Usage:

1{{< card title="Hugo Shortcodes" image="/img/hugo.png" link="/shortcodes" >}}
2Build custom dynamic components using shortcodes.
3{{< /card >}}

6. Loop-Based Shortcodes

Front matter:

1tools:
2  - Hugo
3  - Go
4  - TailwindCSS
5  - Cloudflare Pages

Shortcode:

File: /layouts/shortcodes/list-tools.html

1<ul class="tools">
2  {{ range .Page.Params.tools }}
3    <li>{{ . }}</li>
4  {{ end }}
5</ul>

Usage:

1{{< list-tools >}}

7. Shortcode That Reads External Markdown

File: /layouts/shortcodes/include.html

1{{ $file := .Get "file" }}
2{{ readFile $file | markdownify }}

Usage:

1{{< include file="/content/snippets/guide.md" >}}

8. Using Shortcodes to Build Custom Layout Elements

You can create your own UI components:

• Tabs
• Accordions
• Sliders
• Pricing tables
• FAQ blocks
• Author box
• Custom code examples

Example: Tab Component

1{{< tabs >}}
2{{< tab name="Hugo" >}}Hugo is a static site generator.{{< /tab >}}
3{{< tab name="Go" >}}Go is the language Hugo is written in.{{< /tab >}}
4{{< /tabs >}}

9. Shortcode Best Practices

✔ Keep HTML minimal

Use CSS classes for styling.

✔ Use .Inner | markdownify

Allows nested Markdown inside shortcodes.

✔ Default values example:

1{{ default "primary" (.Get "type") }}

✔ Avoid inline CSS

Keeps themes clean and maintainable.

10. When to Use Shortcodes vs Partials

Shortcodes → content
Partials → templates

Conclusion

Hugo shortcodes drastically upgrade what you can do inside Markdown. When you start building advanced components—cards, notices, tabs, embeds, lists, content blocks—you turn Hugo into a full design system.

And the best part: your blog stays extremely fast and simple to maintain.