Fix your YAML before it breaks your deployment
YAML is whitespace-sensitive. One wrong indent and your Kubernetes pod spec puts the env vars under the wrong container. Three spaces instead of two and your Docker Compose service inherits the wrong network. YAML doesn’t tell you something is wrong, it just interprets your mistake differently than you intended.
This formatter reads the whole document and writes it back out: consistent 2-space indentation (the standard), no trailing whitespace, uniform key: value spacing. Every value stays the same, numbers keep their exact spelling (0755 stays 0755), and a value that would read differently unquoted, like '8080:80' or 'yes', gets quotes. One trade-off: comments are removed, so keep your annotated original. Invalid YAML is reported with the line and column instead of being guessed at.
The places YAML goes wrong
Mixed indentation. One person uses 2 spaces, another uses 4, someone copy-pasted a snippet with tabs. The file still parses, but the structure might not be what anyone intended.
Trailing whitespace. Invisible characters after a value can cause subtle issues. Some YAML parsers are forgiving. Others aren’t.
Inconsistent key-value spacing. key:value, key: value, key: value, they all parse the same way, but inconsistency makes the file harder to scan visually.
When to format
Before docker-compose up. Before kubectl apply -f. Before git commit. Basically, before any tool reads your YAML, format it first.
Docker Compose: after editing services, volumes, and networks, formatting catches indentation issues before they cause mysterious container behavior.
Kubernetes manifests: a misindented field in a K8s manifest can silently create a valid-but-wrong resource. Format first, apply second.
CI/CD pipelines: GitHub Actions, GitLab CI, CircleCI workflows with multiple jobs and steps get complex. Formatting keeps them readable.
Ansible playbooks: large playbooks with nested tasks and handlers benefit from consistent formatting.
Team collaboration: when five people edit the same YAML file, formatting before committing prevents whitespace diffs from cluttering the PR.
YAML formatting rules to live by
Always 2-space indentation. It’s the standard across Kubernetes, Docker Compose, GitHub Actions, and most YAML tools. Tabs are not allowed by the YAML spec.
Quote strings with special characters. Unquoted strings containing colons, brackets, or things that look like booleans (yes, no, true) will surprise you.
Check the structure, not just the syntax. The formatter rejects invalid YAML, but a key nested under the wrong parent is still valid YAML. Read the output once before you apply it.
For converting between YAML and JSON, there’s the YAML to JSON and JSON to YAML converters.
FAQ
What does it normalize?
Indentation to 2 spaces per level, key: value spacing, list layout and quoting. Flow lists like [a, b] come out as block lists, and ~ comes out as null. Multiple documents separated by --- stay separate.
Does it preserve comments?
No. Comments are dropped from the output. If the comments matter, format a copy and move them back by hand, or fix the indentation directly in your editor.
Can it fix syntax errors?
No. It stops at the first error and shows its line and column, for example a duplicated key or an unclosed [. Fix that spot and format again.
Why is indentation so critical in YAML?
YAML uses indentation to define hierarchy, there are no brackets or braces. A line indented wrong belongs to a different parent, which changes the document’s meaning entirely.
Client-side?
Yes, your YAML stays in your browser. Safe for files with secrets and infrastructure details.