ディレクティブ

Opt-in

作成 2026年6月24日Takeshi Takatsudo

:::name / ::name / :name のディレクティブ構文を独自の JSX コンポーネントにマッピングして登録する。デフォルトでは何も登録されていない — 語彙はあなたが用意する。

directives 機能は、zfb.config.ts からコアのディレクティブレジストリに登録を行います。CommonMark Directives 構文 — コンテナ（:::name）、リーフ（::name）、テキスト（:name） — を、コンパイル済み MDX の JSX コンポーネント呼び出しにマッピングします。

デフォルトでは、ディレクティブ名は一つも登録されていません。 語彙はあなたが選び、zfb が JSX を出力します。

有効化

zfb.config.ts

import { defineConfig } from "zfb/config";

export default defineConfig({
  markdown: {
    features: {
      directives: {
        note: "Note",
        tip: "Tip",
        warning: "Warning",
      },
    },
  },
});

値は「ディレクティブ名 → コンポーネント」のマップです。各エントリは短縮形の文字列でも、完全形の DirectiveSpec オブジェクト（後述）でも構いません。

短縮形 — コンポーネント名のみ

最も単純なエントリは、ディレクティブ名をコンポーネント識別子の文字列にマッピングするものです。このディレクティブは titleFromLabel: true の コンテナ として登録され、角括弧で囲んだ [label] が、出力される JSX 要素の title="…" 属性になります。

zfb.config.ts

export default defineConfig({
  markdown: {
    features: {
      directives: {
        callout: "Callout",
      },
    },
  },
});

著者が次のように書くと:

:::callout[Heads up]

Body text.

:::

パイプラインは次を出力します:

<Callout title="Heads up">
  <p>Body text.</p>
</Callout>

完全形 — `DirectiveSpec` オブジェクト

完全形を使うと、ディレクティブの形状（container、leaf、text）と、角括弧のラベルを title 属性にするかどうかを制御できます。

zfb.config.ts

export default defineConfig({
  markdown: {
    features: {
      directives: {
        // container (default kind), titleFromLabel on
        note: "Note",

        // leaf directive — self-closing, no body
        youtube: {
          component: "Youtube",
          kind: "leaf",
          titleFromLabel: true,
        },

        // text (inline) directive
        kbd: {
          component: "Kbd",
          kind: "text",
          titleFromLabel: false,
        },
      },
    },
  },
});

DirectiveSpec のフィールド:

フィールド	型	必須	デフォルト
`component`	`string`	Yes	—
`kind`	`"container" \| "leaf" \| "text"`	No	`"container"`
`titleFromLabel`	`boolean`	No	`true`