clay.yaml

Die clay.yaml liegt im Projektordner und konfiguriert die ganze Seite. Nur title ist Pflicht; alles andere hat einen sinnvollen Standardwert.

#Beispiele

title: "Mein Projekt"

title: "Mein Projekt"
baseURL: "/mein-projekt/"
siteURL: "https://meine-org.github.io"
editURL: "https://github.com/meine-org/mein-projekt/edit/main/docs/"

title: "Mein Projekt"
favicon: "logo.svg"
baseURL: "/mein-projekt/"
siteURL: "https://meine-org.github.io"
editURL: "https://github.com/meine-org/mein-projekt/edit/main/docs/"
fontawesomeKit: "abc123def4"
version: "3.2"
languages: ["de", "en"]

navbar:
  logo: "logo.svg"
  source:
    name: "GitHub"
    icon: "fa-brands fa-github"
    link: "https://github.com/meine-org/mein-projekt"
  links:
    - name: "Website"
      icon: "fa-solid fa-house"
      link: "https://example.com"
    - name: "Changelog"
      icon: "fa-solid fa-list"
      link: "https://github.com/meine-org/mein-projekt/releases"

messages:
  de:
    search: "Durchsuchen"

variables:
  major: "4"

head:
  meta:
    - name: "google-site-verification"
      content: "abc123"

#Seite

#baseURL und siteURL

Zusammen ergeben sie die vollständige Adresse der Seite. Für https://meine-org.github.io/mein-projekt/:

siteURL: "https://meine-org.github.io"
baseURL: "/mein-projekt/"

baseURL brauchst du immer dann, wenn die Seite nicht an der Wurzel ihrer Domain liegt; Links, Bilder und alle weiteren Dateien hängen davon ab. siteURL ist nur der Ursprung: Ein Pfad darin wird ignoriert, der Pfad kommt immer aus baseURL. Was siteURL ermöglicht, steht unter SEO.

#editURL

Mit editURL zeigt jede Seite einen Link Diese Seite bearbeiten. Lass ihn auf den docs/-Ordner deines Repositorys zeigen; Clay hängt die Datei der Seite an:

editURL: "https://github.com/meine-org/mein-projekt/edit/main/docs/"

Die Seite docs/guides/setup.md verlinkt dann auf …/edit/main/docs/guides/setup.md. Das funktioniert mit GitHub, GitLab, Gitea und jedem Hoster mit ähnlichem URL-Schema. Mit Versionen verlinken Seiten in den Ordner ihrer Version, docs/latest/ oder docs/<name>/, solange die URL auf docs/ endet.

#Navigationsleiste

Logo und Favicon können Dateien im Projektordner sein (Clay kopiert sie in die Seite) oder vollständige URLs.

#Variablen

variables legt Werte fest, die Seiten mit \{{name}} einsetzen, etwa die aktuelle Version. Siehe Snippets & Variablen.

variables:
  major: "4"
  node: "20.19"

#Generate

generate führt vor jedem Build Befehle aus, die Seiten in docs/ schreiben, etwa eine API-Referenz aus deinem Code. Siehe generierte Dokumentation.

generate:
  - npx typedoc --plugin typedoc-plugin-markdown --entryFileName index --out docs/api src/index.ts

#Head

head fügt jeder Seite Tags im <head> hinzu: das Skript eines Chat-Widgets, eine Bestätigung für die Google Search Console, eine Schrift. Jeder Eintrag sind die Attribute des Tags; den Code eines Skripts nimmt code auf.

head:
  script:
    - src: "https://widget.example.com/chat.js"
      async: true
    - code: "window.chatSettings = {position: 'right'}"
  link:
    - rel: "preconnect"
      href: "https://fonts.example.com"
  meta:
    - name: "google-site-verification"
      content: "abc123"

Wie jeder Text können die Werte je Sprache verschieden sein. Die clay.yaml gehört zum Projekt: Skripte darin laufen auf jeder Seite, prüf sie also wie Code.

#Startseite

Die Startseite wird hier nicht eingestellt: Sie ist docs/index.md, eine Markdown-Seite mit optionaler Seitenliste und einer großen Kopfzeile. Siehe Indexseiten.

#Versionen und Sprachen

Siehe Versionen und Übersetzungen.

#Theme und Analytics

theme setzt eigene Farben, Ecken und Schriften, siehe Designs & Icons. analytics zählt Seitenaufrufe ohne Cookies, mit Plausible, Umami oder GoatCounter, siehe Analytics.

theme:
  primary: "#2563eb"
  font: "Lora, serif"
analytics:
  plausible: {}

#Werte pro Sprache

Auf einer mehrsprachigen Seite kann jede Texteinstellung einen Wert pro Sprache haben. Sprachen ohne Wert nutzen den der Standardsprache:

title:
  de: "Mein Projekt"
  en: "My Project"
navbar:
  links:
    - name: { de: "Webseite", en: "Website" }
      icon: "fa-solid fa-house"
      link: "https://example.com"

#Einstellungen in eigenen Dateien Neu in Clay 4

Eine Einstellung kann eine YAML-Datei nennen, die ihren Wert enthält, relativ zur clay.yaml:

title: "Mein Projekt"
siteURL: "https://meine-org.github.io"
navbar: config/navbar.yaml
variables: config/variables.yaml
head: config/head.yaml

Das funktioniert für navbar, messages, variables, head, analytics, theme, generate und languages. Die Dateien werden geprüft wie die clay.yaml selbst, und clay dev lädt neu, wenn sie sich ändern.

Wann aufteilen. Halte die clay.yaml als den einen Ort, an dem man die Seite auf einen Blick versteht: Titel, Adressen, Sprachen. Verschiebe eine Einstellung in eine eigene Datei, wenn sie lang ist oder jemand oder etwas anderes sie pflegt:

• variables, wenn ein Release-Skript die Version schreibt, damit es die clay.yaml nie anfasst,
• messages, wenn Übersetzer die Texte der Oberfläche betreuen,
• head, wenn sich Skripte und Bestätigungen häufen,
• navbar, wenn es viele Links sind.

Kurze Einstellungen findet man am leichtesten, wo sie sind; eine Seite mit einer Handvoll Einstellungen braucht keine Aufteilung. Diese Website hält Navigationsleiste, Oberflächentexte, Variablen und Head-Tags in config/, damit ihre clay.yaml die Seite auf einen Blick zeigt.

#Prüfungen

Clay prüft die clay.yaml bei jedem Build und warnt vor:

• unbekannten Einstellungen, meist Tippfehlern: clay.yaml: unknown key "navbar.lgo" is ignored (typo?),
• einem fehlenden title,
• langs, einer Einstellung aus Clay 1, die nicht mehr nötig ist,
• index, dir-meta.yaml und versions/ aus Clay 2, siehe Umstieg auf Clay 3.

Mit --strict lassen diese Warnungen den Build scheitern. Siehe Build-Prüfungen.