How do I write a multiline string in YAML?

Dark navy cover card with the title 'How do I write a multiline string in YAML?' in white and a green accent bar

To write a YAML multiline string, put | after the key to keep every line break, or > to fold the lines into one line joined by spaces. Indent the text under the key. Add - to drop the final newline or + to keep trailing blank lines.

script: |
  npm ci
  npm run build

The two block styles: | keeps breaks, > folds them

The literal style (|) and the folded style (>) are the two block styles for a YAML multiline string. The YAML 1.2.2 spec defines literal as the style where all line breaks are significant, and folded as the one where each line break turns into a space unless it ends an empty or a more-indented line.

I ran each style through js-yaml 4.1.0 and printed the string each one returns as JSON:

YAML you write String the parser returns
a: | + two lines "line one\nline two\n"
a: > + two lines "line one line two\n"
a: |- + two lines "line one\nline two"
a: >- + two lines "line one line two"
a: |+ + two lines + a blank line "line one\nline two\n\n"

Use | for anything where lines matter: shell scripts, certificates, SQL, Markdown. Use > for long prose you want to wrap in the file but read as one paragraph.

What the - and + after | or > do

The - and + are chomping indicators, and they decide what happens to the newline at the end of the block. The spec names three behaviours:

  • Clip (no indicator): the final line break stays, trailing blank lines are dropped.
  • Strip (-): the final line break and any trailing blank lines are removed.
  • Keep (+): the final line break and every trailing blank line stay in the string.

The default bites when you compare a value to a fixed string. A token written with | ends in \n, so token === "abc123" fails. Write it with |-, or trim it in code.

How folding treats blank and indented lines

Folding with > is not a blind join. A blank line becomes a real newline, and the spec says more-indented lines are not folded at all. This input:

a: >
  line one
  line two

  new para
    indented
  end

came back from js-yaml as "line one line two\nnew para\n indented\nend\n". The first two lines joined. The blank line became one \n, and the indented line kept its own line and its extra spaces. That's handy for a description with a code sample inside, and confusing if you didn't expect it.

Multiline strings without | or >

You can also continue a plain or quoted string onto the next indented line, but the line breaks fold into spaces. a: line one followed by an indented line two parsed to "line one line two".

Double quotes give you more control, because escape sequences only work in double-quoted strings:

  • "first\nsecond" gives a real newline between the words.
  • A backslash at the end of a line joins it to the next with no space. The spec says an escaped line break is left out of the content.
  • Trailing spaces before a folded break are thrown away.

I'd only use this for a short string with one \n in it. Past two lines, a block style is easier to read and review.

The indentation indicator for text that starts with spaces

When the first line of a block is indented more than the rest, add a number after | or > to say how deep the block's indentation is. Without it, the parser takes its indentation from the first line.

a: |2
    leading spaces
  normal

This parsed to " leading spaces\nnormal\n". Drop the 2 and js-yaml stops with bad indentation of a mapping entry (3:3), because it decided the block was 4 spaces deep and then hit a line with 2. The spec says a writer should only add the indicator when detection would fail, so you'll rarely see it outside this case.

A real example: CI scripts and config files

Most YAML multiline strings you'll write are commands in a CI file. In GitHub Actions workflow syntax, run: | with one command per line runs them all, and "each line runs in the same shell":

- name: Clean install dependencies and build
  run: |
    npm ci
    npm run build

Use | here, not >. With > the two lines fold into npm ci npm run build, one command with extra arguments.

The other common mistake is a colon inside a plain value. cmd: echo a: b failed in js-yaml with bad indentation of a mapping entry (1:12), because : starts a new mapping. Other parsers report it as mapping values are not allowed here. Put the value in a | block or in quotes and it parses. Tabs cause their own errors, covered in why YAML fails because of tabs.

Which YAML multiline string style should you pick?

Pick by what the text is, not by habit:

Text Style
Shell commands, scripts, SQL |
Certificates, keys, values compared exactly |-
Long description shown as one paragraph > or >-
Text where trailing blank lines matter |+
Short string with one newline "double\nquoted"

To check what a block really becomes, parse it and look at the JSON, as in converting YAML to JSON in JavaScript. Each \n marks a line break. If you're still choosing a format for a config file, see JSON vs YAML for config files.

My take

My default is |- for anything a program reads and >- for prose. The hidden trailing newline is the bug I've seen most from block strings: a password or token that's one character longer than it looks. The - removes it.

The limitation: none of these styles show trailing spaces or the final newline when you read the file, and editors often strip trailing whitespace on save. If those characters matter, use a double-quoted string with explicit escapes, or don't keep that value in YAML.

FAQ

What is the difference between | and > in YAML?

The pipe (|) keeps every line break exactly as written. The greater-than sign (>) folds single line breaks into spaces, so the lines become one long line, but blank lines and more-indented lines still break.

What does |- mean in YAML?

It is a literal block with the strip chomping indicator. Line breaks inside the text are kept, but the final line break and any trailing blank lines are removed.

How do I keep the trailing newline in a YAML string?

Use | or > on their own and you get exactly one final line break. Use |+ or >+ to keep the final line break and every trailing blank line too.

Can I write a multiline string without | or >?

Yes. A plain or double-quoted string can continue on the next indented line, but the line breaks fold into spaces. In double quotes you can add a real newline with the \n escape.

Sources