shortcodes

basalt ships ten shortcodes. They follow a few conventions: every shortcode that wraps a body uses Zola's {% foo() %}…{% end %} form, every parameter is keyword-only, and every shortcode has a no-JS fallback so the page keeps working without scripts.

Sections below: alert · collapsible · em · toc · image · carousel · asciinema · katex · mermaid · project

alert

GitLab-style callout for breaking a fact or warning out of the surrounding prose.

{% alert(kind="warning", title="Data deletion") %}
The following instructions will make your data unrecoverable.
{% end %}

Parameter	Required	Notes
`kind`	yes	`note` / `tip` / `important` / `caution` / `warning`. Unknown values fall back to `note`.
`title`	no	Override the default capitalised-kind title.
`body`	yes	Rendered through Zola's markdown filter.

collapsible

Native disclosure widget. <details> under the hood, no JavaScript.

Click to expand

Markdown works in here, including links, lists, and code.

{% collapsible(title="Click to expand", open=false) %}
Body markdown.
{% end %}

Parameter	Required	Notes
`title`	yes	Summary line.
`open`	no	`true` to start expanded.
`body`	yes	Markdown.

em

Editorial italic accent for hero titles and inline emphasis.

Software engineering from a small shop.

{% em() %}engineering{% end %}

Plain markdown *emphasis* inside an .editorial-hero__title picks up the same colour, so writers can use either form.

Parameter	Notes
`depth`	`1`, `2`, or `3`. Default `2` (h2 + h3).

image

Responsive <figure> with optional WebP srcset, caption, lightbox, and float positioning.

basalt homepage — Homepage in light mode.

{{ image(src="/img/screenshot.png", alt="…", caption="…", lightbox=true) }}

Parameter	Notes
`src`	Absolute site path, page-relative path, or remote URL.
`alt`	Accessibility text; defaults to `caption`.
`caption`	Renders as `<figcaption>`.
`widths`	Comma-separated px widths for the WebP srcset; default `400,800,1200`.
`width`	Sets `<img width>`.
`link`	Wraps the image in `<a href>`; takes precedence over `lightbox`.
`lightbox`	Click-to-enlarge in a `<dialog>`; without JS the anchor goes to the raw image.
`position`	`left` / `right` / `center` for floats.

carousel

Horizontal scroll-snap slideshow. JS pauses autoplay on hover; prefers-reduced-motion disables it.

basalt blog post — homepage · post · project

{{ carousel(srcs="/img/a.jpg, /img/b.jpg, /img/c.jpg",
              alts="First, Second, Third",
              caption="A walk through the demo",
              lightbox=true) }}

Parameter	Notes
`srcs`	Comma-separated image URLs.
`alts`	Comma-separated alt strings, aligned with `srcs`.
`caption`	Shared `<figcaption>`.
`lightbox`	Per-slide click-to-enlarge.
`autoplay`	Milliseconds between slides; disabled under `prefers-reduced-motion`.

The no-JS fallback is CSS scroll-snap.

asciinema

Lazy asciinema player. Loads the player chunk only when a [data-asciinema-cast] element is on the page; supports mp4 / gif fallbacks for no-JS visitors.

{{ asciinema(cast="/casts/demo.cast", title="A short demo", cols=80, rows=24) }}

Parameter	Notes
`cast`	Path to the `.cast` file (required).
`title`	Optional title in the player chrome.
`cols` / `rows`	Optional terminal size hints.
`mp4` / `gif`	Optional fallback URLs shown when JS is off.

katex

LaTeX expressions, lazy-loaded when math is detected on the page.

Inline: $E = mc^2$

Display:

$\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}$

Inline: {% katex() %}E = mc^2{% end %}

Display:
{% katex(block=true) %}
\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
{% end %}

Parameter	Notes
`body`	LaTeX expression as the shortcode body.
`block`	`true` for display mode; default inline.

mermaid

Diagrams via a markdown fence. No shortcode needed. Mermaid loads from jsDelivr only when a fence appears on the page. Diagrams re-render when the theme toggles so the colour palette tracks light/dark.

flowchart LR
  src[markdown fence] --> zola[zola build]
  zola --> html[code data-lang=mermaid]
  html --> js[mermaid-helper.ts]
  js -->|theme-changed| js
  js --> svg[rendered SVG]

```mermaid
flowchart LR
  A --> B --> C
```

project

Live GitHub / GitLab / Gitea / sourcehut card. Fetches repo metadata at build time.

zola

{{ project(link="https://codeberg.org/ttsigg/basalt") }}

Parameter	Notes
`link`	Repo URL (required). Host auto-detected from the domain.
`kind`	Force the fetcher: `"github"` / `"gitlab"` / `"gitea"` / `"sourcehut"`. For self-hosted instances.

Auto-detected hosts: github.com, gitlab.com, codeberg.org, git.sr.ht.