YAML Multiline String: Literal |, Folded > and Chomping
November 11, 2026 · 10 min read
YAML Multiline String Guide: Literal |, Folded > and Chomping
A YAML multiline string is usually written as a block scalar: | keeps every line break, and > folds lines into one paragraph. Add - to drop the final newline or + to keep trailing blank lines. Below, each form sits next to the exact string a parser returns, so you can pick the right one on purpose.
How YAML Multiline Strings Work: Block Scalars and Flow Scalars
YAML gives you two families for text that spans lines. Block scalars start with a header (| or >) after the key, and the content goes on the following lines. Flow scalars are the quoted and unquoted forms you already use for short values, and they can also wrap across lines.
The block scalar header can carry two optional extras: a chomping indicator (- or +) and an indentation indicator (a digit from 1 to 9). The content must be indented more than the key it belongs to, and it ends at the first non-empty line indented less than the content.
Indent with spaces only. The YAML 1.2.2 spec forbids tab characters in indentation, and both parsers we tested (js-yaml and Ruby's Psych) reject a tab-indented block with an error.
Every output in this post was checked with both of those parsers. The results are shown as JSON-style strings, so you can see each \n instead of guessing where a line break went. To print your own file the same way, convert the YAML to JSON.
Literal Block Scalar (|): Keep Every Line Break
The literal style keeps your text exactly as written, minus the indentation. Each line break stays a line break, and a blank line inside the block is part of the content.
message: |
Line one
Line two
Line four, after a blank line
next: x
The parser returns this value for message:
"Line one\nLine two\n\nLine four, after a blank line\n"
Notice that the blank line didn't end the block. Only the less-indented next: line did. The single trailing \n comes from the default chomping rule, covered below.
Reach for | whenever line breaks carry meaning: shell scripts, SQL, certificates, config files embedded in other config files, and Markdown bodies. Inside a literal block, : and # are plain text, and a backslash is just a backslash.
note: |
key: value # not a comment
C:\new\folder
"key: value # not a comment\nC:\\new\\folder\n"
The doubled backslashes are only how JSON prints one backslash. The string holds C:\new\folder with no newline escapes.
Folded Block Scalar (>): Join Lines Into One Paragraph
The folded style lets you wrap long text in your file while the value stays one line. A single line break becomes a space. A blank line becomes one \n. Lines indented further than the rest keep their breaks.
description: >
This sentence is split
across two lines.
A blank line starts a new line.
A more-indented line keeps its breaks.
Back to normal.
"This sentence is split across two lines.\nA blank line starts a new line.\n A more-indented line keeps its breaks.\nBack to normal.\n"
The more-indented rule surprises people. If you paste a nested bullet list or a code sample into a > block, those lines don't fold, and the extra spaces stay in the string. When that's not what you want, switch to |.
What Is the Difference Between | and > in YAML?
Both styles take the same indented text. The difference is what happens at each line break. Here is one value written both ways:
literal: |
Roses are red,
violets are blue.
folded: >
Roses are red,
violets are blue.
literal: "Roses are red,\nviolets are blue.\n"
folded: "Roses are red, violets are blue.\n"
If a program reads the value line by line, use |. If a person reads it as a sentence, > keeps your file tidy without adding breaks.
We prefer > for prose fields such as descriptions and summaries, and | for anything a program will execute or parse. A folded shell script runs as one long command, which is rarely what you meant.
How Do You Remove the Trailing Newline From a YAML Multiline String?
Add a chomping indicator to the header. Chomping controls the final line break and any blank lines after the last line of text. There are three modes, and the spec's block chomping section defines them:
- Clip (no indicator) keeps exactly one final newline and drops trailing blank lines.
- Strip (
-) removes the final newline and every trailing blank line. - Keep (
+) keeps the final newline and every trailing blank line.
clip: |
one
two
strip: |-
one
two
keep: |+
one
two
end: here
clip: "one\ntwo\n"
strip: "one\ntwo"
keep: "one\ntwo\n\n"
The same three modes apply to the folded style. This table shows all six headers for two lines of text followed by two blank lines:
| Chomping | Indicator | Literal block result | Folded block result |
|---|---|---|---|
| Clip (default) | none | "one\ntwo\n" | "one two\n" |
| Strip | - | "one\ntwo" | "one two" |
| Keep | + | "one\ntwo\n\n\n" | "one two\n\n\n" |
Strip is the one you'll use most. A folded value with >- gives you a single clean line, which matters for labels, commit subjects and anything compared as an exact string:
subject: >-
Fix the login redirect
when the session expires
"Fix the login redirect when the session expires"
Keep is rarer. It suits text where trailing blank lines matter, such as a template whose output must end with an empty line.
Indentation Indicators: When the First Line Starts With Spaces
A parser works out the block's indentation from its first non-empty line. That breaks when the first line is meant to start with spaces, such as an indented code sample. The parser treats those spaces as the block's indentation, and the next, shallower line becomes an error.
code: |
indented first line
second line
js-yaml reports bad indentation of a mapping entry, and Psych reports did not find expected key. An indentation indicator fixes it:
code: |2
indented first line
second line
" indented first line\nsecond line\n"
The digit isn't a column number. Per the spec's indentation indicator rules, the content indentation equals the block scalar's own indentation level plus that digit. For a value under a key, that level is the key's indentation. Here code sits at column 0, so 2 means content starts two spaces in, and anything beyond that is kept.
You can combine both indicators in either order. |2- and |-2 both returned " indented first line\nsecond line" in our tests.
Quoted and Plain Multiline Strings: Escapes, Folding and Backslashes
Flow scalars can span lines too, and they fold much like >: a single break becomes a space and a blank line becomes \n. Only the double-quoted style understands escapes.
Double-quoted strings accept \n, \t, \" and \\. A backslash at the end of a line joins the next line with no space, which is handy for long URLs:
msg: "one\ntwo\ttab \"quoted\""
url: "https://example.com/docs/\
getting-started"
msg: "one\ntwo\ttab \"quoted\""
url: "https://example.com/docs/getting-started"
Single-quoted strings have one escape only: write '' for a literal single quote. A \n stays a backslash and the letter n.
msg: 'It''s single-quoted,
so it folds too
and \n stays literal'
"It's single-quoted, so it folds too\nand \\n stays literal"
Plain (unquoted) scalars fold the same way, but they can't contain : or #, because a parser would read those as a new key or a comment.
msg: This plain scalar
spans two lines
and keeps one newline
"This plain scalar spans two lines\nand keeps one newline"
A quoted form beats a block scalar when you need an exact control character, a value with no trailing newline and no header, or a string inside a flow collection. For anything longer than two lines, a block scalar is easier to read. For short values, the YAML format cheat sheet lists when quotes are required.
YAML Multiline String Examples in Front Matter, CI and Kubernetes
Most real files use the same few patterns. In Markdown front matter, >- keeps a long description on one line:
title: My post
description: >-
A long description that
wraps over two lines.
That parses to "A long description that wraps over two lines.". Our front matter guide covers delimiters and fields, and R Markdown users can see where these blocks fit in a YAML header. Our editor's preview doesn't render front matter, so check the result in your static site generator. The front matter generator builds the surrounding YAML, TOML or JSON for seven presets.
GitHub Actions uses | for a multi-line run command, and each line runs in the same shell:
steps:
- name: Build
run: |
npm ci
npm run build
The run value is "npm ci\nnpm run build\n". A Kubernetes ConfigMap can use the same style to store a whole file under one key:
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
app.properties: |
color=blue
retries=3
That key holds "color=blue\nretries=3\n". A block scalar also works as a list item. Put the header right after the dash:
steps:
- |
first
item
- >-
second
item
["first\nitem\n", "second item"]
One limitation to keep in mind: inside a mapping or a list, YAML has no raw, unindented multiline string. Every content line must be indented at least as far as the block's indentation, so pasted text always needs re-indenting. And if the string lands in a Markdown body later, a single \n may render as a space or a break, depending on the renderer. Our Markdown line break guide explains why.
A YAML multiline string comes down to three choices: | or > for line breaks, - or + for the ending, and a digit when the first line starts indented. Check the parsed output once with the parser your tool uses, and you'll stop guessing. When the string ends up in a Markdown document, write and preview the body in the editor, which is free and runs in your browser with no account needed.