Template Shortcodes

Shortcodes are template-based content components you can add without writing Python. Place a Kida template intemplates/shortcodes/and call it from Markdown using Hugo-compatible syntax.

When to Use Shortcodes vs Directives

Choose a shortcode when:

• Output is simple HTML from args (styled blockquote, custom figure)
• No strict validation needed (e.g., "any URL" iframe)
• You want non-developers to add or customize it
• You want to override without touching code

Choose a directive when:

• You need validation (YouTube 11-char ID, Spotify 22-char ID)
• You need computed URLs, privacy mode, or complex options
• You need parent-child nesting (e.g.,:::{step} inside :::{steps})
• You want structured errors and build-time safety

See Custom Directives for the Python path.

Notation: Markdown vs Standard

Shortcodes support two notations that control how inner content is processed:

Use Markdown notation when inner content should support formatting (e.g.**bold**, [links](url)):

<blockquote class="blockquote">&lt;p&gt;The only way to do great work is to &lt;strong&gt;love&lt;/strong&gt; what you do.&lt;/p&gt;

  <footer>— Jane</footer>
</blockquote>

Use standard notation when inner content should stay as-is (e.g. raw HTML or code):

<pre><code class="language-python">
def hello(): print(&quot;world&quot;)
</code></pre>

Creating a Shortcode

1. Create a template attemplates/shortcodes/<name>.html
2. Use it in content with{{ < name args > }} or {{ < name > }}content{{ < /name > }}

Self-Closing Shortcodes

For shortcodes without inner content:

{# templates/shortcodes/audio.html #}
{% set src = shortcode.Get("src") %}
{% if src %}<audio controls preload="auto" src="{{ src }}"></audio>{% end %}

In content:

<audio controls preload="auto" src="/audio/test.mp3"></audio>

Paired Shortcodes

For shortcodes with inner content:

{# templates/shortcodes/blockquote.html #}
<blockquote class="blockquote">
  {{- shortcode.Inner -}}
  {% set author = shortcode.Get("author") %}
  {% if author %}<footer>— {{ author }}</footer>{% end %}
</blockquote>

In content (use {{ % % }}for Markdown in inner content):

<blockquote class="blockquote">&lt;p&gt;The only way to do great work is to &lt;strong&gt;love&lt;/strong&gt; what you do.&lt;/p&gt;

  <footer>— Jane Doe</footer>
</blockquote>

Shortcode Context

Templates receive ashortcodeobject with Hugo-compatible methods:

You also havepage, site, and config in context. Use page.HasShortcode("name")in layouts to check if a page uses a given shortcode (e.g. to conditionally load CSS).

Arguments

Named arguments:

  <figure class="figure">
    
    <img src="/images/cat.jpg" alt="A cat" loading="lazy">
    
    
      <figcaption>Photo by Jane</figcaption>
    
  </figure>

Positional arguments:

Arguments with spaces must be quoted:

<blockquote class="blockquote">Quote
  <footer>— Jane Doe</footer>
</blockquote>

Subdirectory Shortcodes

Organize shortcodes in subdirectories:

templates/shortcodes/
├── media/
│   ├── audio.html
│   └── video.html
└── blockquote.html

Call with the path relative toshortcodes/:

{{< media/audio src=/audio/test.mp3 >}}

Built-in Shortcodes

The default theme ships with these shortcodes. Override any by placing a template with the same name in your project'stemplates/shortcodes/.

| HTML5 audio player | |blockquote|

<p>Quote</p>

<img src="/img.jpg" alt="..." loading="lazy">


  <figcaption>...</figcaption>

| Image with optional caption and link | |details|

code

bengal shortcodes list

{% if page.HasShortcode("audio") %}
  <link rel="stylesheet" href="/css/audio-player.css">
{% end %}

{# templates/shortcodes/img.html — used inside gallery #}
{% set cls = shortcode.Parent.Get("class") if shortcode.Parent else "" %}
<img src="{{ shortcode.Get('src') }}"{% if cls %} class="{{ cls }}"{% end %}>

{% set cols = shortcode.GetInt("cols", 3) %}
<div class="grid grid-cols-{{ cols }}">
  {{ shortcode.Inner }}
</div>