# スニペットとインクルード 多くのページに載せたい文章があります: インストール時の警告、前提条件のブロック、 サポートのお知らせ。**スニペット**として一度だけ書き、必要な場所でインクルード してください — 変更すれば、次のビルドですべてのページが新しいテキストになります。 ## スニペットを書く スニペットはただの Markdown ファイルです。慣習として `_snippets/` に置きます — `_` で始まるフォルダはすでにページとナビゲーションから除外されるので、スニペットが ページになることはありません: ``` content/ _snippets/ requirements.md guides/ install.md ``` ```markdown :::note Ovellum には **Node 20+** が必要です。`node --version` で確認してください。 ::: ``` スニペットではページで使えるすべて — [コンポーネントディレクティブ](/ja/docs/guides/components/)、 コードブロック、画像 — が使えます。レンダリングの*前*に継ぎ足されるため、 インクルードされたコンテンツはページ自身の Markdown と同じパイプライン （同じ HTML サニタイザー）を通ります。 ## インクルードする `::include` ディレクティブを使います（コロンは **2 つ** — 単独の行に書くリーフ ディレクティブです）: ```markdown # インストール ::include[/_snippets/requirements.md] 次にインストーラーを実行… ``` - **ルート絶対**パス（`/_snippets/…`）はコンテンツルートから解決されます — [アセット参照](/ja/docs/guides/assets/)と同じ慣習です。 - **相対**パス（`::include[warning.md]`）はインクルードするファイルのフォルダ から解決されます。 - 属性形式 `::include{file="/_snippets/requirements.md"}` も同等です。 スニペットは他のスニペットをインクルードできます（ネストは問題ありません。循環 インクルードは検出され、警告とともにスキップされます）。スニペット自身の フロントマターはスニペットに関するメタデータです — 取り除かれ、ページにマージ されることはありません。スニペット内の見出しは、他の見出しと同じようにページの 目次に加わります。 ## 複数言語との併用 [i18n](/ja/docs/guides/i18n/) サイトでは、インクルードはまず**現在のロケールの ツリー**で解決され、次に**デフォルトロケール**のツリーにフォールバックします。 つまり `content//` の下に同じパスを作ればスニペットを翻訳でき、まだ翻訳 していないロケールは穴ではなくデフォルトロケール版をレンダリングします。 ## 何かが間違っているとき ターゲットの欠落、循環インクルード、コンテンツディレクトリから逃れようとする パスがビルドを壊すことはなく、生のマークアップが漏れることもありません: ディレクティブは省かれ、ビルドがファイルと行を名指しする警告を報告します。 `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 ミラー](/ja/docs/reference/config/#ai)には 展開されずそのまま現れます。 - **インクルードはコンテンツディレクトリの内側に留まります** — `..` での脱出も、 絶対ファイルシステムパスも不可。ほかのすべてと同じ封じ込めルールです。