Admonitions Preset
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.
Included in the standard preset
zudoDoc() enables this admonition vocabulary by default — the directives field defaults to the canonical seven (@takazudo/). No separate configuration is necessary:
import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";
export default defineConfig(
zudoDoc({
siteName: "My Docs",
}),
);A bare defineConfig({ markdown: { features: { directives: {...} } } }) discards the rest of the preset (githubAlerts, codeTabs, ruby, and more) — use zudoDoc({...}) even when overriding the directives map. See Directives Registry for how to add or override entries.
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
:::detailstype also accepts the legacy:::details title="Click me"attribute form.:::cautionis part of the vocabulary this project registers; it emits<Caution>(data-admonition="caution"), mirroring how:::warningemits<Warning>.cautionis also reachable via GitHub Alerts as> [!CAUTION], so it is available through both paths.importantis not in thedirectivesmap 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, pass a
directivesmap tozudoDoc({...})inzfb.config.ts— see Directives Registry for the full pattern.GitHub Alerts emits the same admonition markup from
> [!NOTE]-style blockquotes; the two features coexist cleanly.