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.

:::note[Included in the standard preset]

`zudoDoc()` enables this admonition vocabulary by default — the `directives` field defaults to the canonical seven (`@takazudo/zudo-doc/directive-vocabulary-defaults`). No separate configuration is necessary:

```ts title="zfb.config.ts"
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](https://zudo-doc.takazudomodular.com/docs/markdown-features/directives-registry#custom-directives) 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.

```md
:::note

Body content goes here.

:::
```

A bracketed label after the type becomes the admonition title:

```md
:::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.

:::

:::details[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:

```html
<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](https://zudo-doc.takazudomodular.com/docs/markdown-features/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](https://zudo-doc.takazudomodular.com/docs/markdown-features/github-alerts) as `> [!IMPORTANT]`, which maps to the `<Important>` component (`data-admonition="important"`).
- To add or override directives, pass a `directives` map to `zudoDoc({...})` in `zfb.config.ts` — see [Directives Registry](https://zudo-doc.takazudomodular.com/docs/markdown-features/directives-registry#custom-directives) for the full pattern.
- [GitHub Alerts](https://zudo-doc.takazudomodular.com/docs/markdown-features/github-alerts) emits the same admonition markup from `> [!NOTE]`-style blockquotes; the two features coexist cleanly.