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

## 概要

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

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

## ディレクティブの形式

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

| 形式 | 構文 | 用途 |
| --- | --- | --- |
| コンテナ | `:::name[label]{attrs}` … `:::` | 複数段落ブロック（アドモニション、コードグループ） |
| リーフ | `::name[label]{attrs}` | 自己クローズ要素 |
| テキスト（インライン） | `:name[label]{attrs}` | インラインコンポーネント |

## アドモニション

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

:::note

これは `:::note` アドモニションです。

:::

:::tip

役立つ提案には `:::tip` を使います。

:::

:::info

補足情報には `:::info` を使います。

:::

:::warning

注意が必要な内容には `:::warning` を使います。

:::

:::danger

重大な警告には `:::danger` を使います。

:::

:::caution

慎重に扱うべきリスクのある手順には `:::caution` を使います。

:::

:::details[クリックして展開]

折り畳み可能なコンテンツには `:::details[ラベル]` を使います。

:::

## 構文

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

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

## 出力マークアップ

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

```html
<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`](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components#%E3%82%B0%E3%83%AD%E3%83%BC%E3%83%90%E3%83%AB%E7%99%BB%E9%8C%B2-mdxextras) を通じてコンポーネントを登録します。

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

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

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

**ステップ 2 — [`mdxExtras`](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components#%E3%82%B0%E3%83%AD%E3%83%BC%E3%83%90%E3%83%AB%E7%99%BB%E9%8C%B2-mdxextras) を通じて `Callout` コンポーネントを登録する。** 作者が `:::callout` と書くと、zfb はコンパイル済みの MDX に `<Callout>` を出力し、グローバル MDX レジストリーがそのコンポーネントに解決します。Rust コードは不要です。

## 補足

- アドモニションディレクティブ（`note`、`tip`、`info`、`warning`、`danger`、`caution`、`details`）は、このプロジェクトが `directives` マップで登録している[アドモニションレシピ](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/admonitions-preset)が提供します。Core レジストリ自体ではありません。レジストリはエンジンであり、`zfb.config.ts` の `directives` マップがディレクティブ名 → コンポーネント名のバインディングを、[`mdxExtras`](https://zudo-doc.takazudomodular.com/ja/docs/guides/custom-components#%E3%82%B0%E3%83%AD%E3%83%BC%E3%83%90%E3%83%AB%E7%99%BB%E9%8C%B2-mdxextras) がカスタムコンポーネントのバインディングを提供します。