YAML Formatter
Reformat YAML while retaining comments, anchors, aliases, directives, tags, and document boundaries where possible.
Multi-document streams are supported. Duplicate mapping keys are treated as errors rather than silently normalized.
YAML formatting is a rewrite, not just indentation
JSON can be prettified by changing insignificant whitespace around tokens. YAML presentation is richer: indentation, block versus flow collections, quote style, scalar folding, comments, directives, anchors, aliases, and document markers all participate in the source text.
The input is parsed into the library's document model and serialized again with the chosen indentation and line width. That keeps YAML-specific structure available to the serializer instead of first collapsing the document into plain JavaScript values.
Why the Document Model Matters for Comments and Aliases
# shared limits limits: &defaults cpu: 500m memory: 512Mi worker: limits: *defaults
If that file is immediately converted to a normal JavaScript object, the comment has nowhere to live and the alias relationship may be resolved into repeated data. A YAML document/AST representation can carry more of the original YAML-specific information through the formatting operation.
“Preserved where possible” is still the important qualifier. Serialization can normalize whitespace and scalar presentation, so formatting should not be treated as byte-for-byte preservation. The yaml library documentation also notes that comment attachment is not perfectly stable, especially around trailing comments. Review the diff when comments carry operational meaning.
Line Width Is a Presentation Preference, Not a Maximum-Line Guarantee
The underlying yaml package treats lineWidth as a soft maximum; setting it to 0 disables folding. YAML cannot safely wrap every long value at an arbitrary column, so a long scalar may still exceed 80 or 120 characters.
Choose 80 or 120 when your repository has a readability convention. Choose no wrapping preference when keeping long scalar presentation matters more than targeting a particular width.
A formatting pass can create a large diff
Quote choices, block styles, blank lines, sequence indentation, and wrapping can all change at once. That can make a simple formatting pass look like a substantial configuration edit in version control.
For production Kubernetes, Compose, CI, or application config, format on a clean branch and inspect the diff before committing. Avoid mixing broad formatting with an unrelated behavior change when reviewers need to understand exactly what changed.
Keep mapping order for maintainers, not application meaning
Teams often keep metadata, image, ports, environment, resources, or other related configuration close together. Alphabetizing keys should be a separate choice because the human grouping can carry maintenance value.
Key sorting is intentionally left out. Reformatting and reorganizing a configuration are separate edits and are easier to review when kept separate.
Directives, Tags, Anchors, and Merge Behavior Deserve a Diff Check
YAML can declare a version, define tag handles, attach tags to nodes, and connect nodes using anchors and aliases. Some applications also support merge-key conventions. These are exactly the kinds of files where “it still parses” is not enough reason to replace the original without inspecting the rendered output.
The YAML 1.2.2 specification defines directives, tags, anchors, aliases, and the separation between presentation details and the representation model. When the target application disagrees, its own parser and schema rules still decide what it accepts.
A YAML version change can change plain-scalar meaning
Without an explicit %YAML directive, the parser defaults to YAML 1.2 and its core schema. YAML 1.1 resolves some familiar plain scalars differently: values such as yes, no,on, and off can become booleans instead of strings. A formatting pass cannot prove that a different runtime will resolve every scalar the same way.
If the destination has a fixed parser or schema, validate the formatted file with that same stack before replacing production configuration.
Valid and Nicely Formatted YAML Can Still Be Invalid for Its Destination
A Kubernetes Deployment, Docker Compose file, GitHub Actions workflow, Ansible playbook, or application config has rules beyond YAML syntax. Required fields, allowed enum values, cross-references, API versions, and runtime constraints belong to the consuming product.
Use formatting to make the YAML maintainable. Use a product-specific validator when you need to know whether the configuration is actually acceptable.
Template Source Is a Special Case
Helm, Jinja-style templates, CI expressions, and other generators may insert syntax that is not ordinary YAML until after rendering. Running generic YAML formatting directly over the template source can fail or can rearrange text in a way the template engine did not expect.
When the file is generated, format the rendered YAML unless the template system explicitly supports YAML-aware formatting for its source language.