TopolearnShell scripts in CI files, certificates and long descriptions all rely on block scalars.
Block scalars hold multi-line text without escaping. They start with an indicator on the key's line, and the content is the indented lines below.
- Literal
|keeps every line break exactly. Ideal for scripts, config snippets, PEM certificates. - Folded
>joins lines with spaces, turning each blank line into a newline. Ideal for long prose that you want to wrap in the source.
Both keep the text's relative indentation. The indentation of the first content line is stripped from all lines.
Chomping controls trailing newlines:
- default (clip): a single final newline;
|-or>-(strip): no final newline;|+or>+(keep): all trailing newlines kept.
If the first line of content starts with spaces, give an explicit indentation indicator: |2 means the content is indented two spaces relative to the parent.
In CI systems such as GitHub Actions, run: | is how you write multi-line shell steps. Note that > folding doesn't fold more-indented lines, which keeps code blocks inside folded text intact.
Inside block scalars nothing is special: #, :, quotes and backslashes are all literal text, which is exactly why they're convenient.
Example
script: |
echo "building"
make -j4
# this is part of the string, not a YAML comment
description: >
This long sentence is wrapped
in the file but becomes one line.
A blank line starts a new paragraph.
no_trailing_newline: |-
value
keep_newlines: |+
value
# parsed:
# script: 'echo "building"\nmake -j4\n# this is part of the string, not a YAML comment\n'
# description: 'This long sentence is wrapped in the file but becomes one line.\nA blank line starts a new paragraph.\n'
# no_trailing_newline: 'value'
# keep_newlines: 'value\n' (plus any blank lines that followed)Remember
- | keeps line breaks, > folds lines into spaces
- Add - to drop the final newline, + to keep all trailing newlines
- Everything inside a block scalar is literal text, including #
Watch out for
- Using > for a shell script, which joins the commands into one line.