Shortcodes

Shortcodes are simple snippets inside your content files calling built-in or custom templates.

Hugo created shortcodes to overcome markdown limitations like unsupported features that are easily implementable with raw html, like iframes, text alignment and over.

In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.

Built-in shortcodes

Hugo has a lot of built-in shortcodes, you can see them at https://gohugo.io/content-management/shortcodes/#use-hugos-built-in-shortcodes

Hugo’s built-in shortcodes cover many common, but not all, use cases. Hugo provides the ability to easily create custom shortcodes to meet your website’s needs.

Create custom shortcodes

To create a shortcode, place an HTML template in the layouts/shortcodes directory. Consider the file name carefully since the shortcode name will mirror that of the file but without the .html extension.

You can organize your shortcodes in subfolders, e.g. in layouts/shortcodes/boxes. These shortcodes would then be accessible with their relative path.

Shortcode templates have a simple lookup order:

/layouts/shortcodes/<SHORTCODE>.html
/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html

Example

For example to create a shortcode for centered aligned text you can create /layouts/shotcodes/center.html with the following content:

<div style="text-align: center;">
    {{.Inner}}
</div>

Now you can can use the center shortcode as shown below:

{{% center %}}
Centered text
{{% /center %}}

It will be automatically converted to:

<div style="text-align: center;">
<p>Centered text</p>
</div>

Note that you probably have to add the following section in config.toml to allow the conversion to raw html:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true