Understanding YAML formatting
Indentation as syntax — done right.
A formatter for YAML normalises the things humans tend to get wrong: indentation depth, quoting, list markers.
YAML's two collection shapes.
YAML expresses dictionaries (mappings) and lists (sequences) two ways each: block form using indentation and dashes, or flow form using braces and brackets that mirror JSON. Block form reads like prose; flow form reads like JSON. The formatter prefers block form for top-level structure — that's what humans came to YAML for.
Two spaces, no tabs.
The YAML spec forbids tabs in indentation. Two-space indentation is the de-facto standard: Kubernetes, Helm, GitHub Actions, OpenAPI, Ansible, Hugo all use it. The formatter normalises any input to two spaces regardless of how the source was written.
Quoting — when and why.
YAML lets you write strings unquoted, single-quoted, or double-quoted. Unquoted is most readable, single-quoted treats backslashes as literal, double-quoted allows escape sequences. The formatter quotes only when necessary — when a value could be misread as a boolean (yes, no), a number (1.0), or a date.
Anchors, aliases, and merge keys.
YAML lets you name a node with &name and reference it elsewhere with *name, optionally merging it into a mapping with <<: *name. These deduplicate repeated structures in long YAML files. The formatter preserves them — it won't expand or eliminate the references.
Multi-document files.
A single .yaml file can contain multiple documents separated by ---. Kubernetes manifests use this constantly — one file with a Deployment, a Service, and an Ingress. The formatter handles each document independently and preserves the separators.