Admonitions Preset

Created May 28, 2026Updated Jun 14, 2026Takeshi Takatsudo

How this project registers the admonition vocabulary via the directives map.

zfb provides the directives registry as a generic mechanism (the engine). This project registers the admonition vocabulary — note, tip, warning, danger, info, caution, and details — as the recipe, enabling the CommonMark Directives ::: fence syntax for callout blocks.

Opt-in feature

Enable admonitions by adding the directives map to zfb.config.ts:

// zfb.config.ts export default defineConfig({ markdown: { features: { directives: { note: "Note", tip: "Tip", info: "Info", warning: "Warning", danger: "Danger", caution: "Caution", details: "Details", }, }, }, });

Syntax

Wrap content in a :::<type> fence. Each fence line — the opening :::note and the closing ::: — must be separated from the surrounding content by blank lines, or parsing fails and the build emits a warning.

:::note

Body content goes here.

:::

A bracketed label after the type becomes the admonition title:

:::tip[Optional title]

Body content.

:::

Live demo

The seven directives below are rendered live by this admonitions recipe.

Note

This is a note. Use it for neutral, supplementary information.

Tip

This is a tip. Use it for helpful advice or shortcuts.

Info

This is an info callout. Use it for contextual background.

Warning

This is a warning. Use it for things the reader should be careful about.

Danger

This is a danger callout. Use it for destructive or irreversible actions.

Caution

This is a caution callout. Use it for risky steps the reader should approach carefully.

Click to expand

This is a details block — a collapsible disclosure. The body stays hidden until the reader expands it.

Emitted markup

Each directive compiles to a JSX element (for example <Note title="Optional title">), which zudo-doc renders as:

<div data-admonition="note" class="admonition admonition-note">
  <p class="admonition-title">…</p>
  <div class="admonition-body">…</div>
</div>

The type class (admonition-note, admonition-tip, admonition-warning, admonition-danger, admonition-info, admonition-caution) and the matching data-admonition attribute let the stylesheet color each variant distinctly.

Notes

The :::details type also accepts the legacy :::details title="Click me" attribute form.
:::caution is part of the vocabulary this project registers; it emits <Caution> (data-admonition="caution"), mirroring how :::warning emits <Warning>. caution is also reachable via GitHub Alerts as > [!CAUTION], so it is available through both paths.
important is not in the directives map and cannot be used as :::important. It is only available via GitHub Alerts as > [!IMPORTANT], which maps to the <Important> component (data-admonition="important").
To add or override directives, extend the directives map in zfb.config.ts with additional name → title pairs.
GitHub Alerts emits the same admonition markup from > [!NOTE]-style blockquotes; the two features coexist cleanly.

View source on GitHub