Includes

Inhalte seitenübergreifend wiederverwenden — füge gemeinsam genutzte Markdown-, MDX- oder Code-Dateien mit der Include-Syntax in jede Seite ein.

Schreibe ein Snippet einmal und füge es in jede beliebige Seite ein. Eine <include>-Anweisung in einer eigenen Zeile bettet zur Build-Zeit eine andere Datei ein, so als wäre deren Inhalt direkt dort geschrieben worden — Überschriften werden Teil des Inhaltsverzeichnisses der Seite, Text wird von der Suche indexiert, und der Inhalt erscheint im .md-Spiegel der Seite sowie in llms-full.txt. Eine Anweisung, die ein Formatter über mehrere Zeilen umbricht, wird trotzdem eingefügt, und eine Anweisung, die Blume nicht parsen kann, löst in ihrer Zeile eine BLUME_INCLUDE_MALFORMED-Warnung aus, statt als rohes Tag gerendert zu werden.

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

Der Pfad wird relativ zur einbindenden Datei aufgelöst. Pfade, die mit / beginnen, werden ab deinem Content-Root aufgelöst, sodass tief verschachtelte Seiten gemeinsame Snippets ohne ../../..-Ketten referenzieren können:

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

Die Syntax entspricht der Include-Syntax von Fumadocs, sodass migrierte Inhalte unverändert funktionieren.

Hier siehst du es live — der folgende Hinweis stammt aus einem gemeinsam genutzten Snippet:

Partials

Jede Datei, deren Name (oder Ordner) mit einem Unterstrich beginnt, ist von Routing, Navigation, Suche und Sitemaps ausgeschlossen — diese Konvention ist der natürliche Ort für gemeinsam genutzte Snippets. Muster, die du zu content.exclude hinzufügst, ergänzen diese Regel, statt sie zu ersetzen; um Dateien mit Unterstrich doch zu veröffentlichen, füge "!**/_*" zu exclude hinzu:

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

Ein Partial ist eine ganz normale Markdown- oder MDX-Datei. Sein Frontmatter wird beim Einfügen entfernt (das Frontmatter der einbindenden Seite gewinnt), und alles andere — Hinweise, Code-Blöcke, Komponenten, Mathematik — wird genau so gerendert wie inline. Partials können andere Partials einbinden; ein zirkulärer Include wird als Fehler gemeldet.

Linkreferenz-Definitionen ([pep 508]: https://peps.python.org/pep-0508/) wirken ebenfalls über Includes hinweg, sodass ein Partial die gemeinsam genutzten Link-Definitionen einer Website enthalten kann: Die Seite und ihre anderen Partials können die Definitionen eines Partials referenzieren ([PEP 508]), und ein Partial kann die der Seite referenzieren. Wenn die Seite und ein Partial beide dasselbe Label definieren, verwendet jede Datei ihre eigene Definition.

Relative Bildreferenzen innerhalb eines Partials funktionieren weiterhin: Sie werden auf die einbindende Seite umgerechnet, sodass ein neben dem Partial liegendes ![diagram](./diagram.png) oder <Card img="./cover.png"> überall aufgelöst wird, wo das Partial eingefügt wird. Der Pfad eines Bildes wird in jeder Schreibweise umgerechnet: in spitzen Klammern (![diagram](<./my diagram.png>)), mit maskierten Klammern oder gefolgt von einem Titel in beliebigen Anführungszeichen. Ein Link auf eine andere Datei neben dem Partial ([spec](./spec.pdf) oder ein <img src> bzw. <a href>, das auf eine solche Datei verweist) wandert ebenfalls mit. Ein Link auf eine Seite wird von der einbindenden Seite aus aufgelöst, so als wäre er dort geschrieben worden.

Wenn du ein Partial bearbeitest, während blume dev läuft, wird jede Seite neu geladen, die es einbindet.

Props

Übergib Werte als Attribute an ein Partial und lies sie im Partial mit {{name}} aus, also mit derselben Syntax wie bei Variablen. So bedient ein einziges Partial jede Seite, die eine Variante davon braucht:

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

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

Ein Prop gilt für die eingebundene Datei und für alles, was diese wiederum einbindet, und hat Vorrang vor einer websiteweiten Variable mit demselben Namen. Jedes Attribut außer lang und meta ist ein Prop; Attributnamen werden kleingeschrieben, und Werte sind reiner Text in Anführungszeichen. Props wirken nur in Markdown- und MDX-Partials: Ein {{name}} in einer eingebundenen Code-Datei wird nicht durch ein Prop ersetzt.

Code-Dateien einbinden

Ein Ziel, das nicht .md/.mdx ist, wird als umschlossener Code-Block eingebettet, wobei die Sprache aus der Dateiendung abgeleitet wird. Verwende lang, um die Sprache zu überschreiben (oder um eine Markdown-Datei als Quelltext anzuzeigen, statt sie einzufügen), und meta, um einen Fence-Meta-String wie einen Titel zu übergeben:

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

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

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

Regeln und Diagnosen

Include-Anweisungen müssen in einer eigenen Zeile stehen — sie sind block-level, nicht inline. Anweisungen innerhalb von umschlossenen Code-Blöcken bleiben unangetastet, sodass du die Syntax selbst dokumentieren kannst (so wie diese Seite es tut).

Ziele müssen innerhalb deines Content-Roots liegen: Eine Datei außerhalb davon würde in Versions-Snapshots und ausgeworfenen Projekten stillschweigend fehlen, deshalb meldet blume BLUME_INCLUDE_OUTSIDE_ROOT, statt sie einzufügen. Ein nicht existierendes Ziel ergibt BLUME_INCLUDE_NOT_FOUND, und eine Schleife von Includes ergibt BLUME_INCLUDE_CYCLE — alle drei lassen blume build fehlschlagen (übergib --no-strict, um trotzdem zu bauen) und tauchen in blume validate auf.

Defekte Links innerhalb eines Partials werden der Partial-Datei zugeordnet, nicht den Seiten, die sie einfügen — so behebst du sie dort, wo sie leben.

Ein Partial wird im Format der einbindenden Seite gelesen, sodass ein .md-Partial, das von einer .mdx-Seite eingebunden wird, als MDX gelesen wird. MDX kennt keine HTML-Kommentare, deshalb werden die -Kommentare des Partials als MDX-Kommentare ({/* … */}) eingefügt und bleiben verborgen. Anderes HTML darin muss gültiges JSX sein: Ein <img …> oder <br> ohne schließenden Schrägstrich verschluckt alles, was im Partial danach folgt, ohne Fehlermeldung. Blume warnt davor mit BLUME_MDX_UNCLOSED_ELEMENT in der Zeile des Partials; schließe das Tag als <br />. Alles andere im Partial, das MDX nach dem Einfügen nicht parsen kann, etwa eine verirrte {, ergibt eine BLUME_MDX_SYNTAX-Warnung in der Zeile des Partials, und wenn es den Build fehlschlagen lässt, meldet auch der Build es dort, nicht bei der Seite, die das Partial einbindet.