Shortcodes reference

Complete reference for all built-in shortcodes. See shortcodes concept for an overview and how to customize your theme for creating custom shortcodes.

include #

Include the contents of another file.

Parameters:

Parameter	Type	Default	Description
path	string	required	Path to the file (relative to project root), or an https:// URL
strip_frontmatter	bool	false	Remove +++-delimited TOML frontmatter from included content
rewrite_links	bool	false	Rewrite relative .md links to clean URL paths

Example:

{{ include(path="README.md", strip_frontmatter="true") }}

tabs #

Render tabbed content panels.

Parameters:

Parameter	Type	Default	Description
labels	string	required	Pipe-separated tab labels

Each tab’s content is separated by <!-- tab --> in the body.

Example:

note #

Styled callout box.

Parameters:

Parameter	Type	Default	Description
type	string	required	Style: info, warning, tip, danger

Examples:

Syntax:

<div class="callout callout--warning"><p class="callout__title"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"/></svg> Warning</p><div class="callout__body">

Be careful with this operation.

</div></div>

details #

Collapsible disclosure section.

Parameters:

Parameter	Type	Default	Description
summary	string	required	Text shown in the clickable summary
open	bool	false	Whether the section starts expanded

Example:

Click to expand

Hidden content revealed on click.

You can include any markdown here: bold, code, lists, etc.

Syntax:

<details class="details" open><summary>Click to expand</summary><div class="details__body">

This starts expanded.

</div></details>

figure #

Image with optional caption.

Parameters:

Parameter	Type	Default	Description
src	string	required	Image URL or path
alt	string	""	Alt text
caption	string	""	Caption displayed below the image
width	string	""	CSS width (e.g. "80%", "400px")

Syntax:

<figure class="figure" style="width: 80%"><img src="/images/screenshot.png" alt="Screenshot" loading="lazy"><figcaption>The dashboard view</figcaption></figure>

youtube #

Embed a YouTube video.

Parameters:

Parameter	Type	Default	Description
id	string	required	YouTube video ID

Syntax:

<div class="youtube"><iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen loading="lazy"></iframe></div>

gist #

Embed a GitHub Gist.

Parameters:

Parameter	Type	Default	Description
url	string	required	Full Gist URL
file	string	""	Specific file from the gist to embed

Syntax:

<div class="gist"><script src="https://gist.github.com/user/abc123.js?file=example.py"></script></div>

mermaid #

Render a Mermaid diagram.

Example:

graph LR
    A[Markdown] --> B[Zorto]
    B --> C[HTML]
    B --> D[CSS]
    B --> E[Sitemap]

Syntax:

<pre class="mermaid">graph LR
    A[Markdown] --&gt; B[Zorto]
    B --&gt; C[HTML]</pre>

pyref #

Auto-generate Python API reference documentation by introspecting a module at build time. Requires the python feature.

Parameters:

Parameter	Type	Default	Description
module	string	required	Python module name to document
recursive	bool	true	Walk submodules
exclude	string	""	Comma-separated names to exclude
include	string	""	Comma-separated allowlist (only document these)
private	bool	false	Include _private members

Example:

{{ pyref(module="zorto", exclude="main,core", recursive="false") }}

Generates HTML with function signatures, class methods, and docstrings. Doctest examples (>>> lines in docstrings) are executed at build time and their output is rendered inline.

configref #

Auto-generate configuration reference from a Rust source file’s doc comments and serde attributes.

Parameters:

Parameter	Type	Default	Description
src	string	required	Path to Rust source file (relative to site root)

Example:

{{ configref(src="../crates/zorto-core/src/config.rs") }}

Parses struct definitions, field types, /// doc comments, and #[serde(...)] attributes to generate HTML tables.

flow #

Horizontal step flow diagram with arrows between steps.

Parameters:

Parameter	Type	Default	Description
steps	string	required	Pipe-delimited steps, each as Label:Description or just Label
caption	string	""	Caption text below the diagram

Example:

Syntax:

{{ flow(steps="Write:Content|Build:Compile|Deploy:Ship", caption="Development workflow.") }}

layers #

Vertical layered stack diagram with numbered items.

Parameters:

Parameter	Type	Default	Description
items	string	required	Pipe-delimited items, each as Title:Description:badge
caption	string	""	Caption text below the diagram

Example:

Syntax:

{{ layers(items="Layer 1:Description:badge|Layer 2:Description:badge") }}

tree #

File tree visualization. Body content defines the tree structure, one entry per line.

Parameters:

Parameter	Type	Default	Description
caption	string	""	Caption text below the tree

Lines use indentation (2 spaces per level) for nesting. Append [tag] for labels. Directories end with /.

Example:

Syntax:

{% tree(caption="Project structure.") %}
content/
  _index.md  [section]
  about.md  [page]
{% end %}

compare #

Side-by-side comparison cards.

Parameters:

Parameter	Type	Default	Description
left_title	string	""	Title for the left card
left	string	required	Body text for the left card
right_title	string	""	Title for the right card
right	string	required	Body text for the right card
left_style	string	"accent"	Style: accent (blue), green, or muted
right_style	string	"green"	Style: accent, green, or muted
caption	string	""	Caption text below

Example:

Syntax:

{{ compare(left_title="Option A", left="Description A", right_title="Option B", right="Description B") }}

cascade #

Override/priority cascade diagram. The last item is highlighted as the winner.

Parameters:

Parameter	Type	Default	Description
items	string	required	Pipe-delimited items, each as Priority:Label:badge
caption	string	""	Caption text below

Example:

Syntax:

{{ cascade(items="Low:Default value:default|High:Your override:wins") }}

Presentation shortcodes #

The following shortcodes are designed for use in presentations but work in any page.

slide_image #

Absolutely positioned image for slide layouts.

Parameters:

Parameter	Type	Default	Description
src	string	required	Image path or URL
alt	string	""	Alt text
top	string		CSS top position (e.g. "10%", "50px")
left	string		CSS left position
right	string		CSS right position
bottom	string		CSS bottom position
width	string		CSS width
height	string		CSS height

Syntax:

{{ slide_image(src="logo.png", top="10%", right="5%", width="200px") }}

speaker_notes #

Speaker notes for reveal.js presentations. Press S in a presentation to open the speaker view.

Syntax:

{% speaker_notes() %}
Remember to mention the key point about performance.
{% end %}

fragment #

Progressive reveal — content appears on each click/advance within a slide.

Parameters:

Parameter	Type	Default	Description
style	string	"fade-in"	Animation style. Validated against an allowlist; an unknown value errors at build time rather than rendering a no-op fragment.

Allowed styles: fade-in, fade-out, fade-up, fade-down, fade-left, fade-right, grow, shrink, strike, highlight-red, highlight-blue, highlight-green, highlight-current-red, highlight-current-blue, highlight-current-green.

Syntax:

{% fragment(style="fade-in") %}
This appears on click.
{% end %}

columns #

Multi-column layout. Body content is split on <!-- column --> markers.

Parameters:

Parameter	Type	Default	Description
widths	string	equal	Pipe-separated column widths (e.g. `“60%

Syntax:

{% columns(widths="60%|40%") %}
Left column content

<!-- column -->

Right column content
{% end %}