Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 39 ยท YAML and Config Files

Multi-line Text and Flow Style in YAML

Learn YAML block scalars (| and >), chomping indicators, quoted multi-line strings, flow sequences and mappings, and when each style is the clearest choice.

Short values fit on one line, but configuration files often hold longer text: a shell script inside a CI job, an SQL query, a license notice, a help message. YAML has a family of tools for this, and it also has a compact "flow" style for small collections that looks almost like JSON. This lesson covers both. If indentation, mappings and sequences are new to you, start with YAML Syntax Basics.

Block scalars: literal and folded

A block scalar is a string whose content is written on the following lines, indented more than its key. Two indicators choose how line breaks are treated.

  • | (literal): every line break is kept exactly as written.
  • > (folded): single line breaks become spaces, so a paragraph can be wrapped in the file but is one line in the data. A blank line becomes a real line break.
YAML
script: |
  echo "start"
  npm test
  echo "done"

summary: >
  This text is wrapped in the file
  but folds into one long line.

  A blank line above starts a new paragraph.

The first value is the string echo "start"\nnpm test\necho "done"\n. The second is This text is wrapped in the file but folds into one long line.\nA blank line above starts a new paragraph.\n. The block ends where the indentation returns to the key's level, and the indentation of the first content line is stripped from all lines.

Chomping: what happens to the final newline

By default a block scalar ends with exactly one newline ("clip"). A chomping indicator right after | or > changes that:

Indicator Name Trailing newlines
(none) clip exactly one is kept
- strip all are removed
+ keep all are kept
YAML
a: |-
  no newline at the end
b: |
  one newline at the end
c: |+
  keeps every trailing newline


d: next key

|- is the most useful one: it gives you a clean string for a version, a token or a command without a surprise \n at the end. You can also add an explicit indentation number (|2) when the first line of the text starts with spaces that must be preserved.

Node.js What the block scalar indicators produce

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The output uses JSON.stringify so you can see the exact \n characters. Compare the literal and folded results: the folded style joined first line second line but kept the paragraph break.

Quoted strings across lines

You can also break a plain or quoted scalar over several lines. A line break inside such a scalar folds into a single space, like >:

YAML
message: "This is one long sentence \
  continued on the next line."
note: this plain scalar
  also spans two lines

In a double-quoted string, a backslash at the end of the line removes the break completely, which is handy for long URLs. In practice block scalars are clearer than multi-line plain scalars, so prefer them.

Flow style: collections on one line

Besides the indented block style, YAML has a flow style that uses [ ] for sequences and { } for mappings, with commas between items. It is exactly the JSON look, with fewer quotes required.

YAML
ports: [80, 443, 8080]
labels: {env: prod, tier: web}
matrix:
  - [1, 2, 3]
  - [4, 5, 6]

Flow style is a good fit for short, simple collections such as a list of numbers or a pair of coordinates. For anything longer than a line, block style stays more readable and gives cleaner diffs in version control. You may mix both: a block mapping can contain flow values, and a flow collection can contain nested flow collections.

Because JSON is (nearly) valid YAML, this also works:

YAML
{"name": "shop", "ports": [80, 443]}

Empty values and explicit null

An empty value is null. These three lines are equivalent in most parsers:

YAML
a:
b: ~
c: null

An empty list and an empty mapping are written [] and {}. A key with nothing after it is not an empty list: it is null, which sometimes causes errors in code that expects a list.

Complex keys and the question mark

Keys are usually plain words, but they may be any scalar, for example "key with spaces": 1 or 2025: report. A key that is itself a collection needs the explicit key marker ?:

YAML
? [red, green]
: colors

This is rare and many languages cannot represent it (a JavaScript object key is always a string), so avoid it in files shared across tools.

Node.js Block style versus flow style give the same data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Which style should you choose?

flowchart TD
  A["Value to write"] --> B{"Is it text?"}
  B -- "one short line" --> C["plain or quoted scalar"]
  B -- "several lines" --> D{"Keep line breaks?"}
  D -- "yes (scripts, SQL)" --> E["literal |"]
  D -- "no (prose)" --> F["folded >"]
  A --> G{"Is it a small collection?"}
  G -- "fits on one line" --> H["flow [ ] or { }"]
  G -- "longer" --> I["block style"]

A quick decision guide.

Common mistakes

  • Wrong indentation under |. Content must be indented more than the key; a line that is less indented ends the block.
  • Forgetting the trailing newline. | adds one. Use |- when the value must not end with a newline.
  • Folded text with indented lines. In > blocks, lines that are indented more than the first line are not folded, which can look like an accident.
  • Colons in flow values. {url: http://x.test} is fine, but {note: a: b} is not; quote such text.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which indicator keeps every line break of a multi-line text exactly as written?

    The pipe makes a literal block scalar: each newline in the file is a newline in the value. The greater-than sign folds lines into spaces.
  2. 2. What does the - in |- do?

    The minus is the strip chomping indicator: the final line break is not part of the value.
  3. 3. How is labels: {env: prod} written in block style?

    A nested mapping in block style puts the inner pairs on following lines, indented more than the key.
  4. 4. What value does a key with nothing after the colon have?

    An empty value is null, not an empty string or an empty list. Write [] or "" when you mean those.

Summary

  • | keeps line breaks, > folds them into spaces; blank lines separate paragraphs in folded text.
  • Chomping indicators - (strip) and + (keep) control trailing newlines; the default keeps exactly one.
  • Flow style ([ ], { }) suits short collections; block style suits everything else.
  • An empty value is null; write [], {} or "" explicitly for empty collections and strings.
  • The runnable code here models the rules; a real YAML library applies them for you.

Next: Anchors, Aliases, Tags and Documents