Shortcodes for Rich Content

Shortcodes are reusable content components you can use inside markdown files to embed rich content in your static site: videos, callout boxes, figures, and more, without writing raw HTML.

Syntax

There are two types of shortcodes:

Inline shortcodes

Output raw HTML. Use {{< and >}} delimiters:

{{< youtube(id="dQw4w9WgXcQ") >}}

Body shortcodes

Wrap markdown content that gets processed normally. Use {{% and %}} delimiters with a {{% end %}} closing tag:

{{% callout(type="warning") %}}
This is **bold** markdown inside the callout.
{{% end %}}

Arguments

All arguments are named (key=value). Supported value types:

• Strings: id="dQw4w9WgXcQ" (quoted)
• Integers: width=800
• Floats: ratio=1.5
• Booleans: autoplay=true

Built-in shortcodes

youtube

Embeds a responsive YouTube video player.

{{< youtube(id="dQw4w9WgXcQ") >}}

vimeo

Embeds a responsive Vimeo video player.

{{< vimeo(id="123456") >}}

gist

Embeds a GitHub Gist.

{{< gist(user="octocat", id="abc123") >}}

figure

Renders a semantic <figure> element with optional caption.

{{< figure(src="/static/photo.jpg", caption="Sunset over the bay", alt="Orange sunset") >}}

callout

Renders an admonition/callout box. This is a body shortcode. The content between the tags is processed as markdown.

{{% callout(type="warning") %}}
Be careful with this operation. It **cannot be undone**.
{{% end %}}

All 10 bundled themes include styled callout boxes with appropriate colors for each type.

Custom shortcodes

Create Tera templates in the templates/shortcodes/ directory. Each .html file becomes a shortcode named after the file.

Example: alert shortcode

Create templates/shortcodes/alert.html:

<div class="alert alert-{{ level | default(value='info') }}">
{{ body }}
</div>

Use in markdown:

{{% alert(level="error") %}}
Something went wrong. Please try again.
{{% end %}}

Template variables

Shortcode templates have access to:

• All named arguments as top-level variables
• {{ body }}: the raw body content (for body shortcodes)
• {{ page }}: current page context (title, slug, tags, etc.)
• {{ site }}: site context (title, base_url, language)

Example: button shortcode with conditional styling

Create templates/shortcodes/button.html:

<a href="{{ url }}"
   class="btn{% if style %} btn-{{ style }}{% endif %}"
   {% if external %}target="_blank" rel="noopener"{% endif %}>
  {{ label | default(value="Click here") }}
</a>

Use in markdown:

{{< button(url="/docs/getting-started", label="Get Started", style="primary") >}}
{{< button(url="https://github.com/user/repo", label="GitHub", external=true) >}}

Overriding built-in shortcodes

To customize a built-in shortcode, create a file with the same name in templates/shortcodes/. For example, templates/shortcodes/youtube.html will override the built-in YouTube embed.

Escaping shortcodes

To show shortcode syntax literally (e.g., in documentation), put it inside a fenced code block:

```
{{< youtube(id="example") >}}
```

Shortcodes inside fenced code blocks and inline code spans are never expanded.

Error handling

• Unknown shortcode: Build fails with the shortcode name and available alternatives
• Unclosed body shortcode: Build fails with the file path and line number
• Missing arguments: Build fails when the template references an undefined variable
• Invalid syntax: Build fails with a descriptive error and line number

All error messages include the source file path and line number for quick debugging.

Next Steps

• Templates & Themes: template variables available inside shortcode templates
• Theme Gallery: all bundled themes include styling for built-in shortcodes