YAML Formatter

YAML files rot in a specific way. Six people edit the same Kubernetes manifest, three of their editors disagree about indentation, someone pastes a block indented with four spaces into a file using two, and a list ends up half in flow style and half in block style. Nothing is broken — YAML is forgiving about most of this — but the file has stopped being readable, and in a language where indentation is the structure, unreadable is one bad paste away from an outage.

This formatter rebuilds the whole document with consistent indentation and consistent style, and it keeps your comments. That last part is not a small detail: most online YAML formatters are built on js-yaml, which parses to a plain object and throws every comment away, so running your manifest through one silently deletes the annotations explaining why replicas is 4. This tool uses the yaml package's document model, which round-trips comments — including the header block at the top of the file and the trailing note at the end of a line.

Comments survive. That is the whole point.

The formatter parses your input into a document tree that keeps comments attached to the nodes they belong to, then re-serialises that tree. In practice this means:

• Header comments at the top of the file stay at the top.
• Line comments — the # at the end of a value — stay on their line, next to that value.
• Standalone comments between keys stay where they were, in the same position in the sequence.
• Anchors and aliases (&default and *default) are preserved as anchors and aliases rather than being expanded into duplicated content.

Try the same document in a js-yaml-based formatter and compare. The output will be structurally correct and every explanatory comment will be gone — which is why so many teams stopped running their manifests through online formatters at all.

What formatting normalises

Because this is a parse-and-reprint rather than a whitespace tweak, some things are rewritten into a canonical form. Indentation becomes uniform at your chosen width. Inconsistent list indentation is regularised. Flow-style collections written inline, such as {cpu: 250m, memory: 512Mi}, are expanded into block style when the document is reprinted, which is nearly always what you want in a file a human maintains.

Quoting is normalised too: strings that need quotes get double quotes, and strings that never needed them lose them. This is safe but occasionally surprising — "1" stays quoted because unquoting it would turn it into a number, while "production" may lose its quotes because it cannot be read as anything else.

Long lines are not wrapped. Line width is set to unlimited deliberately, because YAML's automatic line folding inside plain scalars is a reliable source of confusion, and a wrapped URL or a folded command string is much harder to read and to grep than a long line.

Empty and null values are rendered as an empty value rather than the literal word null, matching the style used across Kubernetes and most CI configuration.

YAML 1.2 and the Norway problem

This tool parses YAML 1.2 with the core schema, which is what modern tooling uses and what you should assume. The practical difference from YAML 1.1 is the boolean set. Under 1.1, yes, no, on and off were booleans — which is the origin of the notorious "Norway problem", where a country list containing NO silently produced false. Under 1.2, only true and false are booleans, and no is the string it looks like.

This matters when you are formatting a file that will be read by something else. Some consumers, including certain older Ruby and Python toolchains, still apply 1.1 rules. If a value must be a string, quote it explicitly — "no", "off", "3.10" — and the ambiguity disappears for every parser regardless of version.