Long Text & Multi-line

5 min read · Beginner
You will learn
  • When to use | (pipe) to keep line breaks exactly as typed
  • When to use > (fold) to merge lines into one paragraph
  • How to embed multi-line descriptions, scripts, or log messages

So far, all our values have been short — a name, a number, true or false. But sometimes you need to write a long description or a multi-line note. Maybe you want to document what a project does, or store a shell script inside your YAML.

YAML has two special symbols for this: the pipe | and the greater-than >.

The pipe symbol: | (keep line breaks)

The pipe means “keep every line break exactly as I wrote it.” Whatever you type on separate lines stays on separate lines:

description: |
·· This is my first semiconductor design project.
·· I am learning how to design a simple processor.
·· The goals of this project are:
·· - Learn about semiconductor design
·· - Practice using design tools
·· - Create a working processor
·· This project will take about 6 months to complete.
· = one space

Everything indented under description: | is the value. The line breaks, the blank line, the dashes — all kept exactly as you wrote them.

Use the pipe when line breaks matter: shell scripts, code snippets, release notes with bullet points, anything with structure.

The greater-than symbol: > (fold into one line)

The greater-than means “fold all my lines into one long paragraph.” Your line breaks become spaces:

summary: >
·· A beginner-friendly processor design project
·· that teaches the basics of semiconductor design
·· and takes about 6 months to complete.
· = one space

YAML reads this as one single sentence: “A beginner-friendly processor design project that teaches the basics of semiconductor design and takes about 6 months to complete.”

Use greater-than when you have a long paragraph that you want to wrap nicely in your YAML file but should be delivered as continuous text.

See the difference

Toggle between the two symbols below. The same text on the left — but look at how differently the computer reads it on the right:

Interactive: Pipe vs Fold

Toggle between | and > to see how YAML treats the same text

What you write in YAML
description: |
  This is my first project.
  I am learning chip design.

  It will take 6 months.
What the computer reads
This is my first project.
I am learning chip design.
 
It will take 6 months.
Line breaks preserved ✓

A helpful way to remember:

  • The pipe | looks like a wall that blocks lines from merging
  • The > points forward, pushing lines together into one

The indentation rule

One important detail: all the text after | or > must be indented at least one level deeper than the key. YAML uses the indentation to know where the text starts and ends:

project:
·· description: |
···· This text is indented 4 spaces.
···· It belongs to "description."
···· The blank line above is preserved too.
·· version: "1.0"
· = one space

Count the dots: description is at 2 spaces, its text content is at 4 spaces. When YAML sees version: back at the 2-space level, it knows the multi-line text is done.

Key takeaways

  • ✓ | preserves every line break — what you type is what you get
  • ✓ > folds lines into a single paragraph — line breaks become spaces
  • ✓ The text must be indented under the key
  • ✓ Use | for code and structured text, > for long descriptions
  • ✓ Remember: pipe = wall (blocks merging), > = push (joins lines)
← Previous Next: Putting It All Together →