YAML Cheatsheet - YAML Syntax Reference

Across Docker Compose, Kubernetes and GitHub Actions, the most common mistakes are wrong indentation, a missing space after the colon, and unquoted special characters. This reference arranges the 8 most-used syntax groups (basics, data types, lists and dicts, multiline strings, anchors and aliases, type tags) by purpose: mirror the scaffolding when writing config, and debug indentation or quoting section by section when an error appears. It also notes where YAML differs from JSON — single quotes do not escape, comments are allowed, and anchors cut repetition. After reading you can write clean, maintainable config files on your own.

Config Formats·54 commands·Last updated 2026-07-21

Basic Syntax 8

key: value

Key-value pair (space required after colon)

# comment

Single-line comment

---

Document separator (for multi-doc files)

...

Document end marker

string

String (quotes not needed by default)

"string" / 'string'

Double quotes (escapes) / single quotes (no escapes)

key: "value: with colon"

Quote values with special chars (: # etc.)

key with spaces: value

Key names may contain spaces (no quotes needed)

Data Types 8

null / ~

Null / ~

true / false

Boolean

123 / 0x1A / 0o17 / 0b1010

Integer (decimal/hex/octal/binary)

3.14 / .inf / -.inf / .nan

Float (inf/-inf/nan)

2026-07-19

Date (ISO 8601)

2026-07-19T10:30:00Z

Datetime (UTC)

2026-07-19T10:30:00+08:00

Datetime with timezone

!!binary "aGVsbG8="

Binary data (base64)

List / Array 6

- item1\n- item2

Block-style list

[item1, item2]

Flow-style list (inline)

fruits:\n - apple\n - banana

Nested list

items: []

Empty list

matrix:\n - [1, 2]\n - [3, 4]

List of lists

users:\n -\n name: tom\n age: 20

List of dicts

Dictionary / Object 6

key1: value1\nkey2: value2

Block-style dict

{key1: value1, key2: value2}

Flow-style dict (inline)

person:\n name: tom\n age: 20

Nested dict

person: {name: tom, age: 20}

Flow-style nested dict

config: {}

Empty dict

server:\n host: localhost\n ports:\n - 80\n - 443

Dict and list mixed nesting

Multiline String 7

text: |\n line1\n line2

Keep newlines (Literal block)

text: >\n line1\n line2

Fold newlines into spaces (Folded block)

text: "line1\nline2"

Explicit newline inside double quotes

text: |-\n line1\n line2

Keep newlines, drop trailing newline (- chomp)

text: |+\n line1\n line2

Keep newlines, keep trailing blank (+ chomp)

text: |2\n line1\n line2

Explicit indentation indicator (2 spaces)

text: >-\n line1\n line2

Fold newlines and drop trailing newline

Anchors & Aliases 6

default: &default\n key: value

Define an anchor (&)

env: *default

Reference an anchor (*)

env:\n <<: *default\n extra: value

Merge an anchor into the current dict (<<)

list: &list [a, b, c]

Define an anchor for a list

copy: *list

Reference a list anchor

config:\n <<: [*base, *override]

Merge multiple anchors (later overrides earlier)

Type Conversion 8

key: !!str 123

Cast integer to string "123"

key: !!int "42"

Cast string to integer 42

key: !!float "3.14"

Cast string to float

key: !!bool "yes"

Cast string to boolean

key: !!timestamp "2026-07-19"

Cast string to timestamp

key: !!null ""

Cast empty string to null

key: !!seq {}

Explicitly declare a sequence type

key: !!map []

Explicitly declare a mapping type

Real-world Examples 5

services:\n web:\n image: nginx:latest\n ports:\n - "80:80"

Docker Compose service definition

steps:\n - name: Checkout\n uses: actions/checkout@v4

GitHub Actions step

apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: my-app

Kubernetes resource definition

---\ntitle: My Post\ndate: 2026-07-19\n---

Front Matter (post metadata)

env:\n DATABASE_URL: postgres://localhost/mydb

Environment variable config

Typical Use Case

People who write Docker Compose, Kubernetes, GitHub Actions or any YAML config face two recurring scenarios: building a runnable config from scratch, or pinpointing a syntax error when it fails. For a compose file, the port "8080:80" must be double-quoted or it parses as a sequence; to reuse a common block across services, define it once with an anchor (defaults) and merge it in with << instead of copying the whole block. Consulting this table, you can write structurally correct YAML on your own and quickly tell whether an error is indentation, a missing space after the colon, or missing quotes.

Command Examples

Reuse a common block with anchor merge

defaults: &defaults\n replicas: 2\n image: nginx:1.25\n env: production\n\napp:\n <<: *defaults\n name: web

&defaults 定义锚点，<<: *defaults 把公共字段合并进 app；显式写的 name: web 覆盖同名锚点键。多服务复用公共配置时可避免逐段复制。

Output

解析后等价于：\napp:\n  name: web\n  replicas: 2\n  image: nginx:1.25\n  env: production

Quote port mappings in Docker Compose

services:\n web:\n image: nginx:latest\n ports:\n - "8080:80"\n environment:\n NGINX_PORT: "80"

ports 里的 "8080:80" 必须加双引号，否则冒号加数字会被解析成序列语法而报错；environment 中的值想保留字符串语义时同样建议加引号。

Common Pitfalls

Indentation must stay consistent — never mix space counts or use Tab within the same level, or the parser errors or nests deeper than intended.
A space is required after the colon (key: value); otherwise the whole line is treated as a string and the config silently does nothing.
Quote values that begin with special chars such as : # @, or they are parsed as tags, comments or anchor syntax.
Dates and numbers are auto-typed (2026-07-19 parses as a Date); add quotes when you want string semantics.
The << merge is overridden by explicit keys: an explicit definition always wins, so do not rely on an anchor to overwrite a written value.

Tips

YAML is indentation-sensitive: use spaces, not Tab, and align the same level.
A space is required after the colon (key: value), or it parses as a string.
Use | to keep newlines and > to fold them (good for long paragraphs).
Quote strings containing special chars (: # @ ` etc.) to avoid parse ambiguity.
Anchors & define, aliases * reference, << merges - reduces repeated config.
Multi-document files use --- separators, common in Front Matter and CI/CD.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

YAML Spec

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.