**Core feature** — always active, no configuration required.

## What it does

The Directives Registry is the underlying primitive that enables the `:::name` (and `::name` / `:name`) directive syntax in markdown. During compilation it translates directive syntax into JSX component calls, making it possible for both built-in features and custom project components to respond to directive blocks.

Without this registry, none of the directive-based features — including admonitions — would parse.

## Directive shapes

Three shapes are supported:

| Shape | Syntax | Use case |
| --- | --- | --- |
| Container | `:::name[label]{attrs}` … `:::` | Multi-paragraph blocks (admonitions, code groups) |
| Leaf | `::name[label]{attrs}` | Self-closing elements |
| Text (inline) | `:name[label]{attrs}` | Inline components |

## Admonitions

The most common use of the registry is the admonition directives. This project registers the admonition vocabulary via the `directives` map (the recipe), so the following container directives are available:

:::note

This is a `:::note` admonition.

:::

:::tip

Use `:::tip` for helpful suggestions.

:::

:::info

Use `:::info` for supplemental information.

:::

:::warning

Use `:::warning` for cautions that need attention.

:::

:::danger

Use `:::danger` for critical warnings.

:::

:::caution

Use `:::caution` for risky steps that need extra care.

:::

:::details[Click to expand]

Use `:::details[label]` for collapsible content.

:::

## Syntax

```md
:::note[Optional title]
Content goes here.
:::
```

The label in brackets is optional. Without a label the admonition renders with its default type name as the title.

## Emitted markup

A `:::note` directive renders as:

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

The `data-admonition` attribute carries the variant name. The type-specific class (`admonition-note`, `admonition-tip`, etc.) is used for styling.

## Custom directives

Registering a custom directive requires two steps: mapping the directive name in `zfb.config.ts`, then registering the component through [`mdxExtras`](https://zudo-doc.takazudomodular.com/docs/guides/custom-components#global-registration-mdxextras).

**Step 1 — Add the directive name → component name mapping in `zfb.config.ts`:**

```ts title="zfb.config.ts"
import { defineConfig } from "zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";
import { defaultDirectiveVocabulary } from "@takazudo/zudo-doc/directive-vocabulary-defaults";

export default defineConfig(
  zudoDoc({
    directives: {
      ...defaultDirectiveVocabulary,
      callout: "Callout", // :::callout → <Callout>
    },
  }),
);
```

The value (`"Callout"`) is the JSX tag name zfb emits in the compiled MDX output. It must match the key you register through `mdxExtras`.

`directives` replaces the whole directive map. Always spread `defaultDirectiveVocabulary` before adding or overriding entries: omitting the spread removes all seven built-in directives (`note`, `tip`, `info`, `warning`, `danger`, `caution`, and `details`).

**Step 2 — Register your `Callout` component through [`mdxExtras`](https://zudo-doc.takazudomodular.com/docs/guides/custom-components#global-registration-mdxextras).** When an author writes `:::callout`, zfb emits `<Callout>` in the compiled MDX and the global MDX registry resolves it to your component. No Rust code is needed.

## Notes

- The admonition directives (`note`, `tip`, `info`, `warning`, `danger`, `caution`, `details`) are provided by the [admonitions recipe](https://zudo-doc.takazudomodular.com/docs/markdown-features/admonitions-preset) this project registers via the `directives` map — not by the Core registry itself. The registry is the engine; the `directives` map in `zfb.config.ts` supplies the directive-name → component-name bindings, and [`mdxExtras`](https://zudo-doc.takazudomodular.com/docs/guides/custom-components#global-registration-mdxextras) supplies custom component bindings.