Mehrzeilige Strings in YAML: | und > richtig verwenden

Für mehrzeilige Texte (YAML multiline string) nutzt du in YAML einen Blockstring: | (literal) behält jeden Zeilenumbruch, > (folded) macht aus einzelnen Zeilenumbrüchen Leerzeichen. Danach folgt der Text eingerückt in den nächsten Zeilen. Ob am Ende ein Zeilenumbruch steht, steuerst du mit - und + (|-, |+, >-, >+).

Was am Ende wirklich im String steht, siehst du am schnellsten im JSON. Füge dein YAML in den YAML-zu-JSON-Konverter ein: Dort ist jeder Zeilenumbruch als \n sichtbar. Alle Beispiele unten kannst du so nachprüfen. Die Konvertierung läuft lokal im Browser, es wird nichts an einen Server gesendet.

Literal-Block mit |

text: |
  Zeile eins
  Zeile zwei

{ "text": "Zeile eins\nZeile zwei\n" }

Jeder Zeilenumbruch bleibt erhalten, auch der letzte. Die gemeinsame Einrückung der Zeilen gehört nicht zum Text. Zusätzliche Leerzeichen darüber hinaus bleiben dagegen erhalten, ebenso Leerzeilen:

text: |
  a

  b

{ "text": "a\n\nb\n" }

Folded-Block mit >

text: >
  Das ist ein langer Satz,
  der im Editor auf
  mehrere Zeilen verteilt ist.

{ "text": "Das ist ein langer Satz, der im Editor auf mehrere Zeilen verteilt ist.\n" }

Einzelne Zeilenumbrüche werden zu einem Leerzeichen. Eine Leerzeile bleibt als Zeilenumbruch erhalten, so trennst du Absätze. Zeilen, die stärker eingerückt sind als der Rest, werden nicht gefaltet:

text: >
  a
  b

  c
    d
  e

{ "text": "a b\nc\n  d\ne\n" }

Typischer Einsatz: lange Beschreibungstexte, die im Editor nicht über den Bildschirmrand laufen sollen.

Chomping: Zeilenumbruch am Ende steuern

Der Indikator hinter | oder > legt fest, was mit den Zeilenumbrüchen am Ende des Blocks passiert:

Mit |- bekommst du einen sauberen String ohne Anhängsel:

text: |-
  a
  b

{ "text": "a\nb" }

Mit |+ bleiben auch Leerzeilen am Ende erhalten:

text: |+
  a
  b


andere: 1

{ "text": "a\nb\n\n\n", "andere": 1 }

Bei >- und >+ gilt dasselbe wie bei |- und |+, nur dass der Text im Inneren gefaltet wird:

a: >-
  eins
  zwei
b: >+
  eins
  zwei

c: 1

{ "a": "eins zwei", "b": "eins zwei\n\n", "c": 1 }

Faustregel: | oder > reichen meist. - nimmst du, wenn der Wert ohne abschließenden Zeilenumbruch verglichen oder zusammengesetzt wird. + brauchst du selten.

Einrückungs-Indikator: |2

Normalerweise bestimmt die erste nicht leere Zeile die Einrückung des Blocks. Beginnt der Text selbst mit Leerzeichen, wäre das mehrdeutig. Dann gibst du die Einrückung als Zahl an (1–9), relativ zur Einrückung des übergeordneten Schlüssels:

text: |2
    a
  b

{ "text": "  a\nb\n" }

Hier ist die Einrückung auf 2 festgelegt. Die erste Zeile hat vier Leerzeichen, davon gehören zwei zum Text. Kombinieren kannst du beides: |2- oder |-2 sind gleichwertig.

Mehrzeilige Strings in Anführungszeichen

Auch ohne Block darf ein String über mehrere Zeilen laufen. Das gilt für einfache, doppelte und sogar ungequotete Werte (Plain Scalars). In allen drei Fällen wird ein einzelner Zeilenumbruch zu einem Leerzeichen und eine Leerzeile zu einem Zeilenumbruch:

plain: a
  b

  c
einfach: 'a
  b

  c'
doppelt: "a
  b

  c"

{ "plain": "a b\nc", "einfach": "a b\nc", "doppelt": "a b\nc" }

Nur in doppelten Anführungszeichen kannst du außerdem Escape-Sequenzen nutzen. \n ist ein echter Zeilenumbruch, und ein \ am Zeilenende unterdrückt den Umbruch samt Leerzeichen:

text: "Zeile eins\nZeile zwei"

{ "text": "Zeile eins\nZeile zwei" }

Für längere Texte sind Blockstrings meist lesbarer. In einfachen Anführungszeichen ist \n dagegen kein Escape, sondern bleibt als Backslash und n stehen.

Typische Anwendungen

Skripte in GitHub Actions. Mit run: | läuft jede Zeile als eigener Befehl im selben Shell-Skript:

steps:
  - name: Bauen
    run: |
      npm ci
      npm run build

{
  "steps": [
    { "name": "Bauen", "run": "npm ci\nnpm run build\n" }
  ]
}

Willst du einen sehr langen einzelnen Befehl umbrechen, passt run: >- besser: Aus den Zeilen wird ein einzeiliger Befehl ohne Zeilenumbruch am Ende.

Zertifikate und Schlüssel. PEM-Blöcke bestehen aus festen Zeilen und brauchen deshalb |:

cert: |
  -----BEGIN CERTIFICATE-----
  MIIB...
  -----END CERTIFICATE-----

Mit > würden die Zeilen zu einer verklebt, und das Zertifikat wäre ungültig.

SQL und Konfigurationstexte.

query: |
  SELECT id, name
  FROM users
  WHERE aktiv = true;

Hier hilft |, weil Kommentare im SQL (-- ...) nur bis zum Zeilenende gelten. Würdest du > verwenden, würde ein solcher Kommentar den Rest der Abfrage verschlucken.

Häufige Fehler

Falsche oder fehlende Einrückung. Der Block-Inhalt muss tiefer eingerückt sein als der Schlüssel:

text: |
zeile

Das ist ungültig oder ergibt einen leeren String. Richtig:

text: |
  zeile

Tabs. YAML erlaubt keine Tabs zur Einrückung. Nutze Leerzeichen.

Weniger eingerückte Zeile mitten im Block. Sie beendet den Block. Der Rest wird dann als neuer Schlüssel gelesen und führt zu einem Fehler. Mehr zu den Meldungen steht im Ratgeber YAML-Fehler.

Leerzeichen am Zeilenende. Sie bleiben im String erhalten und sind im Editor unsichtbar. Im JSON siehst du sie sofort vor dem \n.

Zeilenumbruch am Ende vergessen einzukalkulieren. | und > hängen immer einen \n an. Das stört bei Vergleichen, Dateinamen oder Hashes. Dann nimm |- oder >-.

Kommentare im Block. Ein # innerhalb eines Blockstrings ist Text, kein Kommentar. Ein Kommentar ist nur in der Kopfzeile erlaubt (text: | # Hinweis).

Mit dem YAML-Formatierer rückst du ein YAML-Dokument einheitlich ein und behältst dabei die Kommentare.

Kurz gesagt

• | behält alle Zeilenumbrüche, > macht aus einzelnen Umbrüchen Leerzeichen. Leerzeilen trennen Absätze.
• Standardmäßig endet der String mit genau einem \n. - entfernt ihn, + behält alle.
• Bei Text, der selbst mit Leerzeichen beginnt, hilft der Einrückungs-Indikator, zum Beispiel |2.
• Für Skripte, Zertifikate und SQL nimmst du |. > ist für Fließtext.
• Prüfe das Ergebnis im YAML-zu-JSON-Konverter: Dort siehst du jeden Zeilenumbruch als \n.

Weiterlesen: Was ist YAML?, JSON vs. YAML, YAML-Fehler, YAML-Norway-Problem.