Shortcodes

Shortcodes let you embed rich, structured content in markdown without writing raw HTML. They bridge the gap between markdown’s simplicity and the flexibility of full templates.

Syntax #

Inline shortcodes (no body) use double curly braces:

{{ figure(src="/images/photo.jpg", alt="A photo", caption="My caption") }}

Body shortcodes (wrap content) use curly-percent:

{% note(type="warning") %}
Be careful with this operation.
{% end %}

Built-in shortcodes #

The diagram shortcodes (flow, layers, tree, compare, cascade) render pure CSS/HTML visuals with no JavaScript. They are used throughout these docs — see content model and AI-native for examples.

The presentation shortcodes (slide_image, speaker_notes, fragment, columns) are designed for use in presentations but work in any page.

See the shortcodes reference for parameters and live examples.

Custom shortcodes #

Create a template in templates/shortcodes/ to define your own:

<!-- templates/shortcodes/greeting.html -->
<p class="greeting">Hello, {{ name }}!</p>

Use it in markdown:

{{ greeting(name="world") }}

Body shortcodes receive the inner content as body:

<!-- templates/shortcodes/card.html -->
<div class="card">
  <h3>{{ title }}</h3>
  {{ body }}
</div>

{% card(title="My card") %}
Card content goes here.
{% end %}

Shortcodes vs. callouts vs. templates #

Further reading #

• Shortcodes reference — all 19 built-in shortcodes with live examples
• Callouts — GitHub-style alert boxes
• Templates — the Tera template engine
• How to customize your theme — create custom shortcodes