Directives Registry

The parsing primitive that maps :::name directive syntax to JSX components.

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:

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:

Syntax

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

<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.

Step 1 — Add the directive name → component name mapping in 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. 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 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 supplies custom component bindings.