Directives registry

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

DirectiveRegistry is the Core primitive that maps CommonMark Directives syntax — container (:::name), leaf (::name[label]), and text (:name[label]) — to JSX component calls in the compiled output.

It is always active. You interact with it in two ways:

• From config — use the opt-in directives feature to register directive names without writing Rust.

• From Rust — populate a DirectiveRegistry directly and insert it into the pipeline. See Custom Directives.

Directive shapes

The registry handles three directive shapes:

• Container — :::name[label] … ::: wraps multi-paragraph body content into a JSX component.

• Leaf — ::name[label]{attrs} produces a self-closing component with no children.

• Text — :name[label]{attrs} is an inline component.

Zero defaults

The registry ships with no directive names pre-registered. Every :::name you use must be explicitly registered — either via the directives feature in zfb.config.ts or by populating the registry in Rust. An unrecognised directive name emits a warning diagnostic and leaves the source paragraph unchanged.

Typed attribute schemas (from #584)

The registry accepts typed attribute schemas for each registered directive. Unknown attributes emit a build-time warning (the attr still passes through unchanged). Type-coercion failures (e.g. a non-boolean value for a Boolean attr) emit hard errors. The schema is declared alongside the register call:

registry.register(
    DirectiveDef::text("badge", "Badge")
        .with_attrs(vec![
            AttrSchema { name: "tone".into(), ty: AttrType::String, default: None, required: false },
        ]),
);

Custom directives

To register additional directives or override built-ins, see Custom Directives — the author-facing path that does not require writing Rust.

See also

• directives feature — opt-in config feature that populates the registry from zfb.config.ts.

• Custom Directives — register new :::name / ::name / :name directive names via the Rust API.

• Extending the Markdown Pipeline — engine-side extension surface.