Shortcodes Hugo and PaperMod

Below is a combined, alphabetical list of common shortcodes from both sources, with (Hugo) for Hugo and (CustP) for Custom PaperMod.

before - Creates the ‘before’ panel in a side-by-side comparison (CustP) .
callout - Creates a highlighted aside with types like info, warning, tip, note, or success (CustP) .
compare - Wraps a before/after comparison block for side-by-side visuals (CustP) .
details - Inserts an HTML <details> element for a collapsible content block (Hugo) .
figure - Inserts an HTML <figure> element with advanced image placement and caption options (Hugo) .
gist - Embeds a GitHub Gist (Hugo) .
highlight - Displays syntax-highlighted code with configurable options (Hugo) .
image - Processes and embeds images with attributes like width and alt text (CustP) .
instagram - Embeds an Instagram post (Hugo) .
param - Inserts a parameter value from front matter or site configuration (Hugo) .
pullquote - Displays a large-format quote for emphasis (CustP) .
qr - Generates a QR code image from a provided string (Hugo) .
ref - Creates a canonical (absolute) permalink to another page (Hugo) .
relref - Creates a relative permalink to another page (Hugo) .
stat - Displays a single metric tile with a number and label (CustP) .
stats - Wraps a group of stat tiles in a flex container (CustP) .
step - Creates a single numbered step within a steps block (CustP) .
steps - Wraps a sequence of step shortcodes for auto-numbered procedures (CustP) .
vimeo - Embeds a Vimeo video player (Hugo) .
x - Embeds an X (formerly Twitter) post (Hugo) .
youtube - Embeds a YouTube video player (Hugo) .

Example .md File with Shortcode Usage

An example Markdown file demonstrating how to use a mix of these shortcodes in your content. Remember, custom shortcodes like callout must be defined by you before they can be used.

---
title: "Complete Shortcode Showcase"
date: 2026-08-10
description: "A demonstration of using all available shortcodes in Hugo and PaperMod"
---

This page demonstrates all the shortcodes available in Hugo (H) and PaperMod (P).

# ===== HUGO BUILT-IN SHORTCODES =====

## details (H)
Creates an HTML `<details>` element for a collapsible content block.
{{< details summary="Click to expand the details!" >}}
This content is hidden behind a clickable summary, just like an HTML `<details>` element.
{{< /details >}}

## figure (H)
Inserts an HTML `<figure>` element with advanced image placement and caption options.
{{< figure src="/images/example.jpg" title="Example Image" caption="This is a figure caption" alt="Example image alt text" >}}

## gist (H)
Embeds a GitHub Gist.
{{< gist username/123456 >}}

## highlight (H)
Displays syntax-highlighted code with configurable options.
{{< highlight javascript "linenos=true" >}}
function greet(name) {
  console.log(`Hello, ${name}!`);
}
{{< /highlight >}}

## instagram (H)
Embeds an Instagram post.
{{< instagram BXx5UjGjKQw >}}

## param (H)
Inserts a parameter value from front matter or site configuration.
{{< param "description" >}}

## qr (H)
Generates a QR code image from a provided string.
{{< qr "https://example.com" >}}

## ref (H)
Creates a canonical (absolute) permalink to another page.
{{< ref "blog/another-post.md" >}}

## relref (H)
Creates a relative permalink to another page.
{{< relref "blog/another-post.md" >}}

## vimeo (H)
Embeds a Vimeo video player.
{{< vimeo 123456789 >}}

## x (H)
Embeds an X (formerly Twitter) post.
{{< x user=username id=123456789 >}}

## youtube (H)
Embeds a YouTube video player.
{{< youtube OmrSCNXguQ4 >}}


# ===== PAPERMOD / CUSTOM SHORTCODES =====

## before (P)
Creates the 'before' panel in a side-by-side comparison.
{{< before >}}
This is the before content.
{{< /before >}}

## callout (P)
Creates a highlighted aside with types like info, warning, tip, note, or success.
{{< callout type="warning" >}}
⚠️ **Important:** Make sure to back up your data before running this command.
{{< /callout >}}

## compare (P)
Wraps a before/after comparison block for side-by-side visuals.
{{< compare >}}
{{< before >}}
This is the before content.
{{< /before >}}
{{< after >}}
This is the after content.
{{< /after >}}
{{< /compare >}}

## image (P)
Processes and embeds images with attributes like width and alt text.
{{< image path="photo.jpg" width=600 alt="A scenic mountain view" >}}

## pullquote (P)
Displays a large-format quote for emphasis.
{{< pullquote >}}
This is a large-format quote that stands out from the text.
{{< /pullquote >}}

## stat (P)
Displays a single metric tile with a number and label.
{{< stat value="1,000+" label="Users" >}}

## stats (P)
Wraps a group of stat tiles in a flex container.
{{< stats >}}
{{< stat value="1,000+" label="Users" >}}
{{< stat value="500+" label="Posts" >}}
{{< stat value="10k+" label="Views" >}}
{{< /stats >}}

## step (P)
Creates a single numbered step within a steps block.
{{< step "Create the shortcode file" >}}
Add `layouts/shortcodes/callout.html` to your project.
{{< /step >}}

## steps (P)
Wraps a sequence of step shortcodes for auto-numbered procedures.
{{< steps >}}
{{< step "Create the shortcode file" >}}
Add `layouts/shortcodes/callout.html` to your project.
{{< /step >}}
{{< step "Add the CSS" >}}
Create `assets/css/extended/components.css` with the component styles.
{{< /step >}}
{{< /steps >}}

How to Activate Custom PaperMod Shortcodes

Activating a custom shortcode in Hugo PaperMod is a simple two-step process: creating the template and adding the styles.

  1. Create the Template The shortcode’s logic lives in an HTML file. Create a file named after your shortcode (e.g., callout.html) and place it in the layouts/shortcodes/ directory of your Hugo project . This tells Hugo how to process the shortcode when it’s called in your content.

  2. Add the Styles (Optional but Recommended) While a shortcode can work without styling, it will look like plain text. To make it visually match your theme, add the CSS rules for your new component. Create a CSS file (e.g., components.css) and save it in the assets/css/extended/ folder . PaperMod automatically loads and bundles all CSS files found in this directory, so no manual import is necessary .

After these two files are created, your new shortcode is ready to be used with the {{< shortcode-name >}} syntax in any of your Markdown posts.