YAML Comments & Multiline Strings: The Complete Syntax Guide

YAML Comments & Multiline Strings: The Complete Syntax Guide

Two things trip people up in YAML more than anything else: comments (because YAML has no block-comment syntax) and multiline strings (because there are five different ways to write one and they behave differently). This guide settles both.

Comments in YAML

YAML comments start with a hash # and run to the end of the line:

# This is a full-line comment
service: api        # this is an inline comment
replicas: 3

A few rules that matter:

The # must be preceded by whitespace when used inline. key: value#comment is not a comment — the # becomes part of the value. You need key: value #comment with a space before the hash.

There is no block comment. Unlike /* ... */ in other languages, YAML has nothing. To comment out multiple lines, prefix each with #. Most editors do this with a multi-line cursor or a "toggle comment" shortcut.

# replicas: 3
# debug: true
# these three lines

Comments are not data. They exist only in the source file. The moment you parse YAML into an object — or convert it with the YAML to JSON Converter — every comment is gone. This is why round-tripping config through JSON strips your documentation; see How to Convert JSON to YAML for the full list of what round-trips lose.

A # inside a quoted string is literal:

color: "#ff0000"    # the hash here is part of the value, not a comment

Multiline Strings: The Two Families

YAML gives you two block scalar styles, and the choice determines what happens to your newlines:

• Literal style | — keeps newlines exactly as written.
• Folded style > — folds newlines into spaces (wraps text into a paragraph).

Literal Style (`|`) — Preserve Newlines

Use | when line breaks matter: shell scripts, formatted text, embedded files.

script: |
  #!/bin/bash
  echo "Line one"
  echo "Line two"

Parses to the string:

#!/bin/bash
echo "Line one"
echo "Line two"

Every newline is preserved, and the indentation under script: is stripped (YAML uses the indentation of the first line as the baseline).

Folded Style (`>`) — Collapse to Spaces

Use > for long prose that you want to wrap in the source but read as one line — descriptions, log messages, commit text.

description: >
  This is a long description
  that spans several lines
  but renders as one paragraph.

Parses to:

This is a long description that spans several lines but renders as one paragraph.

Single newlines become spaces. A blank line in the source becomes a real newline in the output — that's how you create paragraph breaks in folded style.

Chomping Indicators: Controlling the Trailing Newline

Both | and > add a single trailing newline by default. You control that with a chomping indicator appended to the style character:

Example — strip the trailing newline so the value has none:

token: |-
  eyJhbGciOiJIUzI1Ni
  no-trailing-newline

This matters for things like keys, tokens, and hashes where a stray \n breaks comparison. If a secret "looks right but doesn't match," a trailing newline from clip-mode | is a prime suspect.

Quoting: The Third Way

For short multiline values you can also use quoted scalars. Double quotes allow escape sequences and line continuation with a backslash:

message: "line one\nline two"          # \n is an escaped newline
wrapped: "this is one long line that \
  continues without a real newline"

Single quotes are literal — no escapes processed — except '' for a literal single quote:

path: 'C:\Users\name'                  # backslashes stay literal
quote: 'it''s here'                     # '' → '

Putting It Together

# Deployment config
name: web-app

# Literal: preserves the shell script line by line
startup: |
  npm ci
  npm run build
  npm start

# Folded + strip: one-line description, no trailing newline
summary: >-
  A small web service that
  serves the marketing site.

# Quoted: special characters stay literal
windows_path: 'C:\app\bin'

Verify Your YAML

Indentation and block-scalar behavior are easy to get subtly wrong. The fastest check is to convert the YAML to JSON and inspect the actual string values — the YAML to JSON Converter shows exactly how your |, >, and chomping indicators resolved (you'll see the literal \n characters in the JSON output). Format the result with the JSON Formatter if you need a clearer view.

Quick Reference

• Comments use # to end of line; inline # needs a leading space. No block comment exists.
• Comments are stripped on parse/convert — they never survive a trip through JSON.
• | literal = keep newlines; > folded = newlines become spaces, blank line = paragraph break.
• Chomping: - strips trailing newlines, + keeps them, default keeps exactly one.
• A trailing newline from clip-mode | is a common cause of tokens/hashes that "look right but don't match."
• Confirm behavior by converting to JSON with the YAML to JSON tool.