{% example %}

Attributes

Parameter	Type	Required	Description
id	string	✓	Unique kebab-case identifier — no type prefix (e.g., 'sign-in-steps')
summary	string	✓	One-line description shown in the gallery table header and modal dialog title
tags	string	—	Space-separated labels for filtering in the gallery (e.g., 'api auth')
group	string	—	Group id — examples sharing the same group render together in a tab group
label	string	—	Short tab label — overrides summary as the tab title in grouped examples
scope	string	—	Visibility scope — inherits from parent; may narrow to 'agent' or 'public'

Valid Parent Contexts

This tag is valid inside: {% domain %}, {% feature %}, {% flow %}, {% role %}, {% manifest %}, {% blueprint %}, {% story %}, {% milestone %}, {% changeset %}, {% tag %}

Rules

Rule	Force	Realm	Reference	Description
example-id-unique	must	global	—	must be unique across all documents in the spec. Duplicate ids trigger a compiler warning. convention
example-id-kebab-case	must	global	—	is plain kebab-case — no type prefix. conventionnaming
example-scope-inherited	must	global	—	Scope is inherited from the parent tag. To restrict to agent-only output, set . scope

Examples appear inline on the document page as styled cards and are collected globally into an Examples Gallery at /examples. The body may be prose, a fenced code block, or a mix.

Usage

Prose body

Code body

Use a fenced code block as the body to show formatted code. The fence language (json, typescript, etc.) is preserved for syntax highlighting in the gallery:

Grouped examples (tab group)

Use the group attribute to render multiple examples as tabs within a single card. Each example’s summary becomes the tab label:

Agent bundle shape

{
  "examples": [
    { "id": "sign-in-steps", "summary": "Happy path for user sign-in", "tags": ["ux", "flow"], "content": "1. User navigates to /login\n..." }
  ]
}

content is the raw body text (preserves code fence syntax). It is suitable for agent consumption. The rendered HTML version is used by the gallery component and is not stored in the TOON bundle.

Examples Gallery aggregate

The public pass collects every \{% example %\} from all documents and writes src/content/docs/examples.mdx, which renders as /examples on the site. The page shows:

• A tag filter bar — clickable chips to narrow the list by tag
• A table — columns: Summary | Tags | Source (linked to the defining document)
• On row click — a wa-dialog modal showing the full rendered body and a “View source” link

The example tag's own prose body usage illustration

tagexampleprose example-tag-prose-usage

{% example id="sign-in-steps" summary="Happy path for user sign-in" tags="ux flow" %}
1. User navigates to /login
2. Enters email and password
3. Clicks "Sign in"
4. System validates credentials and issues a session token
5. User is redirected to /dashboard
{% /example %}

Happy path for user sign-in

uxflow sign-in-steps

1. User navigates to /login 2. Enters email and password 3. Clicks "Sign in" 4. System validates credentials and issues a session token 5. User is redirected to /dashboard

The example tag's own code body usage illustration

tagexamplecode example-tag-code-usage

{% example id="login-request" summary="Login API request payload" tags="api auth" %}
(code fence with language "json" here)
{ "email": "user@example.com", "password": "secret123" }
(end code fence)
{% /example %}

Login API request payload

apiauth login-request

(code fence with language "json" here) { "email": "user@example.com", "password": "secret123" } (end code fence)

Grouped example tabs for the same endpoint

tagexamplegroup example-tag-group-usage

{% example id="login-curl" summary="cURL" tags="api auth" group="login-request" %}
(code fence with language "bash" here)
curl -X POST /api/login -d '{"email":"user@example.com"}'
(end code fence)
{% /example %}

{% example id="login-fetch" summary="Fetch API" tags="api auth" group="login-request" %}
(code fence with language "typescript" here)
const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify({ email: 'user@example.com' }) });
(end code fence)
{% /example %}

apiauth login-curl

cURL

(code fence with language "bash" here) curl -X POST /api/login -d '{"email":"user@example.com"}' (end code fence)

Fetch API

(code fence with language "typescript" here) const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify({ email: 'user@example.com' }) }); (end code fence)