トランスクルージョン

Opt-in

作成 2026年6月24日Takeshi Takatsudo

:::include ディレクティブを使って別ファイルの内容をインライン展開する。

transclude 機能を使うと、:::include ディレクティブで別ファイルのコンテンツをインライン展開できます。参照されたファイルは Markdown としてパースされ、その AST は、他のすべての処理が走る前に、取り込み側のドキュメントへマージされます。

有効化

// zfb.config.ts
export default defineConfig({
  markdown: {
    features: {
      transclude: {},
    },
  },
});

オプション設定:

transclude: {
  maxDepth: 5, // include チェーンの最大深さ（デフォルト 5）
},

インライン展開したいファイルを指す file 属性を付けて :::include を使います。パスは 現在のソースファイル からの相対で解決されます。

# My Document

:::include{file="./snippets/intro.md"}

More content follows.

取り込まれたファイルはディレクティブの位置に挿入されるため、その見出し・段落・コードブロックなどの要素が、出力中にそのまま現れます。

code=true を設定すると、ファイルの内容をパース済みの Markdown ではなくコードブロックとして扱います。lang 属性でシンタックスハイライトの言語を指定します。

:::include{file="./examples/hello.rs" code=true lang="rust"}

lines 属性は、取り込み前にファイルを指定した行に切り出します。code=true と併用して、ソースファイルの特定の抜粋を表示します。

:::include{file="./src/lib.rs" code=true lang="rust" lines="10-30"}

行番号は 1 始まりで、両端を含みます。

取り込まれたファイル自体が :::include ディレクティブを含むこともできます。デフォルトの maxDepth 5 では、最大 5 階層までのチェーンが許可されます。それより深いチェーンはエラー診断とともに拒否されます。

ファイル A がファイル B を取り込み、ファイル B がファイル A を取り込む場合（直接的または推移的に）、ビルドは無限ループに陥る代わりに、Error 診断を出力して該当のディレクティブをスキップします。

相対パスのみ — 絶対パスはエラー診断とともに拒否されます。
プロジェクトルートへの閉じ込め — 解決後のパスはプロジェクトルート内に収まっていなければなりません。パストラバーサル（例: ../../outside）は拒否されます。

:::include のフェンス行は、Markdown パーサーがインラインコンテンツではなくブロックディレクティブとして扱えるよう、前後のコンテンツと空行で区切る必要があります。