YAML looks simple until you spend an hour hunting for a missing indent in a 400-line Kubernetes manifest. This tool parses your YAML (1.2 spec, plus common 1.1 quirks), reformats it, and yells at you when something is structurally broken.
Indentation is the single thing that trips people up. YAML only understands spaces for indentation, tabs throw a hard error. Most of the community settled on 2 spaces per level; the formatter defaults to that. If your file mixes 2-space and 4-space indentation at different nesting depths, every key lands in the wrong mapping.
Paste in a mess like:
services:
web:
image: nginx:latest
ports:
- "80:80"
environment:
- DB_HOST=db
- DB_PORT=5432
and the parser immediately points you at the over-indented ports and the misaligned environment list item.
Gotcha: YAML's type coercion is aggressive and version-dependent. The string "no" becomes the boolean false in YAML 1.1 (which many parsers still follow). Version floats like "1.10" silently become 1.1. If you've ever pinned a dependency version and watched your CI break, this is why. The formatter's type-inference panel shows exactly what each scalar resolves to, so you can slap quotes around "1.10" or "no" before it bites you.
A few things worth knowing:
-
Anchors (
&) and aliases (*) are preserved -- formatting does not expand them. There is an "expand aliases" toggle if you inline them, but remember it can change semantics when the same node is referenced from multiple places. -
Multi-line strings come in two flavors: literal blocks (
|, keeps every newline) and folded blocks (>, collapses single newlines into spaces). The formatter picks the right one based on content. A folded block containing hard-wrapped code is a bug magnet, double-check after formatting. -
Comments are retained and attached to whatever node follows them. Reordering keys (sort-alphabetically mode) drags comments along. Standalone comment blocks in the middle of a mapping land on the next key down -- that is a formatting artifact, but the parser tolerates it.
-
Multi-document streams (
---separators) are kept intact. Each document formats independently.
If you work with anything machine-facing -- Docker Compose, GitHub Actions, Ansible, Prometheus rules, Swagger/OpenAPI -- this normalizes it to the same readable shape before you commit. Net result: diffs in code reviews show only real changes, not re-indentation noise.