YAML-Frontmatter

YAML-Frontmatter: strukturierte Metadaten, die Flat-File-CMS und Docs-as-Code antreiben

YAML-Frontmatter ist ein Block strukturierter Metadaten am Kopf einer Markdown-Datei, eingefasst zwischen zwei Zeilen aus drei Bindestrichen, der maschinenlesbare Daten vom menschlich geschriebenen Inhalt trennt.

Eine Markdown-Datei besteht aus reinem Text, und reiner Text kennt keine Felder. Sobald ein System aber wissen muss, wie eine Seite heisst, wann sie erschien, welches Layout sie nutzt oder ob sie veröffentlicht ist, braucht es einen Ort für solche Angaben. Frontmatter ist dieser Ort: ein kurzer YAML-Abschnitt, der dem Generator sagt, wie er den darunterliegenden Inhalt behandeln soll. Diese Seite beschreibt das Format, wofür es eingesetzt wird und an welchen YAML-Eigenheiten es regelmässig bricht.

Das Format

Frontmatter steht ganz am Anfang der Datei und wird durch zwei Trennzeilen aus je drei Bindestrichen begrenzt. Dazwischen liegt ein YAML-Dokument, darunter folgt der eigentliche Inhalt in Markdown:

---
title: Erste Schritte
date: 2026-06-17
tags: [anleitung, einstieg]
published: true
---
# Erste Schritte

Hier beginnt der eigentliche Text der Seite.

YAML steht für "YAML Ain't Markup Language" und ist ein Format zur Serialisierung von Daten, das auf Lesbarkeit für Menschen ausgelegt ist. Es bildet die gängigen Bausteine ab: einzelne Werte wie Zeichenketten und Zahlen, Schlüssel-Wert-Paare (Mappings) und Listen (Sequenzen). Struktur entsteht über Einrückung mit Leerzeichen, nicht über Klammern. Genau diese beiden Punkte, die Trennung von Daten und Text sowie die einrückungsbasierte Syntax, machen Frontmatter so verbreitet und zugleich so fehleranfällig.

Wie ein Generator die Datei liest

Der Build-Schritt eines Flat-File-Systems teilt jede Datei in zwei Hälften. Der Frontmatter-Block wird als YAML geparst und zu strukturierten Daten, der Rest wird als Markdown zu HTML gerendert. Beide Hälften fliessen anschliessend in eine Vorlage, die daraus die fertige Seite baut:

flowchart TD
    F["Markdown-Datei<br/>--- YAML --- + Inhalt"] --> S{"Trennung<br/>an den --- Zeilen"}
    S -->|"oberer Block"| Y["YAML parsen<br/>title, date, tags ..."]
    S -->|"unterer Block"| M["Markdown rendern<br/>zu HTML"]
    Y --> T["Vorlage<br/>Daten + Inhalt"]
    M --> T
    T --> P["fertige Seite"]

In diesem Modell sind die Daten Teil des Dokuments und nicht in eine separate Datenbank ausgelagert. Eine Seite ist eine Datei, versionierbar in Git und ohne laufenden Dienst lesbar. Das ist der Kern des Flat-File-Ansatzes, wie ihn Grav CMS umsetzt, und der Grund, warum Frontmatter die natürliche Heimat für Seitenmetadaten ist.

Daten im Dokument

Der Nutzen von Frontmatter zeigt sich an konkreten Feldern. Üblich sind ein Titel und eine Beschreibung für die Seite selbst und für Suchmaschinen, ein Datum für Sortierung und Archiv, ein Verweis auf eine Layout-Vorlage, ein Veröffentlichungs-Schalter und eine Liste von Schlagworten zur Kategorisierung. Welche Felder gelten, legt das jeweilige System fest: Grav, Jekyll und Hugo kennen je eigene Schlüssel, das Prinzip ist jedoch dasselbe.

Weil diese Daten im Dokument selbst stehen, gehören sie zum Inhalt und wandern mit ihm durch jede Pipeline. Ein Pull Request verändert Text und Metadaten in einem Zug, ein Review sieht beides nebeneinander, und der Verlauf zeigt, wann ein Titel oder ein Veröffentlichungsstatus geändert wurde. Damit ist Frontmatter ein tragender Baustein von Docs-as-Code, dem Ansatz, Dokumentation wie Quellcode zu behandeln, versioniert und über GitOps und Reconciliation automatisiert ausgeliefert. Dieselbe Idee, regelhafte Vorgaben als versionierte Dateien zu führen, trägt auch Compliance as Code.

Die YAML-Fallstricke

YAML ist bequem zu schreiben und unangenehm präzise zu parsen. Die häufigsten Defekte in Frontmatter stammen nicht aus dem Inhalt, sondern aus der Syntax.

Einrückung mit Tabs. YAML erlaubt zur Strukturierung ausschliesslich Leerzeichen, niemals Tabulatoren. Ein einzelner Tab, oft vom Editor unbemerkt eingefügt, führt zu einem Parse-Fehler. Eine inkonsistente Einrückung verschiebt zudem stillschweigend, zu welchem Schlüssel ein Wert gehört.
Implizite Typisierung. Parser raten aus einem unquotierten Wert den Datentyp. So wird 9.30 zur Zahl 9.3, und ein Versionsstring verliert seine nachgestellte Null. Wer eine Zeichenkette meint, setzt sie in Anführungszeichen.
Das Norway-Problem. Ältere Parser nach YAML 1.1 deuten zahlreiche Wörter als Wahrheitswert, darunter yes, no, on und off. Der Ländercode NO für Norwegen wird damit zum booleschen false. YAML 1.2 hat diese Liste auf true und false eingegrenzt, doch viele verbreitete Parser arbeiten weiterhin nach den alten Regeln. Anführungszeichen um den Wert beenden das Raten.
Doppelpunkte und Sonderzeichen. YAML-Plain-Scalars brechen vor allem an einem Doppelpunkt-mit-Leerzeichen oder an kontextabhängigen Sonderzeichen. Werte mit : (Doppelpunkt und Leerzeichen), einem #-Kommentar oder einem führenden - gehören in Anführungszeichen.

Die durchgehende Gegenmassnahme ist einfach und eintönig: im Zweifel quotieren und auf konsistente Einrückung mit Leerzeichen achten. Strengere Werkzeuge wie StrictYAML gehen weiter und behandeln jeden Wert grundsätzlich als Zeichenkette, bis ein Schema etwas anderes verlangt.

Abgrenzung

Frontmatter ist eine Konvention, kein eigener Standard: Es kombiniert Markdown und YAML, ohne selbst spezifiziert zu sein. Die Trennzeile aus drei Bindestrichen ist nicht zufällig, sie entspricht dem YAML-Dokumenttrenner. Manche Systeme erlauben statt YAML auch TOML oder JSON im Frontmatter, das Muster bleibt gleich. Verwandt, aber anders gelagert ist das Model Context Protocol, das Daten nicht im Dokument ablegt, sondern KI-Modelle zur Laufzeit mit Datenquellen verbindet. Frontmatter löst die statische Frage, MCP die dynamische.

Referenzen

Grav Page Headers (Frontmatter). Dokumentation der von Grav unterstützten Frontmatter-Felder und der Taxonomie. (2026). learn.getgrav.org/17/content/headers
Jekyll Front Matter. Beschreibt Frontmatter als YAML-Block zwischen zwei Dreifach-Bindestrich-Zeilen am Dateianfang und die vordefinierten Variablen. (2026). jekyllrb.com/docs/front-matter/
StrictYAML The Norway Problem. Erläutert, warum implizite Typisierung gefährlich ist, am Beispiel des zu false geparsten Ländercodes NO. (2023). hitchdev.com/strictyaml/why/implicit-typing-removed/
YAML.org YAML Specification 1.2.2. Die aktuelle Sprachspezifikation; Revision 1.2.2 grenzt unter anderem die Wahrheitswerte auf true und false ein. (01.10.2021). yaml.org/spec/1.2.2/

KI fragen

Diese Links öffnen externe KI-Dienste, die Unterhaltung und deren Inhalt werden dabei an den jeweiligen Anbieter übertragen.

YAML-Frontmatter