YAML multiline strings: | and >

A block starting with | keeps line breaks. A block starting with > joins lines with spaces. A - or + after either one decides what happens to the line breaks at the end.

The five blocks

Each YAML block on the left produces the JSON string on the right. These are the outputs of YAML to JSON.

a: |
  one
  two

"one\ntwo\n"

Literal. Every line break is kept, plus one at the end.

a: |-
  one
  two

"one\ntwo"

Literal, strip. Line breaks are kept. The final one is removed.

a: |+
  one
  two


b: 1

"one\ntwo\n\n\n"

Literal, keep. The blank lines at the end are kept too.

a: >
  one
  two

  three

"one two\nthree\n"

Folded. Lines join with a space. A blank line becomes a line break.

a: >-
  one
  two

"one two"

Folded, strip. One line of text with no line break at the end.

Which one to use

Shell scripts in CI files, SQL, and anything else where each line matters: |.
A certificate or key pasted into a config file: |, so the line breaks survive.
A long description or message that should be one line: >-.
A value compared exactly, such as a token or a URL split for readability: >- or |-, so no newline is added at the end.

Without a block indicator

A plain value continued on the next line is folded like >-.

a: one
  two

The JSON is "one two". In a double-quoted string, write \n for a line break: a: "one\ntwo" becomes "one\ntwo".

The edge case

In a folded block, a line indented further than the others is not joined. It keeps its line breaks and its extra spaces.

a: >
  one
    indented
  two

The JSON is "one\n indented\ntwo\n". If a folded paragraph unexpectedly keeps a line break, look for a line with extra indentation.

Paste a block into YAML to JSON to see the exact string, including every \n.