Blog
Hextra Shortcodes Cheat Sheet: Make Your Hugo Blog More Expressive

Hextra Shortcodes Cheat Sheet: Make Your Hugo Blog More Expressive

June 17, 2026

Hextra is a modern Hugo theme for documentation and blogs. Beyond standard Markdown, it ships with a rich set of shortcodes to enhance your content. This post covers the most useful ones with syntax and live rendered examples.

Collapsible Content (details)

Use to hide/show a block of content. Great for FAQ, supplementary notes, and long code snippets.

Expanded by Default

Click to collapse
This is expanded by default. It supports Markdown, including code, links, and lists. 
{{% details title="Click to collapse" %}}
This is expanded by default. It supports **Markdown**.
{{% /details %}}

Collapsed by Default

Click to expand
This is hidden by default. Click the title to reveal. 
{{% details title="Click to expand" closed="true" %}}
This is hidden by default.
{{% /details %}}

Note

Use {{% %}} delimiters (percent sign), otherwise Markdown inside won’t render.

Callouts

Use to display eye-catching notices within your content.

Default (Orange)

This is a default callout.
{{< callout >}}
  This is a default callout.
{{< /callout >}}

Info (Blue)

ℹ️
This is an info callout, for supplementary information.
{{< callout type="info" >}}
  This is an info callout, for supplementary information.
{{< /callout >}}

Warning (Yellow)

⚠️
This is a warning callout. Pay attention.
{{< callout type="warning" >}}
  This is a warning callout. Pay attention.
{{< /callout >}}

Error (Red)

🚫
This is an error callout. Dangerous operation.
{{< callout type="error" >}}
  This is an error callout. Dangerous operation.
{{< /callout >}}

Custom Emoji

👾
Use any emoji as the icon.
{{< callout emoji="👾" >}}
  Use any emoji as the icon.
{{< /callout >}}

GitHub-Style Alerts

Similar to callouts, but with lighter Markdown-only syntax.

Note

Supplementary info (blue).

Tip

Helpful suggestion (green).

Important

Key information (purple).

Warning

Caution needed (amber).

Caution

Dangerous operation (red).

> [!NOTE]
> Supplementary info (blue).

> [!TIP]
> Helpful suggestion (green).

When to use: Custom emoji → callout; simple labels → Alerts.

Tabs

Use to display parallel content, such as multi-language code or platform-specific steps.

{ "hello": "world" }
hello: world
hello = "world"
{{< tabs items="JSON,YAML,TOML" >}}
  {{< tab >}}
  ```json
  { "hello": "world" }
  ```
  {{< /tab >}}
  {{< tab >}}
  ```yaml
  hello: world
  ```
  {{< /tab >}}
  {{< tab >}}
  ```toml
  hello = "world"
  ```
  {{< /tab >}}
{{< /tabs >}}

Default selects the first tab. Use defaultIndex="1" to select the second.

Card Grid (cards + card)

Use for post recommendations, resource lists, and feature showcases. Supports icons, images, and tags.

Visit Blog
See all posts
 About Me
Learn more
 
{{< cards cols="2" >}}
  {{< card link="/blog" title="Visit Blog" icon="pencil" subtitle="See all posts" >}}
  {{< card link="/about" title="About Me" icon="user" subtitle="Learn more" >}}
{{< /cards >}}

With tags:

With Tag
New
 Warning
Alert
 
{{< card link="/blog" title="With Tag" tag="New" tagType="info" >}}
{{< card link="/blog" title="Warning" tag="Alert" tagType="warning" >}}

Steps

Use for tutorials, installation guides, and step-by-step instructions.

Step 1

Install Hugo: brew install hugo (macOS) or choco install hugo (Windows).

Step 2

Create a site: hugo new site myblog

Step 3

Choose a theme and deploy.

{{% steps %}}
### Step 1
Install Hugo: `brew install hugo` (macOS) or `choco install hugo` (Windows).

### Step 2
Create a site: `hugo new site myblog`

### Step 3
Choose a theme and deploy.
{{% /steps %}}

Note

Each step must be an H3 (###) header. Use {{% %}} delimiters.

Enhanced Code Blocks

Add {filename="filename"} after the language tag to display a filename label.

app.py
def hello():
    print("Hello, world!")
```python {filename="app.py"}
def hello():
    print("Hello, world!")
```

Mermaid Diagrams

Write Mermaid syntax in a code block to render SVG diagrams.

graph LR
    A[Start] --> B[Process]
    B --> C[End]
```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

File Tree (filetree)

Use to display directory structures. Folders can be expanded/collapsed.

    • _index.md
      • post1.md
      • post2.md 
    • {{< filetree/container >}}
  {{< filetree/folder name="content" state="open" >}}
    {{< filetree/file name="_index.md" >}}
    {{< filetree/folder name="blog" state="open" >}}
      {{< filetree/file name="post1.md" >}}
    {{< /filetree/folder >}}
  {{< /filetree/folder >}}
{{< /filetree/container >}}

    state: "open" (default) or "closed".

    Inline Badges

    Small inline labels with 4 color variants.

    Default:

    Default
    Info:
    Info
    Warning:
    Warning
    Error:
    Error

    {{< badge content="Default" >}}
{{< badge content="Info" type="info" >}}
{{< badge content="Warning" type="warning" >}}
{{< badge content="Error" type="error" >}}

    With link and icon:

    GitHub
     
    {{< badge content="GitHub" link="https://github.com" icon="github" >}}

    Inline Icons

    Insert Heroicons inline with text.

    GitHub, Academic, Edit

    {{< icon "github" >}} GitHub

    Note

    Requires enableInlineShortcodes: true in site config.

    PDF Embed

    Embeds a PDF viewer in an iframe.

    {{< pdf "path/to/file.pdf" >}}

    Supports remote URLs and local file paths (in page bundles).

    Jupyter Notebook

    Renders .ipynb files inline with syntax-highlighted code cells, Markdown cells, and image output.

    {{% jupyter "notebook.ipynb" %}}

    Uses {{% %}} delimiters. Supports remote URLs.

    Quick Reference

    Need Shortcode Delimiter
    Collapsible text details {{% %}}
    Callout callout {{< >}}
    Tabs tabs + tab {{< >}}
    Steps steps {{% %}}
    Card grid cards + card {{< >}}
    File tree filetree/* {{< >}}
    Embed PDF pdf {{< >}}
    Embed Notebook jupyter {{% %}}
    Inline icon icon {{< >}}
    Badge badge {{< >}}
    Diagrams Mermaid ```mermaid
    Code with filename Code block attr ```lang {filename="..."}

    For full parameter reference, see the Hextra Shortcodes Documentation.

    🤖
    AI disclosure: This article was written by the author with assistance from Claude (Anthropic) for drafting, bilingual translation, and formatting. The author has reviewed all content and takes full responsibility for its accuracy.
    Last updated on