YAML Pipe Operator Explained With Examples

YAML looks tiny and calm. Then you meet the pipe symbol, |, and wonder if it is plumbing. Good news. It is not scary. The YAML pipe operator helps you write text that keeps its line breaks, spaces, and shape.

TLDR: The YAML pipe operator, |, is used for literal block text. It keeps line breaks exactly as you write them. It is great for messages, scripts, notes, config blocks, and certificates. If you want YAML to remember your text layout, use the pipe.

What is the YAML pipe operator?

The YAML pipe operator is the | symbol. In YAML, it is called the literal block scalar. That sounds fancy. But the idea is simple.

It tells YAML:

• “This value is a block of text.”
• “Keep the line breaks.”
• “Do not squash my text into one line.”

Here is a tiny example:

message: |
  Hello there!
  Welcome to YAML.
  Please enjoy your stay.

The value of message becomes:

Hello there!
Welcome to YAML.
Please enjoy your stay.

See that? The lines stay separate. YAML does not mash them together like a potato.

Why does YAML need this?

YAML is often used for configuration files. These files can contain more than simple values like true, 42, or banana.

Sometimes you need long text. Sometimes you need a script. Sometimes you need a beautiful tiny poem for your robot server. The pipe operator helps with all of that.

Without the pipe, long text can become hard to read. You may need quotes. You may need escape characters. You may get sad. The pipe makes it neat.

Basic syntax

The basic pattern looks like this:

key: |
  line one
  line two
  line three

There are two important rules:

1. The pipe goes after the key and colon.
2. The text block must be indented.

Indentation matters a lot in YAML. YAML is like a very strict librarian. It wants things lined up nicely.

This is correct:

description: |
  This is a product.
  It is shiny.
  It has many buttons.

This is wrong:

description: |
This is a product.
It is shiny.

The text must be indented under the key. Usually two spaces are used. Do not use tabs. YAML does not like tabs. Tabs make YAML grumpy.

Example 1: A welcome message

Let us make a friendly app message.

app:
  welcome: |
    Hello, user!
    Thanks for opening the app.
    Today is a great day to click buttons.

This is useful because the message stays readable in the file. It also stays readable when your app uses it.

If you used a normal string, it might look messy:

welcome: "Hello, user!\nThanks for opening the app.\nToday is a great day to click buttons."

Yikes. That is not fun. The pipe version is kinder to your eyes.

Example 2: A shell script

The pipe operator is very popular in CI files. That means files used by build tools, test tools, and deployment bots.

Here is a script inside YAML:

deploy_script: |
  echo "Starting deploy"
  npm install
  npm test
  npm run build
  echo "Deploy complete"

Each command stays on its own line. That is exactly what scripts need. Your robot worker can read the steps in order.

Example 3: Email text

You can also use the pipe for emails.

email:
  subject: Welcome!
  body: |
    Hi Alex,

    Welcome to our platform.
    We are happy you are here.

    Cheers,
    The Team

Notice the blank lines. The pipe keeps them. This matters for email layout. Nobody wants an email that looks like one giant noodle.

The pipe keeps newlines

This is the big thing to remember. The pipe preserves line breaks.

For example:

text: |
  red
  green
  blue

That value is stored like this:

red
green
blue

There is also a final newline at the end by default. That means YAML usually adds one last line break after the final line. This is normal.

What are |- and |+?

The plain pipe is not alone. It has tiny cousins. They control what happens at the end of the block.

• | keeps one final newline.
• |- removes the final newline.
• |+ keeps extra final newlines.

Let us see them.

Using |

text: |
  hello

This becomes:

hello

There is a newline after hello.

Using |-

text: |-
  hello

This becomes:

hello

No final newline. It stops right after the word.

Using |+

text: |+
  hello

This keeps the extra blank lines at the end. This is less common, but useful when exact text matters.

Pipe versus greater than

YAML also has another symbol: >. It is called the folded block scalar. It looks similar, but it behaves differently.

The pipe keeps line breaks. The greater than sign folds many line breaks into spaces.

Pipe example:

text: |
  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.

Greater than example:

text: >
  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.

Use | when line breaks matter. Use > when you want readable wrapping in YAML, but one paragraph in the result.

Common uses for the pipe operator

The YAML pipe operator is handy in many places. Here are common examples.

• Scripts: Shell commands, setup steps, deploy commands.
• Messages: Welcome notes, error text, help text.
• Emails: Templates with blank lines and signatures.
• Certificates: Text blocks that must keep exact line breaks.
• Markdown: Documentation snippets inside config files.
• SQL: Queries that look better over many lines.

Here is a SQL example:

query: |
  SELECT id, name, email
  FROM users
  WHERE active = true
  ORDER BY name;

This is much nicer than one long line. Your future self will thank you. Maybe with cake.

Watch the indentation

Most YAML pipe problems come from indentation. The block belongs to the key above it. So it must be indented more than the key.

Good:

note: |
  Bring snacks.
  Bring water.
  Bring a tiny spoon.

Bad:

note: |
  Bring snacks.
 Bring water.
  Bring a tiny spoon.

The second line has the wrong spacing. YAML may fail. Or worse, it may confuse you first.

Keep indentation consistent. Use spaces. Pick two spaces or four spaces. Then stick with it.

When should you not use it?

The pipe is great, but you do not need it for every string.

Do not use it for simple values like this:

name: Luna
city: Paris
status: active

These are already clear. Adding pipes would make the file bigger for no reason.

Use the pipe when text has structure. Use it when line breaks matter. Use it when humans need to read it easily.

Quick cheat sheet

• | means “keep line breaks.”
• |- means “keep line breaks, but remove the final newline.”
• |+ means “keep line breaks and extra ending blank lines.”
• > means “fold lines into a paragraph.”
• Indent block text under the key.
• Use spaces, not tabs.

Final thoughts

The YAML pipe operator is a small symbol with a big job. It lets your text breathe. It keeps line breaks where you put them. It makes scripts, messages, and templates much easier to read.

So when YAML text starts looking squished, messy, or full of weird \n symbols, call the pipe. It is the tiny vertical hero of clean configuration files.