Shortcodes

Shortcodes let you add styled components to your content without writing HTML.

Code blocks

Markdown fenced code blocks are styled automatically. If a language is provided, the code block header shows it and includes a Copy button when the browser supports the Clipboard API.

```toml
theme = "devlab-theme"
compile_sass = true
```

theme = "devlab-theme"
compile_sass = true

Cards

Cards are useful for linking to related pages or highlighting standalone information.

Linked card

Fast setup

Start building your documentation site with Zola.

{% card(title="Fast setup", href="/docs/getting-started/") %}
Start building your documentation site with Zola.
{% end %}

Static card

Project status

DevLab Theme is under active development.

{% card(title="Project status") %}
DevLab Theme is under active development.
{% end %}

Callouts

Callouts highlight important information. Four types are available:

info
warning
error
tip

Info

info

Note: Zola must be installed before you start.

{% callout(type="info") %}
**Note:** Zola must be installed before you start.
{% end %}

Warning

warning

Changing zola.toml while the dev server is running may require a restart.

{% callout(type="warning") %}
Changing `zola.toml` while the dev server is running may require a restart.
{% end %}

Error

error

Do not delete the public/ folder while the dev server is running.

{% callout(type="error") %}
Do not delete the `public/` folder while the dev server is running.
{% end %}

Tip

tip

Use zola serve for instant preview during development.

{% callout(type="tip") %}
Use `zola serve` for instant preview during development.
{% end %}

Custom title

Override the default title with the title parameter:

Did you know?

You can set any title you want - it does not have to match the callout type.

{% callout(type="info", title="Did you know?") %}
You can set any title you want.
{% end %}

Icons

DevLab Theme includes a small SVG icon library. Icons live as individual template files in templates/macros/icons/, while the icon shortcode gives Markdown content a stable, documented API.

Basic usage

Use name to render an icon inline with text:

GitHub Codeberg Matrix

GitHub {{ icon(name="github") }} Codeberg {{ icon(name="codeberg") }} Matrix {{ icon(name="matrix") }}

By default, icons are decorative and hidden from screen readers.

Parameters

Parameter	Required	Default	Description
`name`	Yes	-	Icon filename without `.html`, for example `github` or `warning`.
`size`	No	`inline`	Visual size. Available values: `sm`, `inline`, `md`, `lg`.
`label`	No	-	Accessible label. Use it when the icon communicates meaning without adjacent text.
`extra_class`	No	-	Extra CSS class added to the shortcode wrapper.

Sizes

{{ icon(name="check", size="sm", label="Small icon") }}
{{ icon(name="check", size="inline", label="Inline icon") }}
{{ icon(name="check", size="md", label="Medium icon") }}
{{ icon(name="check", size="lg", label="Large icon") }}

Accessibility

When the surrounding text already names the action or brand, omit label:

[GitHub {{ icon(name="github") }}](https://github.com/you)

When the icon stands alone, add label:

{{ icon(name="external-link", label="External link") }}

Using icons in templates

Include icons directly in your templates with {% include %}:

<footer>
  <a href="https://github.com/you">{% include "macros/icons/github.html" %}</a>
  <a href="https://matrix.to/#/...">{% include "macros/icons/matrix.html" %}</a>
</footer>

If you prefer a named helper, import the shared icon macro:

{% import "macros/icons.html" as icons %}

{{ icons::render_icon(name="github") }}

Available icons

Theme

Icon	Purpose
`sun`	Light mode toggle
`moon`	Dark mode toggle

Social / Brand

Icon	Icon	Icon	Icon
`github`	`gitlab`	`codeberg`	`matrix`
`zulip`	`telegram`	`discord`	`rss`
`email`	`link`

UI / Interface

Icon	Icon	Icon	Icon
`search`	`chevron-right`	`external-link`	`copy`
`check`	`info`	`warning`	`menu`
`x`	`arrow-left`	`arrow-right`

Adding a new icon

Create templates/macros/icons/your-name.html with the SVG markup.
Add a branch to templates/macros/icons.html:

{% elif name == "your-name" %}{% include "macros/icons/your-name.html" %}

Use it from Markdown with {{ icon(name="your-name") }}, or from templates with {% include "macros/icons/your-name.html" %}.

Keep icon filenames lowercase and descriptive. If the icon is purely decorative, include aria-hidden="true" and focusable="false" on the SVG.