This collection of Hugo shortcodes is not meant to be an exhaustive list of components you might need in your Markdown content, rather it's a few examples that illustrate various techinques that will help you build out your own shortcodes. These techinques include: validating parameters (button), using a partial within the shortcode so layout and content can use the component (icon), using conditional content (ifparam), and passing parameters from a child shortcode to the parent for rendering (tabpane).

• alert
• blockquote
• button
• collapse
• figure
• file-list
• icon
• ifparam
• img
• include
• labeled-highlight
• param
• resource
• siteparam
• tabpane

To see the output of these shortcodes, run:

hugo server

Then visit http://localhost:1313 in your browser.

Requires Hugo v0.121.2 or later.

If you want to add an alert banner to your content, you can use the alert shortcode.

{{< alert severity="warning" size="small" >}}
  Markdown
{{< /alert >}}

<div class="alert alert--info alert--small">
  <div class="alert__icon">
    <svg class="icon icon--info icon--small">...</svg>
  </div>
  <div class="alert__body">
    Markdown
  </div>
</div>

If you want to add a blockquote to your content, you can use the blockquote shortcode.

{{< blockquote author="Author" cite="Source" url="https://www.huxley.net/" >}}
  Markdown
{{< /blockquote >}}

<blockquote cite="https://www.huxley.net/bnw/">
  <p>
    Markdown
  </p>
  <footer>
    —Author, <cite><a href="https://www.huxley.net/bnw/">Source</a></cite>
  </footer>
</blockquote>

If you want to add a button to your content, you can use the button shortcode.

{{< button href="https://github.com/" variant="primary" size="small" disabled="true" >}}
  Markdown
{{< /button >}}

If href begins with "http", then the link will open in a new window.

<a class="button button--primary button--small button--disabled">
  Markdown
</a>

If you want to collapse a block of content and show an expand button to reveal the full content, you can use the collapse shortcode.

{{< collapse maxHeight="100" >}}
  Markdown
{{< /collapse >}}

<div class="collapse">
  <input class="collapse__input" type="checkbox" id="collapse-00">
  <label class="collapse__label" for="collapse-00"></label>
  <div class="collapse__content">
    Markdown
  </div>
</div>

The collapse shortcode doesn't reliably work when nested in a tabpane shortcode. The expand button may still be visible when it's not needed. This is because the CSS display property of the inactive tabpane panel is set to none, so the height of the content cannot be determined on page load.

If you want to add an image with a caption to your content, you can use the figure shortcode.

{{< figure src="/path/to/image.jpg" alt="Alt text" title="Image caption" >}}

<figure>
  <img src="/path/to/image.jpg" alt="Alt text">
  <figcaption>Image caption</figcaption>
</figure>

If you want to display a list of links as a file list, you can use the file-list shortcode.

{{< file-list >}}
- [Page 1](page-1)
- [Page 2](page-2)
- [Page 3](page-3)
{{< /file-list >}}

The shortcode inner content must be an unordered list of anchor links.

<ul class="file-list">
  <li>
    <a href="page-1"><svg class="icon">...</svg> Page 1</a>
  </li>
  <li>
    <a href="page-2"><svg class="icon">...</svg> Page 2</a>
  </li>
  <li>
    <a href="page-3"><svg class="icon">...</svg> Page 3</a>
  </li>
</ul>

If you want to add an icon to your content, you can use the icon shortcode.

{{< icon name="alert" variant="primary" size="small" >}}

The icon file must be an svg, located in the /assets/icons/ directory.

<svg class="icon icon--primary icon--small">...</svg>

If you want to conditionally print some text based on a boolean parameter set in frontmatter, you can use the ifparam shortcode.

Let's say you have this parameter set in your frontmatter...

---
some_param: true
---

In your Markdown, you can conditionally print some text based on this parameter.

{{< ifparam "some_param" "enabled" "disabled" >}}

You can also leave the false value empty, and the shortcode will only print the text if the parameter is true.

If you want to add an image in your content, but need to set additional attributes not supported by Markdown image syntax, you can use the img shortcode.

{{< img src="/path/to/image.jpg" alt="Alt text" width="600" height="400" class="image" style="border: solid 1px red" >}}

<img src="/path/to/image.jpg" alt="Alt text" width="600" height="400" class="image" style="border: solid 1px red">

If you have HTML or Markdown that you would like to externally include in your content files, you can place the file under the current working directory. Then, you can use the include shortcode to pull in this file into your content.

{{< include "includes/file.md" >}}

• You must use {{< >}} shortcode delimiters to render the included content correctly.
• All included files under the content directory must have draft:true set in their frontmatter.
• Only relative paths under the page including the file are supported. Relative paths traversing up the directory are not supported. For files outside the current working directory you can use an absolute path starting with /.
• When editing an included file in local development, the page including the file is not automatically updated. Restarting the server is required to see any changes.
• The headings of included files will not be displayed in Hugo's TableOfContents.

Hugo automatically highlights content in code fences, and also provides a built-in highlight shortcode.

However, Hugo does not provide an option to display a title or filename.

If you need to label the code block, you can use the labeled-highlight shortcode.

{{< labeled-highlight label="users.json" lang="json" options="lineNos=true" >}}
{
  "name": "John",
  "age": 30
}
{{< /labeled-highlight >}}

You can also use a code fence as the content of the shortcode. The language and options of the code fence will be honored, and the lang and options parameters will be ignored.

{{< labeled-highlight "users.yaml" >}}
```yaml
name: "John"
age: 30
```
{{< /labeled-highlight >}}

<div class="labeled-highlight">
  <div class="labeled-highlight__label">
    <code>Label</code>
  </div>
  <div class="highlight">
    ...
  </div>
</div>

Rather than using a shortcode, an alternate solution is to add a title with Markdown attribute syntax to the code fence:

json {title="users.json",linenos=true}

Then add styles to display the title attribute:

.highlight[title] {
  &::before {
    content: attr(title);
    ...
  }
}

While this method avoids needing to use a shortcode, the shortcode allows for more control of the markup used to display the label.

If you need to print a frontmatter parameter in your Markdown, you can use the param shortcode.

Let's say you have this param set in your frontmatter:

---
title: Hugo shortcodes
---

Then in your Markdown, you can print the value of this parameter:

{{< param "title" >}}

You can also pass a second optional value that will only be returned if the parameter is empty.

{{< param "param_name" "default value" >}}

If you want to include a page resource in your Markdown, you can use the resource shortcode.

{{< resource "image.svg" >}}

If the resource is a raster image (webp, jpg, png, ...), then you can pass an optional process specification.

{{< resource "image.webp" "fill 200x200 jpg q80 lanczos" >}}

If the resource is a JavaScript or stylesheet file, the file contents will be printed on the page as text. If you would like to link to the file as an external resource, then you can pass an optional "external" param.

{{< resource "script.js" "external" >}}

Output

<script src="script.js"></script>

If you need to print a site parameter in your Markdown, you can use the siteparam shortcode.

{{< siteparam "param_name" >}}

You can also pass a second optional value that will only be returned if the site parameter is empty.

{{< siteparam "param_name" "default value" >}}

You can also access the site parameter by chaining the identifiers

{{< siteparam "a.b.c" >}}

If you want to add tabs to your content, you can use the tabpane shortcode.

{{< tabpane >}}
{{< tab label="Tab 1" >}}
  Markdown
{{< /tab >}}
{{< tab label="Tab 2" selected="true" >}}
  Markdown
{{< /tab >}}
{{< tab label="Tab 3" >}}
  Markdown
{{< /tab >}}
{{< /tabpane >}}

<div class="tabpane">
  <input type="radio" name="tabpane-00" id="tabpane-00-00" class="tabpane__input">
  <label class="tabpane__label" for="tabpane-00-00">
    Tab 1
  </label>
  <div class="tabpane__panel">
    Markdown
  </div>
  <input type="radio" name="tabpane-00" id="tabpane-00-01" class="tabpane__input">
  <label class="tabpane__label" for="tabpane-00-01">
    Tab 2
  </label>
  <div class="tabpane__panel">
    Markdown
  </div>
  <input type="radio" name="tabpane-00" id="tabpane-00-02" class="tabpane__input">
  <label class="tabpane__label" for="tabpane-00-02">
    Tab 3
  </label>
  <div class="tabpane__panel">
    Markdown
  </div>
</div>