Reference/Markdown directives
Directive syntax
Directives extend markdown with the rich blocks a docs site needs: callouts, tabs, accordions, video embeds, and alignment. They are plain text, which matters in an agent-native product: your AI tool can write, read, and edit them like any other markdown.
This article covers the syntax rules. For every directive and its attributes, see the Directives reference.
The fence
A directive is a fenced block: three colons, the directive name, optional attributes in braces, the body, and three closing colons.
:::callout{type="tip"}
Publish early. You can always edit and republish.
:::
Which renders like this:
Publish early. You can always edit and republish.
The name comes immediately after the colons, with no space. The body is ordinary markdown: bold, links, lists, and code all work inside.
Attributes
Attributes sit in curly braces right after the name, as key="value" pairs:
:::video{src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
:::
Two strict rules keep parsing predictable:
- Values always use double quotes. Single quotes or bare values are not recognized.
- Values cannot contain quotes or escapes.
Most attributes are optional with sensible defaults. An invalid value does not break anything: the block renders with the default instead.
Nesting containers
Two directives are containers that hold other directives: tabs and accordions. Containers use a four-colon fence, and their children use the normal three colons:
::::tabs
:::tab{label="macOS"}
Press Cmd K to open search.
:::
:::tab{label="Windows"}
Press Ctrl K to open search.
:::
::::
The rule is simple: outer fence four colons, inner fences three, blank lines between blocks. Same-width nesting, like a callout inside a callout, is not supported.
Directives in code blocks
Anything inside a fenced code block is left alone. That is how this article shows literal directive syntax without rendering it, and it means code samples in your docs will never accidentally turn into rendered blocks.
When something is off: warnings, not errors
Clayo never rejects a save over directive problems. Instead, saves return warnings your agent reads and fixes:
| Warning | Meaning |
|---|---|
unknown_directive | The directive name is not in the registry |
unknown_attribute | An attribute is not recognized for this directive |
invalid_attribute_value | A value is outside the allowed set |
missing_required_attribute | A required attribute (like video's src) is absent |
long_content | The article is very long; consider splitting it |
On the live site, unknown directives degrade gracefully: the wrapper disappears and the body renders as ordinary markdown. Visitors never see raw colons or broken blocks.
Agents do not need to memorize any of this. The get_directives tool returns the machine-readable registry of every directive, attribute, and allowed value, so your agent can check before it writes.
A note on evolution
Directives are forward-only: once one ships, it stays supported, because removing it would visually change articles that already use it. You can use them freely without worrying about content rotting.