Directives Registry

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

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

概要

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

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

ディレクティブの形式

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

アドモニション

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

構文

:::note[任意のタイトル]
コンテンツをここに記述します。
:::

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

出力マークアップ

:::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 でディレクティブ名とコンポーネント名のマッピングを定義し、pages/_mdx-components.ts でコンポーネントの実装を提供します。

ステップ 1 — zfb.config.ts にディレクティブ名 → コンポーネント名のマッピングを追加する:

export default defineConfig({
  markdown: {
    features: {
      directives: {
        // 既存のエントリ...
        callout: "Callout", // :::callout → <Callout>
      },
    },
  },
});

値（"Callout"）は、コンパイル済みの MDX 出力で zfb が出力する JSX タグ名です。コンポーネントマップに登録するキーと一致している必要があります。

ステップ 2 — pages/_mdx-components.ts でコンポーネント名を実装にバインドする:

import { Callout } from "@/components/content/callout";

export function createMdxComponents(lang) {
  return {
    // 既存のエントリ...
    Callout,
  };
}

作者が :::callout と書くと、zfb はコンパイル済みの MDX に <Callout> を出力します。<entry.Content components={createMdxComponents(lang)} /> の呼び出しが、このマップを通じて Callout をコンポーネントに解決します。Rust コードは不要です。

補足

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

• important と caution コンポーネントが登録されていることを確認しない限り、> [!IMPORTANT] や > [!CAUTION] の GitHub アラート構文は使用しないでください。それぞれ data-admonition="important" / data-admonition="caution" にマッピングされ、コンポーネントが存在しない場合は 500 エラーになります。