Overview
Introduction
Key order in a hand-edited YAML file tends to drift, new fields get appended wherever it was convenient at the time, not in any particular order. Over time that makes documents harder to scan and diffs harder to review. This tool alphabetizes every mapping's keys, recursively, so key order stops being noise.
It's a purely structural transformation: since YAML mappings are unordered by spec, sorting keys never changes what the document means, only how it reads.
What Is YAML Sorter?
A YAML key sorter walks a parsed document and, at every mapping (at any depth), reorders its keys alphabetically before re-serializing.
An optional setting extends this to scalar-only sequences too, alphabetizing a list of plain strings or numbers, while always leaving lists of objects in their original order, since there's no single obviously 'correct' sort key for a list of mappings.
How YAML Sorter Works
The input is parsed into its underlying value, then walked recursively. Every mapping's keys are sorted with a standard locale-aware string comparison before its values are (also recursively) processed. If the array-sorting option is enabled, sequences where every item is a scalar are also sorted the same way.
The sorted value is re-serialized with the same block-style YAML stringifier used by the formatter, so indentation and quoting stay consistent with this site's other YAML tools.
When To Use YAML Sorter
Use it before committing a YAML file to normalize key order across a team, so future diffs reflect actual changes rather than reordering.
It's also useful when comparing two versions of a config by eye, alphabetized keys make it much easier to spot a specific field.
Often used alongside YAML Formatter & Prettifier, YAML Flattener and YAML Diff Checker.
Features
Advantages
- Never changes the document's meaning, since mapping key order is not semantically significant in YAML.
- Recursively sorts every nesting level, not just the top of the document.
- Optional array sorting is scoped to scalar-only lists, avoiding the ambiguity of sorting objects.
- Runs entirely client-side, so configuration values never leave your browser.
Limitations
- Comments are not preserved, since the transformation parses and re-serializes the document, the same tradeoff as the YAML Formatter.
- Lists of objects are never reordered by this tool, even with array sorting enabled, since picking a sort field automatically would be a guess.
- Sorting uses a standard string comparison, which may not match every locale's specific alphabetization rules for accented or non-Latin characters.
Examples
Best Practices & Notes
Best Practices
- Agree on a sorting convention as a team before adopting this in a workflow, so diffs stay minimal going forward rather than one-time noisy.
- Leave array sorting off for lists where order is meaningful (like a sequence of deployment steps), only enable it for genuinely unordered scalar collections (like a list of tags).
- Run this before diffing two versions of a config with the YAML Diff tool, so the diff reflects real changes, not just reordering.
Developer Notes
Sorting uses `Array.prototype.sort` with `String.prototype.localeCompare` for both mapping keys and (when enabled) scalar arrays, applied recursively depth-first so nested mappings are sorted independently of their parent's key order. Arrays are only sorted when every element is a non-object scalar, checked with a simple `every()` guard before sorting.
YAML Sorter Use Cases
- Normalizing key order across a team before committing shared configuration
- Making a large config easier to scan by alphabetizing its keys
- Reducing diff noise when comparing two versions of a document with different key insertion order
- Preparing a canonical, sorted form of a config for documentation
Common Mistakes
- Enabling array sorting for order-sensitive lists (like a sequence of build steps) and breaking their intended execution order.
- Expecting comments to survive sorting, they don't, since the document is fully parsed and re-serialized.
- Assuming lists of objects get sorted too, they never do, regardless of the array-sorting option.
Tips
- Combine with YAML Formatter if you also want consistent indentation alongside sorted keys.
- Use YAML Diff after sorting both sides of a comparison to confirm the diff reflects real value changes, not reordering.
- If a list's order genuinely doesn't matter (like a set of feature flags), enabling array sorting can make it easier to check for duplicates or missing entries at a glance.