Snippets & Variablen

Manche Texte gehören auf viele Seiten: eine Voraussetzung, eine Warnung, die aktuelle Version. Schreib sie einmal, und Clay setzt sie beim Bauen der Seite überall ein, wo sie gebraucht werden. Suche, Linkprüfung und das Markdown für Agenten sehen den fertigen Text.

#Variablen

Leg die Werte in der clay.yaml fest:

variables:
  major: "4"
  node: "22.22.3"

Nutze sie in jeder Seite mit zwei geschweiften Klammern:

npm install --save-dev clay-doc@5

Clay {{major}} braucht Node.js {{node}} oder neuer:

```bash
npm install --save-dev clay-doc@{{major}}
```

• Variablen funktionieren überall in einer Seite: im Text, in Codeblöcken, in Links und im Front Matter.
• Nur Namen aus variables werden eingesetzt. Andere geschweifte Klammern bleiben, wie sie sind, Templates in Codebeispielen sind also sicher.
• Ein Backslash lässt eine Variable stehen: \{{major}} zeigt {{major}}.
• Werte können je Sprache verschieden sein, wie jeder Text in der clay.yaml: product: {en: "Docs", de: "Doku"}.
• Gespeicherte Versionen behalten ihre Werte: clay version setzt die Variablen ein, damit die alte Dokumentation weiter die alte Version nennt.

#Snippets

Leg einen Text, den du mehrfach nutzen willst, in eine Datei, deren Name oder deren Ordnername mit _ beginnt: Solche Dateien sind keine Seiten. Binde ihn mit einem HTML-Kommentar in einer eigenen Zeile ein:

<!--@include: ../_snippets/node-version.de.md-->

> [!NOTE]
> Clay {{major}} braucht **Node.js {{node}}** oder neuer.

• Der Pfad ist relativ zur Seite, wie ein Link. Das Front Matter des Snippets bleibt weg.
• Links und Bilder in einem Snippet sind relativ zur Seite, die es einbindet.
• Snippets können Snippets einbinden, relativ zu sich selbst, und Variablen werden überall eingesetzt.
• Rück das Einbinden ein, und das ganze Snippet wird eingerückt: So funktioniert es auch in Schritten und Listen.
• Auf GitHub ist das Einbinden ein HTML-Kommentar und zeigt nichts.

#Code aus dem Projekt

Einbinden funktioniert auch in Codeblöcken, mit jeder Datei des Projekts. So bleiben Beispiele in der Dokumentation der Code, der wirklich läuft:

```ts
<!--@include: ../../src/client.ts#setup-->
```

Markiere Bereiche in Kommentaren der Sprache der Datei; die Markierungszeilen bleiben weg:

// #region setup
const client = createClient({token: process.env.TOKEN});
// #endregion

Diese Website macht es genauso mit ihren eigenen Einstellungen: Der Block unten ist aus ihrer config/variables.yaml eingebunden, zwischen # #region values und # #endregion, und ändert sich mit ihr.

major: "5"
node: "22.22.3"

```yaml [config/variables.yaml]
<!--@include: ../../../config/variables.yaml#values-->
```

#Prüfungen

Der Build meldet Einbindungen, die er nicht füllen kann, und lässt sie weg:

docs/guides/setup.md: includes "../_snippets/gone.md", which does not exist; it is left out

Genauso bei Dateien außerhalb des Projekts, Bereichen, die es nicht gibt, und Snippets, die zurück zur Seite führen. Mit --strict lassen sie den Build scheitern, siehe Build-Prüfungen.