Understanding Non-Destructive YAML Formatting
YAML (YAML Ain't Markup Language) is the backbone of modern DevOps, Infrastructure-as-Code (IaC), and cloud configurations. However, standard YAML beautifiers often destroy critical document structure by stripping comments (#), expanding anchors (&) and aliases (*), or ruining line breaks in multiline scripts (|).
Why Standard Formatters Destroy Comments and Anchors
Most basic web formatters parse YAML into generic JavaScript objects via JSON.parse or basic js-yaml.load() functions. Because native JSON data structures do not support comments or node pointers, all documentation is lost during serialization. Our YAML Formatter uses a round-trip AST engine built on Eemeli Aro's yaml package, preserving comments, anchors, and original scalar representations.
YAML Indentation Rules & Whitespace
YAML relies strictly on spaces for block indentation; tab characters are illegal in YAML 1.2. The industry standard across Kubernetes, Docker, and Ansible is 2 spaces per indentation level. Our tool automatically converts illegal tab characters into spaces while preserving visual block alignment.
Multiline Block Scalars: Literal (|) vs Folded (>)
- Literal Block (
|): Preserves newlines exactly as written. Used for shell scripts, SQL queries, and certificates. - Folded Block (
>): Folds line breaks into single spaces. Used for long readable descriptions and sentences.
Ecosystem-Specific Formatting Profiles
- Kubernetes: Canonical key order
apiVersion→kind→metadata→spec. - Docker Compose: Service-level ordering
version→services→image→ports→environment. - GitHub Actions: Workflow order
name→on→jobs→steps(withrun: |script protection). - Ansible: Task list ordering starting with
- name:followed by module actions and Jinja2 template quoting.