トランスクルージョン

:::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 パーサーがインラインコンテンツではなくブロックディレクティブとして扱えるよう、前後のコンテンツと空行で区切る必要があります。

取り込まれたファイルにおける GFM 構文

取り込まれたファイルは、取り込み元プロジェクトの markdown.gfm 設定でパースされます。つまり、取り込むページ自身が使うのと同じ構文セットです。テーブル、打ち消し線、タスクリスト、脚注、オートリンクリテラルは、マークアップがインラインで書かれていても取り込まれたファイルの中にあっても、同じように動作します。

<!-- snippet.md -->
| a | b |
| - | - |
| 1 | 2 |

markdown.gfm.table が有効なら、これは取り込まれたときにテーブルとしてレンダリングされます。同じ 3 行をページに直接貼り付けた場合とまったく同じです。

zfb #2390 より前は、設定にかかわらず取り込まれたファイルが常にすべての GFM 構文を無効にしてパースされていました。そのため上記のスニペットは、ページ内の同一のマークアップがテーブルになる一方で、リテラルテキストとしてレンダリングされていました。この挙動に依存したコンテンツがある場合は、該当する markdown.gfm.* フラグを無効にしてください。

数式（$$…$$ と $…$ ）も zfb #2397 以降は同じルールに従います。取り込まれたファイルは、それを囲むページがどちらの経路向けにコンパイルされているかに合わせてパースされます。MDX/JSX 経路では数式がパースされるため、取り込まれたファイル内の数式はインラインで書いた場合とまったく同じようにレンダリングされます。HTML 経路では数式は無効のままです。トップレベルと同様に、そこでは $$…$$ はリテラルテキストになります。

#2397 より前は、両方の経路で数式が無効でした。MDX/JSX 経路では、これは見た目だけの問題ではありませんでした。LaTeX が裸の {…} 式コンテナとして漏れ出し、バンドラーがこれを拒否した結果、ページ全体が生コンテンツのフォールバック表示になっていました。取り込まれるファイル内の数式は、現在は安全に使用できます。

構文の一覧とデフォルト値については GFM を参照してください。