zfb は汎用的なメカニズム（エンジン）として `directives` レジストリを提供します。このプロジェクトはアドモニションのボキャブラリ — `note`、`tip`、`warning`、`danger`、`info`、`caution`、`details` — をレシピとして登録し、コールアウトブロックに CommonMark Directives の `:::` フェンス構文を使えるようにします。 :::note[標準プリセットに含まれます] `zudoDoc()` はこのアドモニションボキャブラリをデフォルトで有効にします — `directives` フィールドは標準の 7 種類（`@takazudo/zudo-doc/directive-vocabulary-defaults`）をデフォルト値として持ちます。個別の設定は不要です。 ```ts title="zfb.config.ts" import { defineConfig } from "zfb/config"; import { zudoDoc } from "@takazudo/zudo-doc/config"; export default defineConfig( zudoDoc({ siteName: "My Docs", }), ); ``` `defineConfig({ markdown: { features: { directives: {...} } } })` を直接書くと、プリセットの残り（githubAlerts、codeTabs、ruby など）が失われます。`directives` マップを上書きする場合でも `zudoDoc({...})` を使ってください。エントリの追加・上書き方法は [Directives Registry](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/directives-registry#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%86%E3%82%A3%E3%83%96) を参照してください。 ::: ## 構文 `:::` フェンスで内容を囲みます。各フェンス行（開始の `:::note` と終了の `:::`）は、前後の内容との間に**必ず空行を入れる**必要があります。空行がないとパースに失敗し、ビルド時に警告が出ます。 ```md :::note 本文をここに書きます。 ::: ``` タイプの後に角括弧でラベルを付けると、アドモニションのタイトルになります。 ```md :::tip[任意のタイトル] 本文。 ::: ``` ## ライブデモ 以下の 7 つのディレクティブは、このアドモニションレシピによってライブで描画されています。 :::note これは **note** です。中立的な補足情報に使います。 ::: :::tip これは **tip** です。役立つアドバイスやショートカットに使います。 ::: :::info これは **info** コールアウトです。文脈的な背景情報に使います。 ::: :::warning これは **warning** です。読者が注意すべき事柄に使います。 ::: :::danger これは **danger** コールアウトです。破壊的・不可逆な操作に使います。 ::: :::caution これは **caution** コールアウトです。慎重に扱うべきリスクのある手順に使います。 ::: :::details[クリックで展開] これは **details** ブロック — 折りたたみ可能な開閉領域です。本文は読者が展開するまで非表示のままです。 ::: ## 出力されるマークアップ 各ディレクティブは JSX 要素（例: ``）にコンパイルされ、zudo-doc は次のように描画します。 ```html

…

…
``` タイプクラス（`admonition-note`、`admonition-tip`、`admonition-warning`、`admonition-danger`、`admonition-info`、`admonition-caution`）と対応する `data-admonition` 属性により、スタイルシートは各バリアントを個別に色分けできます。 ## メモ - `:::details` タイプはレガシーな `:::details title="Click me"` 属性形式も受け付けます。 - `:::caution` はこのプロジェクトが登録するボキャブラリの一部です。`:::warning` が `` を出力するのと同様に、``（`data-admonition="caution"`）を出力します。また `caution` は [GitHub Alerts](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/github-alerts) の `> [!CAUTION]` からも使用できるため、両方のパスで利用可能です。 - `important` は `directives` マップに含まれておらず、`:::important` としては使用できません。[GitHub Alerts](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/github-alerts) の `> [!IMPORTANT]` を通じてのみ利用でき、`` コンポーネント（`data-admonition="important"`）にマッピングされます。 - ディレクティブを追加・上書きするには、`zfb.config.ts` の `zudoDoc({...})` に `directives` マップを渡します。完全なパターンは [Directives Registry](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/directives-registry#%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%86%E3%82%A3%E3%83%96) を参照してください。 - [GitHub Alerts](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/github-alerts) は `> [!NOTE]` 形式のブロック引用から同じアドモニションマークアップを出力します。両機能はクリーンに共存します。