YAML Multiline Strings

YAML has two block styles for multiline strings: the literal style |, which preserves newlines, and the folded style >, which joins lines into a paragraph. Both accept a "chomping" indicator that controls trailing newlines. This guide covers every variant with examples, plus the quoted alternatives.

Literal block scalar: |

Every line break is kept. This is the right choice for scripts, code, certificates, and anything where whitespace matters.

script: |
  echo "Building..."
  npm ci
  npm run build

Result: "echo \"Building...\"\nnpm ci\nnpm run build\n". Note the single trailing newline.

Folded block scalar: >

Single newlines become spaces; blank lines become a single newline. Use it for long descriptions that you want to wrap in the source file.

description: >
  This service handles authentication
  for all internal tools.

  It is owned by the platform team.

Result: "This service handles authentication for all internal tools.\nIt is owned by the platform team.\n"

Chomping indicators: keep, strip, or clip

A character after | or > controls what happens to newlines at the end of the block.

Indicator	Name	Trailing newlines
| or >	Clip (default)	Exactly one
|- or >-	Strip	None
|+ or >+	Keep	All of them

clip: |
  text

strip: |-
  text

keep: |+
  text

next: value

gives "text\n", "text", and "text\n\n" respectively. Strip (|-) is what you usually want for values like commands or keys that must not end in a newline.

Indentation indicator

The parser detects the block's indentation from its first non-empty line. If that line intentionally starts with spaces, tell the parser the base indentation explicitly:

art: |2
    indented two extra spaces
  normal line

The indicator can combine with chomping: |2- or |-2 are both valid.

Quoted multiline strings

Double-quoted strings can span lines and support escapes. Line breaks inside them are folded into spaces, and a trailing backslash prevents even that:

message: "First line\nSecond line"
folded: "this is
  one line"
joined: "no space\
  here"

Single-quoted strings also fold line breaks but process no escapes; the only special sequence is '' for a literal apostrophe.

Plain multiline strings

Even an unquoted value can continue on indented lines and is folded like >:

note: this value
  continues here

This works but is easy to misread. Prefer > or quotes for anything longer than one line.

Real-world examples

GitHub Actions step:

- name: Deploy
  run: |
    ./scripts/build.sh
    ./scripts/deploy.sh --env production

Kubernetes ConfigMap with an embedded config file:

data:
  nginx.conf: |
    server {
      listen 80;
      location / { proxy_pass http://app:8080; }
    }

Docker Compose healthcheck with a stripped newline:

healthcheck:
  test: >-
    curl --fail http://localhost:8080/health
    || exit 1

Common mistakes

• Inconsistent indentation inside the block. Lines less indented than the first line end the block early. Run the file through the YAML validator to catch this.
• Tabs. Indent block content with spaces only.
• Forgetting the strip indicator. A value like a password or token picks up a trailing newline with plain |. Use |-.
• Using a comment inside a block. A # inside a block scalar is text, not a comment.

To see exactly what a block produces, paste it into the YAML to JSON converter. The JSON string shows every newline as \n.