スニペットとインクルード#

多くのページに載せたい文章があります: インストール時の警告、前提条件のブロック、サポートのお知らせ。スニペットとして一度だけ書き、必要な場所でインクルードしてください — 変更すれば、次のビルドですべてのページが新しいテキストになります。

スニペットを書く#

スニペットはただの Markdown ファイルです。慣習として _snippets/ に置きます — _ で始まるフォルダはすでにページとナビゲーションから除外されるので、スニペットがページになることはありません:

content/
  _snippets/
    requirements.md
  guides/
    install.md

<!-- content/_snippets/requirements.md -->
:::note
Ovellum には **Node 20+** が必要です。`node --version` で確認してください。
:::

スニペットではページで使えるすべて — コンポーネントディレクティブ、コードブロック、画像 — が使えます。レンダリングの前に継ぎ足されるため、インクルードされたコンテンツはページ自身の Markdown と同じパイプライン（同じ HTML サニタイザー）を通ります。

インクルードする#

::include ディレクティブを使います（コロンは 2 つ — 単独の行に書くリーフディレクティブです）:

# インストール

::include[/_snippets/requirements.md]

次にインストーラーを実行…

ルート絶対パス（/_snippets/…）はコンテンツルートから解決されます — アセット参照と同じ慣習です。
相対パス（::include[warning.md]）はインクルードするファイルのフォルダから解決されます。
属性形式 ::include{file="/_snippets/requirements.md"} も同等です。

スニペットは他のスニペットをインクルードできます（ネストは問題ありません。循環インクルードは検出され、警告とともにスキップされます）。スニペット自身のフロントマターはスニペットに関するメタデータです — 取り除かれ、ページにマージされることはありません。スニペット内の見出しは、他の見出しと同じようにページの目次に加わります。

複数言語との併用#

i18n サイトでは、インクルードはまず現在のロケールのツリーで解決され、次にデフォルトロケールのツリーにフォールバックします。つまり content/<code>/ の下に同じパスを作ればスニペットを翻訳でき、まだ翻訳していないロケールは穴ではなくデフォルトロケール版をレンダリングします。

何かが間違っているとき#

ターゲットの欠落、循環インクルード、コンテンツディレクトリから逃れようとするパスがビルドを壊すことはなく、生のマークアップが漏れることもありません: ディレクティブは省かれ、ビルドがファイルと行を名指しする警告を報告します。

ovellum check もすべてのインクルードターゲットを検証します — 壊れたインクルードは通常の問題（終了 1）なので、読者より先に CI が捕まえます:

ovellum check complete in 12ms
  ...
  broken includes: 1
  details:
    guides/install.md:5  broken include /_snippets/requirments.md — file not found

境界（設計上のもの）#

manual モードのみ — インクルードはサイトビルダーの機能です。auto/hybrid の生成 Markdown はソースから生成されるもので、スニペットから合成されません。
.md ミラーは書かれたままのソースを見せます — コンポーネントディレクティブと同じく、::include の行はページの AI ミラーには展開されずそのまま現れます。
インクルードはコンテンツディレクトリの内側に留まります — .. での脱出も、絶対ファイルシステムパスも不可。ほかのすべてと同じ封じ込めルールです。