インクルード

ページ間でコンテンツを再利用 — 共有の Markdown、MDX、コードファイルを include 構文で任意のページに差し込みます。

スニペットを一度書けば、任意のページに差し込めます。単独の行に置いた <include> 文は、ビルド時に別のファイルを埋め込み、その内容がインラインで書かれていたかのように扱われます — 見出しはページの目次に加わり、テキストは検索でインデックスされ、内容はページの .md ミラーおよび llms-full.txt にも現れます。フォーマッターによって複数行に折り返された文も正しく差し込まれます。Blume が解析できない文は、生のタグとしてレンダリングされる代わりに、その行で BLUME_INCLUDE_MALFORMED 警告を発生させます。

<include>./_snippets/prerequisites.mdx</include>

パスはインクルード元のファイルからの相対で解決されます。/ で始まるパスはコンテンツルートから解決されるため、深くネストしたページでも ../../.. の連なりなしに共有スニペットを参照できます。

<include>/_snippets/prerequisites.mdx</include>

この構文は Fumadocs の include 構文と一致しているため、移行したコンテンツはそのまま動作します。

こちらが実際の動作です — 次のコールアウトは共有スニペットから差し込まれたものです。

パーシャル

名前（またはフォルダー名）がアンダースコアで始まるファイルは、ルーティング、ナビゲーション、検索、サイトマップから除外されます。この慣習は共有スニペットの置き場所として最適です。content.exclude に追加したパターンは、このルールを置き換えるのではなく、このルールに追加されます。それでもアンダースコアで始まるファイルを公開したい場合は、exclude に "!**/_*" を追加してください。

docs/
  _snippets/
    prerequisites.mdx
    cli-flags.md
  guides/
    quickstart.mdx   ← <include>../_snippets/prerequisites.mdx</include>
  index.mdx

パーシャルは通常の Markdown または MDX ファイルです。差し込み時にフロントマターは取り除かれ（インクルード元ページのフロントマターが優先されます）、それ以外のすべて — コールアウト、コードフェンス、コンポーネント、数式 — はインラインで書いた場合とまったく同じようにレンダリングされます。パーシャルは他のパーシャルをインクルードできます。循環インクルードはエラーとして報告されます。

リンク参照定義（[pep 508]: https://peps.python.org/pep-0508/）もインクルードをまたいで機能するため、パーシャルにサイト共通のリンク定義をまとめておけます。ページとその他のパーシャルはパーシャルの定義を参照でき（[PEP 508]）、パーシャルはページの定義を参照できます。ページとパーシャルの両方が同じラベルを定義している場合は、それぞれが自身の定義を使用します。

パーシャル内の相対画像参照はそのまま機能します。インクルード元のページを基準に再解決されるため、パーシャルの隣に配置した ![diagram](./diagram.png) や <Card img="./cover.png"> は、そのパーシャルがどこに差し込まれても正しく解決されます。画像のパスは、どのような形式で書かれていても再解決されます。山括弧で囲んだ形式（![diagram](<./my diagram.png>)）、括弧をエスケープした形式、いずれかの引用符で囲んだタイトルが続く形式のいずれにも対応します。パーシャルの隣にある別のファイルへのリンク（[spec](./spec.pdf)、またはそうしたファイルを指す <img src> や <a href>）も、同様にパーシャルに合わせて再解決されます。ページへのリンクは、インクルード元のページに書かれていたかのように、そのページを基準に解決されます。

blume dev の実行中にパーシャルを編集すると、それをインクルードしているすべてのページがリロードされます。

プロップ

値を属性としてパーシャルに渡し、パーシャル内では変数と同じ構文である {{name}} で読み取ります。これにより、1 つのパーシャルで、そのバリエーションを必要とするすべてのページに対応できます。

Upgrade to the **{{plan}}** plan to use {{feature}}.

<include plan="Enterprise" feature="SSO">
  ./_snippets/upgrade.mdx
</include>

プロップはインクルードされたファイルと、そのファイルがさらにインクルードするすべてのものに適用され、同じ名前のサイト全体の変数よりも優先されます。lang と meta 以外のすべての属性がプロップになります。属性名は小文字で、値は引用符で囲んだプレーンテキストです。プロップが渡されるのは Markdown と MDX のパーシャルのみです。インクルードされたコードファイル内の {{name}} はプロップで置き換えられません。

コードファイルのインクルード

.md/.mdx 以外のターゲットは、拡張子から推論された言語でフェンス付きコードブロックとして埋め込まれます。言語を上書きするには（または Markdown ファイルを差し込む代わりにソースとして表示するには）lang を使い、タイトルなどのフェンスのメタ文字列を渡すには meta を使います。

<include>./examples/config.ts</include>

<include meta='title="config.ts"'>./examples/config.ts</include>

<include lang="mdx">./_snippets/prerequisites.mdx</include>

ルールと診断

include 文は単独の行を占める必要があります — インラインではなくブロックレベルの要素だからです。フェンス付きコードブロック内の文はそのまま残されるため、（このページのように）構文そのものをドキュメント化できます。

ターゲットはコンテンツルート内に存在しなければなりません。ルート外のファイルはバージョンスナップショットや eject したプロジェクトから黙って欠落してしまうため、blume は差し込む代わりに BLUME_INCLUDE_OUTSIDE_ROOT を報告します。存在しないターゲットは BLUME_INCLUDE_NOT_FOUND、インクルードのループは BLUME_INCLUDE_CYCLE となります。これら 3 つはいずれも blume build を失敗させ（それでもビルドするには --no-strict を渡します）、blume validate にも表示されます。

パーシャル内のリンク切れは、それを差し込んでいるページではなくパーシャルのファイルに対して報告されるため、実体のある場所で修正できます。

パーシャルはインクルード元ページの形式で読み込まれるため、.mdx ページがインクルードする .md パーシャルは MDX として読み込まれます。MDX には HTML コメントがないため、パーシャル内の  コメントは MDX コメント（{/* … */}）として差し込まれ、非表示のまま保たれます。それ以外の HTML は有効な JSX である必要があります。閉じスラッシュのない <img …> や <br> は、パーシャル内でその後に続くすべての内容を取り込んでしまい、エラーも発生しません。Blume はこれをパーシャルの該当行で BLUME_MDX_UNCLOSED_ELEMENT として警告します。<br /> のように閉じてください。パーシャル内のその他の内容で、差し込み後に MDX が解析できないもの（余分な { など）は、パーシャルの該当行で BLUME_MDX_SYNTAX 警告となります。それがビルドを失敗させる場合も、ビルドはインクルード元のページではなくパーシャルの該当行でエラーを報告します。