Configuration files often hold long text: a shell script, a message template, a description. YAML has several ways to write it, and they differ in how they treat newlines. Choosing the wrong one is a common source of stray line breaks and missing ones.
The two block styles
A block scalar starts with an indicator after the key and continues on the following indented lines.
Literal style (|) keeps line breaks exactly as written:
script: |
echo "building"
make all
echo "done"
The value is the three lines with newlines between them, and a final newline at the end.
Folded style (>) turns single line breaks into spaces, so a paragraph can be wrapped across lines in the source:
description: >
This is a long description that is wrapped
across several lines in the file but reads
as one paragraph.
The value is one line of text: "This is a long description that is wrapped across several lines in the file but reads as one paragraph." plus a final newline. Blank lines in a folded scalar become newlines, and more-indented lines keep their line breaks.
Chomping: controlling the final newline
By default, a block scalar ends with a single newline ("clip"). Add a modifier after the style indicator to change that:
|or>: clip, keep one final newline|-or>-: strip, remove all trailing newlines|+or>+: keep, preserve all trailing newlines, including blank lines
message: |-
No trailing newline here
Use strip when the receiving system treats a trailing newline as part of the value, such as a one-line command or a token.
The indentation indicator
The first non-empty line sets the indentation of the whole block. If that line starts with spaces that are meant to be part of the content, add an explicit indentation number after the indicator, for example |2, to say how much indentation to remove. It is rare, but it solves the case where the first line begins with extra spaces.
Quoted multiline strings
Plain and quoted scalars can also span lines, with different rules:
- Double-quoted strings fold line breaks into a space, and let you write
\nfor an explicit newline. A backslash at the end of a line joins it to the next without a space. - Single-quoted strings fold line breaks too, but have no escape sequences.
- Plain (unquoted) multi-line scalars also fold, but are fragile because of special characters.
note: "Line one\nLine two"
For text with explicit breaks that fits on a line, a double-quoted string with \n is compact.
Which should you pick?
| You want | Use |
|---|---|
| A script or code block with breaks preserved | | |
| A long paragraph wrapped in the file | > |
| No trailing newline | |- or >- |
| A short string with escapes | double quotes |
| Text with special characters and no escapes | single quotes |
Common mistakes
- Wrong indentation. Every line of the block must be indented more than the parent key, and consistently. Mixed indentation produces errors or truncated text.
- Trailing spaces after
|or>can cause issues in some parsers. - Tabs are not allowed for indentation, as in the rest of YAML. See fixing YAML indentation errors.
- Expecting folded text to keep indentation. More-indented lines are preserved in a folded scalar, but that surprises people.
- Forgetting the final newline matters for hashes and signatures of the text.
Check the result
A syntax check confirms the file parses, not what the string contains. Use Docento's Text & Markdown Editor to catch structural errors in a .yaml file, then print the parsed value in the program that will read it to confirm the newlines.
Takeaway
Use | to keep line breaks and > to fold them into spaces, add - to strip the final newline, and use double quotes with \n for short strings with explicit breaks. Indent consistently and verify the parsed result.
