YAML Multiline String - Complete Guide with Examples

Overview

YAML provides multiple ways to write multiline strings, each with different behaviors for line breaks and whitespace. Choosing the right style depends on your specific needs.

Two Main Styles

• Literal Block (|) - Preserves line breaks
• Folded Block (>) - Converts line breaks to spaces

Literal Block Scalar (|)

Basic Usage

Use the pipe symbol (|) to preserve line breaks exactly as written:

YAML:

description: |
  This is line one.
  This is line two.
  This is line three.

Result:

This is line one.
This is line two.
This is line three.

Preserving Indentation

Indentation within the block is preserved:

YAML:

code: |
  def hello():
      print("Hello")
      return True

Result:

def hello():
    print("Hello")
    return True

Controlling Trailing Newlines

Use chomping indicators to control final line breaks:

|- (Strip final newlines):

text: |-
  Line one
  Line two

Result: "Line one\nLine two" (no trailing newline)

|+ (Keep all newlines):

text: |+
  Line one
  Line two

Result: "Line one\nLine two\n\n\n" (all newlines preserved)

Folded Block Scalar (>)

Basic Usage

Use the greater-than symbol (>) to fold line breaks into spaces:

YAML:

description: >
  This is a long
  paragraph that will
  be folded into a
  single line.

Result:

This is a long paragraph that will be folded into a single line.

Blank Lines Create Paragraphs

Empty lines are preserved as paragraph breaks:

YAML:

text: >
  First paragraph
  continues here.

  Second paragraph
  starts here.

Result:

First paragraph continues here.

Second paragraph starts here.

Chomping with Folded Style

Similar to literal blocks, you can control trailing newlines:

>- (Strip):

text: >-
  Line one
  Line two

>+ (Keep):

text: >+
  Line one
  Line two

Quoted Multiline Strings

Double-Quoted Strings

Use double quotes for strings with escape sequences:

message: "Line one\n\
  Line two\n\
  Line three"

Single-Quoted Strings

Single quotes don't support escape sequences:

message: 'Line one
  Line two
  Line three'

Note: Line breaks are converted to spaces in single-quoted strings

Quick Reference Table

Style	Syntax	Line Breaks	Use Case
Literal	\|	Preserved	Code, logs, preformatted text
Folded	>	To spaces	Long descriptions, paragraphs
Double-quoted	"..."	Escape sequences	Strings with special characters
Single-quoted	'...'	To spaces	Literal strings, no escaping

Real-World Examples

SQL Queries

queries:
  get_users: |
    SELECT id, name, email
    FROM users
    WHERE active = true
    ORDER BY created_at DESC
    LIMIT 100;

Shell Scripts

scripts:
  deploy: |
    #!/bin/bash
    echo "Starting deployment..."
    npm run build
    npm run test
    pm2 restart app

Long Descriptions

product:
  name: "Premium Widget"
  description: >
    This is our premium widget product
    that offers advanced features and
    exceptional performance for enterprise
    customers. Available in multiple colors
    and configurations.

HTML Templates

email_template: |
  <html>
    <body>
      <h1>Welcome!</h1>
      <p>Thank you for joining us.</p>
    </body>
  </html>

Best Practices

✓ Use Literal (|) for:

• Code snippets
• Log messages
• Preformatted text
• Content where line breaks matter

✓ Use Folded (>) for:

• Long descriptions
• Paragraphs of text
• Documentation
• Content where readability in YAML matters

Tip: Consistent Indentation

Always use consistent indentation (2 or 4 spaces) throughout your YAML file for better readability.

YAML Multiline String Guide

Overview

Literal Block Scalar (|)

Basic Usage

Preserving Indentation

Controlling Trailing Newlines

Folded Block Scalar (>)

Basic Usage

Blank Lines Create Paragraphs

Chomping with Folded Style

Quoted Multiline Strings

Double-Quoted Strings

Single-Quoted Strings

Quick Reference Table

Real-World Examples

SQL Queries

Shell Scripts

Long Descriptions

HTML Templates

Best Practices

✓ Use Literal (|) for:

✓ Use Folded (>) for:

Tip: Consistent Indentation

Related Articles

YAML Comments Guide

YML vs YAML