Directives Registry

:::name ディレクティブ構文を JSX コンポーネントにマッピングするパースプリミティブ。

Core 機能 — 常に有効です。設定は不要です。

概要

Directives Registry は、markdown における :::name（および ::name / :name）ディレクティブ構文を可能にする基盤プリミティブです。コンパイル時にディレクティブ構文を JSX コンポーネント呼び出しに変換し、組み込み機能とカスタムプロジェクトコンポーネントの両方がディレクティブブロックに応答できるようにします。

このレジストリがなければ、アドモニションを含むディレクティブベースの機能はすべてパースされません。

ディレクティブの形式

3 つの形式に対応しています。

アドモニション

レジストリの最も一般的な使用方法はアドモニションディレクティブです。このプロジェクトは directives マップ（レシピ）でアドモニションのボキャブラリを登録しているため、以下のコンテナディレクティブが使えます。

構文

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

角括弧内のラベルは省略可能です。ラベルを省略すると、デフォルトのタイプ名がタイトルとしてレンダリングされます。

出力マークアップ

:::note ディレクティブは以下のようにレンダリングされます。

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

data-admonition 属性はバリアント名を保持します。タイプ固有のクラス（admonition-note、admonition-tip など）はスタイリングに使用されます。

カスタムディレクティブ

カスタムディレクティブの登録には 2 つのステップが必要です。zfb.config.ts でディレクティブ名とコンポーネント名のマッピングを定義し、mdxExtras を通じてコンポーネントを登録します。

ステップ 1 — 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>
    },
  }),
);

値（"Callout"）は、コンパイル済みの MDX 出力で zfb が出力する JSX タグ名です。mdxExtras を通じて登録するキーと一致している必要があります。

directives はディレクティブマップ全体を置き換えます。エントリの追加または上書きでは、必ず先に defaultDirectiveVocabulary をスプレッドしてください。スプレッドを省くと、組み込みの 7 つのディレクティブ（note、tip、info、warning、danger、caution、details）がすべてなくなります。

ステップ 2 — mdxExtras を通じて Callout コンポーネントを登録する。 作者が :::callout と書くと、zfb はコンパイル済みの MDX に <Callout> を出力し、グローバル MDX レジストリーがそのコンポーネントに解決します。Rust コードは不要です。

補足

• アドモニションディレクティブ（note、tip、info、warning、danger、caution、details）は、このプロジェクトが directives マップで登録しているアドモニションレシピが提供します。Core レジストリ自体ではありません。レジストリはエンジンであり、zfb.config.ts の directives マップがディレクティブ名 → コンポーネント名のバインディングを、mdxExtras がカスタムコンポーネントのバインディングを提供します。