Shortcodes

Beautiful Hugo ships with several shortcodes for common patterns like collapsible sections, multi-column layouts, tabbed content, image galleries, videos, and diagrams.

callout

The callout shortcode renders a Bootstrap alert-based callout box. It supports multiple paragraphs and an optional title. Nine styles are available, matching Bootstrap 5’s alert classes: primary, secondary, info (default), warning, danger, success, light, dark, and note (a custom grey style).

Live examples:

Source:

{{< callout info "Information" >}}
This is an **info** callout — the default style.

You can include multiple paragraphs.
{{< /callout >}}

{{< callout primary "Primary" >}}
This is a **primary** callout.
{{< /callout >}}

{{< callout secondary "Secondary" >}}
This is a **secondary** callout.
{{< /callout >}}

{{< callout warning "Caution" >}}
This is a **warning** callout.
{{< /callout >}}

{{< callout danger "Critical" >}}
This is a **danger** callout.
{{< /callout >}}

{{< callout success "All good" >}}
This is a **success** callout.
{{< /callout >}}

{{< callout light "Light" >}}
This is a **light** callout.
{{< /callout >}}

{{< callout dark "Dark" >}}
This is a **dark** callout.
{{< /callout >}}

{{< callout note >}}
This is a **note** callout (no title).
{{< /callout >}}

The type parameter defaults to info, so {{< callout >}} is equivalent to {{< callout info >}}. The title parameter is optional — omit it for a title-less callout.

details

The details shortcode renders a collapsible <details> element. The first positional parameter is the summary text; the inner content is the body.

Live example:

def hello():
    print("Hello from inside a details block!")

Source:

{{< details "Click to expand this section" >}}
This content is hidden by default. You can use **Markdown** here.
{{< /details >}}

columns / column

The columns and column shortcodes create a two-column layout using the splitbox CSS class. columns is a paired shortcode; column marks the boundary between the left and right column.

For historical reasons, you can also use {{< columns />}} ... {{< endcolumns >}} (note the required self-closing tag) as a backward compatibility shim.

Live example:

[Params]
  colorScheme = "auto"

Source:

{{< columns >}}
Left column content here.
{{< column >}}
Right column content here.
{{< /columns >}}

tabs / tab

The tabs and tab shortcodes render a Bootstrap 5 tabbed interface. Tabs with the same groupId across different blocks will switch in sync.

Live example — three tabs:

[Params]
  subtitle = "My Site"
  colorScheme = "auto"

Params:
  subtitle: "My Site"
  colorScheme: "auto"

{
  "Params": {
    "subtitle": "My Site",
    "colorScheme": "auto"
  }
}

Synchronized tabs — click a tab below and watch the one above switch too:

Source:

{{< tabs groupId="config-format" >}}
{{< tab "TOML" >}}
  ... content ...
{{< /tab >}}
{{< tab "YAML" >}}
  ... content ...
{{< /tab >}}
{{< tab "JSON" >}}
  ... content ...
{{< /tab >}}
{{< /tabs >}}

To synchronize tabs across multiple blocks, give them the same groupId:

{{< tabs groupId="config-format" >}}
{{< tab "TOML" >}} ... {{< /tab >}}
{{< tab "YAML" >}} ... {{< /tab >}}
{{< /tabs >}}

{{< tabs groupId="config-format" >}}
{{< tab "TOML" >}} ... {{< /tab >}}
{{< tab "YAML" >}} ... {{< /tab >}}
{{< /tabs >}}

beautifulfigure

The beautifulfigure shortcode renders a PhotoSwipe-enhanced figure with lightbox support, captions, attribution, and effects. See Figures & Galleries for the full parameter reference and live examples.

figure

The figure shortcode is a router. By default it delegates to beautifulfigure (PhotoSwipe-enhanced). When disableFigureOverride = true is set in your config, it uses Hugo’s standard <figure> shortcode instead.

See Figures & Galleries for details on the routing behavior and the disableFigureOverride flag.

gallery

The gallery shortcode renders an image gallery grid with PhotoSwipe support. It supports manual mode (place beautifulfigure shortcodes inside) and directory mode (auto-populate from a directory). See Figures & Galleries for the full parameter reference and live examples.

video

The video shortcode embeds a self-hosted video file in a <figure> that scales with the page width, with an optional caption. It uses the browser’s native player. For YouTube and Vimeo, use Hugo’s built-in youtube and vimeo shortcodes.

Paths resolve like beautifulfigure: page bundle resources and files under assets/ are published by Hugo, paths that start with / are served from static/, and remote URLs pass through. A poster image from a page bundle or assets/ is resized to at most 1280 pixels wide.

Live example:

Source:

{{< video src="/video/sample.mp4" poster="/video/sample-poster.jpg" width="480px" caption="A generated colour gradient, 8 seconds long and silent" attr="ffmpeg gradients" attrlink="https://ffmpeg.org/" >}}

A muted, looping clip that starts on its own works as an animated image replacement:

{{< video src="demo.webm" autoplay=true loop=true controls=false >}}

When the browser cannot play the file, a download link is shown in its place. The link text comes from the videoUnsupported i18n key.

icon

The icon shortcode renders a Font Awesome icon inline, so markdown content can use the icons the theme already loads. Give it the class list of the icon. Hugo does not allow positional and named arguments together, so use class="..." as soon as you add another argument. Add label when the icon carries meaning of its own; without it the icon is hidden from screen readers.

Live example:

Download the PDF guide, or read it on .

Source:

Download the {{< icon "fas fa-file-pdf" >}} PDF guide, or read it on {{< icon class="fab fa-github" label="GitHub" >}}.

mermaid

The mermaid shortcode renders Mermaid diagrams (flowcharts, sequence diagrams, Gantt charts, etc.) with automatic light/dark mode handling via dual-rendering. It accepts an optional align parameter (center, left, or right).

A ```mermaid fenced code block gives the same result through a codeblock render hook, and is the recommended form. The shortcode stays available.

See Math & Diagrams for live examples and source code.

no-ai-summary

The no-ai-summary shortcode wraps content in a <div data-nosnippet> element, telling search engines not to use that content for AI-generated summaries or snippets.

Live example:

Source:

{{< no-ai-summary >}}
This text is wrapped in `data-nosnippet` and should not appear in search engine AI summaries.
{{< /no-ai-summary >}}

See SEO & i18n for the full robot meta tags and AI summary limit configuration.

publications

The publications shortcode lists every type: publication page on the site, grouped by year, with the same markup as a publication section list. Use it to place the list on a regular page, such as a research group page.

Live example:

Source:

{{< publications links=false >}}

See Configuration — Publication Pages for the page type itself.

include-code

The include-code shortcode reads a source file from disk and renders it with syntax highlighting. It supports auto-detection of the language from the file extension, line numbers, and line highlighting (Chroma only).

See Code Blocks — Including External Files for the full parameter reference and live examples.