How to Break YAML Multiline Strings Across Lines

To break a long string in YAML, use block scalars — the literal | or the folded > — to create a readable YAML multiline string without having to escape quotes or special characters. The literal style (|) preserves line breaks exactly, the folded style (>) turns line breaks into spaces (use >- to strip the final newline), and chomping indicators (- or +) control trailing newlines.

Contents

• YAML multiline string: literal (|) vs folded (>)
• Preserving quotes and special characters
• Examples and common patterns
• Chomping, indentation, and nested YAML
• Common pitfalls and tips
• Sources
• Conclusion

YAML multiline string: literal (|) vs folded (>)

Two block-scalar styles are the usual way to break a long string in YAML: literal (|) and folded (>). Both let you write the value over several lines in the file while the YAML parser produces a single string value to your program.

• Literal (|) — preserves newline characters exactly. Use this when formatting matters (scripts, poems, preformatted text).
• Folded (>) — replaces single newlines with spaces (good for long paragraphs), while blank lines remain paragraph breaks.

Quick examples (input on the left; parser result described on the right):

# literal: preserves the newline(s)
KeyLiteral: |
 this is my very very very
 very very long string

Resulting value (conceptually): “this is my very very very\nvery very long string\n”

# folded: lines fold into spaces
KeyFolded: >
 this is my very very very
 very very long string

Resulting value (conceptually): “this is my very very very very very long string\n”

If you don’t want the final newline added by default, append - after the block indicator (e.g., |- or >-) to strip it. The YAML specification documents block scalars and chomping behavior in detail: https://yaml.org/spec/1.2.2/. Practical guides and examples are available at https://yaml-multiline.info/ and the StackOverflow Q&A on this topic https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines.

Preserving quotes and special characters

You mentioned wanting to “maintain the quotes to avoid having to escape special characters.” Good news: block scalars let you include single quotes, double quotes, colons, hashes (#), and most other characters directly — you generally don’t need to wrap the block in single or double quotes to avoid escapes.

Example: a block scalar containing quotes and hashes

Key: |
 Here's a single quote: ' and a double quote: "
 A hash (#) and a colon: : are literal inside a block scalar.

That block yields a string that literally contains ', ", #, and : characters; the YAML parser does not treat them as delimiters or comments inside the block. If, instead, you truly need the string value to include literal surrounding quote characters (for example the value should start and end with '), write those quotes inside the block content:

Key: |-
 'this is my very very very very very very long string'

Important: YAML does not support concatenation with + like many programming languages — the pattern you showed ('a' + 'b') won’t merge two quoted scalars as you expect. See the StackOverflow discussion for that behavior: https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines.

If you do want escape sequences (like explicit \n), use a double-quoted scalar and include \n, but that’s usually less readable than block scalars for long text.

Examples and common patterns

Here are practical patterns that match common needs.

1. Keep everything exactly as written (good for scripts, config fragments):

script: |
 #!/bin/bash
 echo "Start"
 echo "Value: $MY_VAR"

2. Folded paragraph into a single logical line (good for descriptions):

description: >-
 This is a long description that I want to keep readable in the YAML
 file but treat as one line when my program loads the YAML.

Parsed value: “This is a long description that I want to keep readable in the YAML file but treat as one line when my program loads the YAML”

3. Preserve paragraphs (blank lines become paragraph breaks):

notes: >
 First paragraph line one.
 Second line of parag.

 Next paragraph starts here.

4. Nested mapping and forced indentation (common in Kubernetes manifests):

metadata:
 annotations:
 long-note: >-
 This annotation is long but will be folded into a single-line value.
 Keep indentation consistent with the parent mapping.

5. If you need the final string to include a trailing newline, use |+ (keep extra newlines) or | (default clip keeps one final newline). If you want no trailing newline, use |-.

For further examples and explanation see Baeldung and Pure Storage’s guides: https://www.baeldung.com/yaml-multi-line and https://www.purestorage.com/knowledge/what-is-yaml-multiline-string.html.

Chomping, indentation, and nested YAML

Chomping indicators control trailing newlines:

• | or > (no indicator) — “clip”: keep exactly one trailing newline.
• |- or >- — “strip”: remove the final newline.
• |+ or >+ — “keep”: preserve all trailing newlines.

Indentation: YAML auto-detects the block’s indentation based on the first non-blank line, which is usually what you want. You can also explicitly set indentation with a digit (for example |2) if you need precise control in some edge cases. The YAML spec covers these details: https://yaml.org/spec/1.2.2/.

Simple rule of thumb: if you want exact layout (scripts, preformatted text), use |. If you want plain text folded into paragraphs (descriptions, long single-line values), use > and consider >- if you don’t want the final newline.

Common pitfalls and tips

• Don’t try to concatenate quoted scalars with +. YAML doesn’t do that; it will either error or treat + as content. Use block scalars to avoid concatenation hacks (see the StackOverflow thread).
• Folded > may be surprising in CI or command contexts: in some tools a folded YAML string was interpreted as multiple commands. If you’re writing multi-line shell steps, prefer literal | or test the behavior in your target runtime. See the GitHub community discussion for an example: https://github.com/orgs/community/discussions/26105.
• If your text includes leading spaces that must be preserved (e.g., code blocks), use | — folded style collapses runs of whitespace.
• When writing YAML for tools (Kubernetes, Docker Compose, GitLab CI), check how that tool treats block scalars. Most follow YAML spec, but behavioral differences can exist in how trailing newlines are handled.
• Want explicit newlines (\n) inside the value? Use double-quoted scalars: "line1\nline2". But for readability, block scalars are usually easier.

If you’re using a YAML library (PyYAML, ruamel.yaml, etc.), test the loaded string in your code so you see exactly what the parser returns.

Sources

• https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines
• https://yaml-multiline.info/
• https://www.purestorage.com/knowledge/what-is-yaml-multiline-string.html
• https://alisoftware.github.io/yaml/2021/08/19/yaml-part2-strings/
• https://saturncloud.io/blog/how-to-break-a-string-in-yaml-over-multiple-lines/
• https://kodekloud.com/blog/yaml-multiline-string/
• https://www.baeldung.com/yaml-multi-line
• https://yaml.org/spec/1.2.2/
• https://github.com/orgs/community/discussions/26105
• https://rwaight.github.io/resources/coding/multi-line-strings-in-YAML/

Conclusion

Use YAML block scalars to break long strings cleanly: | (literal) to preserve newlines and exact formatting, or > (folded) to join lines into a paragraph. Block scalars avoid the need to escape quotes or special characters, and chomping indicators (- or +) let you control trailing newlines — in short, they’re the proper, readable way to write a YAML multiline string.