YAML Multiline Strings

A multiline string in YAML is a string value that spans more than one line. YAML provides two dedicated styles for multiline text: the literal block style and the folded block style. These styles make it easy to embed long text — like scripts, descriptions, SQL queries, HTML, or configuration content — directly inside a YAML file without any special encoding.

Why Multiline Strings Matter

Many real-world tools embed large text blocks in YAML. For example, GitHub Actions runs shell scripts inside YAML files. Kubernetes ConfigMaps store entire configuration files as YAML values. Without multiline string support, these would need ugly one-line strings full of \n escape characters.

Two Multiline Styles at a Glance

Literal Block Style ( | )

The pipe character | tells YAML to keep every line break exactly as written. Each line in the block becomes a separate line in the final string value.

address: |
  123 Baker Street
  London
  United Kingdom
  W1A 1AA

The value of address is:

123 Baker Street
London
United Kingdom
W1A 1AA

Every line break is preserved. This is ideal for postal addresses, code blocks, and any content where formatting must be exact.

Folded Block Style ( > )

The greater-than symbol > tells YAML to replace single line breaks with spaces. Multiple lines are joined into one paragraph. Only blank lines between paragraphs are preserved as real line breaks.

description: >
  This is a long description
  that continues on the next line
  and wraps into a single paragraph.

The final value is: This is a long description that continues on the next line and wraps into a single paragraph.

Literal vs Folded Comparison Diagram

+----------------------------------------------+
|  Input in YAML                               |
+----------------------------------------------+
|  literal:  |         folded: >               |
|    Line 1              Line 1                |
|    Line 2              Line 2                |
+----------------------------------------------+
|  Result                                      |
+----------------------------------------------+
|  "Line 1\nLine 2\n"    "Line 1 Line 2\n"     |
+----------------------------------------------+

Trailing Newlines – Chomp Indicators

By default, YAML adds one newline at the end of a block scalar. Chomp indicators control this behavior.

Clip (Default – One Trailing Newline)

text: |
  Hello World

Value: Hello World\n (one newline at the end)

Strip (|-) – Remove All Trailing Newlines

text: |-
  Hello World

Value: Hello World (no trailing newline)

Keep (|+) – Keep All Trailing Newlines

text: |+
  Hello World

Value: Hello World\n\n\n (all blank lines at the end are kept)

Chomp Indicators Summary Table

Indentation Inside Block Scalars

The content of a block scalar must be indented more than the parent key. Extra spaces at the start of each content line (beyond the indentation) are preserved.

script: |
  #!/bin/bash
  echo "Starting deployment"
  cd /var/www
  git pull origin main
  systemctl restart nginx

This is a shell script embedded directly in YAML. Every line is preserved exactly. This pattern is used in GitHub Actions, GitLab CI, and Ansible.

Folded Blocks with Blank Lines (Paragraph Breaks)

In a folded block, a blank line creates a real paragraph break (a newline in the output), while regular line breaks are folded into spaces.

notes: >
  First paragraph line one
  first paragraph line two

  Second paragraph starts here
  second paragraph line two

Result:

First paragraph line one first paragraph line two
Second paragraph starts here second paragraph line two

The blank line between the paragraphs becomes a real newline. Lines within the same paragraph are joined with spaces.

Real-World Example – GitHub Actions Run Script

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and Deploy
        run: |
          echo "Building application..."
          npm install
          npm run build
          echo "Build complete"
          cp -r dist/ /var/www/html/

The run key uses a literal block scalar to embed a multi-step shell script directly in the YAML workflow file. Every line runs as a separate shell command.

Real-World Example – Kubernetes ConfigMap with File Content

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-config
data:
  nginx.conf: |
    server {
      listen 80;
      server_name example.com;
      location / {
        root /usr/share/nginx/html;
        index index.html;
      }
    }

The entire Nginx configuration file is stored as a literal block value under the nginx.conf key. Kubernetes reads this and writes the content into the container as a real file.

Summary

• Literal block (|) preserves all line breaks exactly as written
• Folded block (>) joins lines into a paragraph by replacing line breaks with spaces
• Use |- to remove trailing newlines and |+ to keep all trailing newlines
• Block scalars are indented under their parent key
• Use literal blocks for scripts, code, and formatted text
• Use folded blocks for long prose descriptions that should appear on one line