YAML Formatter & Re-indenter

YAML formatter and re-indenter

Paste YAML with inconsistent indentation, stray tabs or untidy spacing and get back a normalised document. This is the quick fix for config files — Docker Compose, Kubernetes manifests, GitHub Actions workflows, Ansible playbooks — that have drifted into mixed two- and four-space indents or picked up a tab that breaks the parser.

Re-indentation rules

The formatter is a dependency-free re-indenter, not a full parser, which keeps it fast and lossless. It works in three steps:

1. Expand tabs to spaces — YAML disallows tabs for indentation, so every tab becomes two spaces.
2. Detect and normalise depth — it measures the leading-space depth of each line, finds the smallest positive gap between distinct depths as your source step, then snaps every nesting level onto your chosen 2- or 4-space unit.
3. Tidy spacing — it collapses runs of spaces after the first key: colon and after a list - .

Lines inside a | or > block scalar are detected by being more indented than their key and are copied verbatim, so embedded scripts and text keep their exact layout. Keys, values and block contents are never changed — only whitespace.

Example

Messy input (note the mixed spacing and over-indented dashes):

name:    Gera Tools
tools:
  -   xml
  -   yaml
meta:
    runs: browser

Formatted with a 2-space indent:

name: Gera Tools
tools:
  - xml
  - yaml
meta:
  runs: browser

Everything runs in your browser as plain JavaScript, so your YAML — and any secrets in it — never leaves your device.

The most common sources of messy YAML indentation

Pasting from documentation. Code blocks in web pages, PDFs, and Markdown readmes often lose their consistent indentation when selected and pasted — especially when a page uses proportional fonts or when the copy includes leading spaces that get stripped. The result is YAML that looks correct visually in the browser but fails when pasted into a terminal.

Editors with mixed tab/space settings. Even with EditorConfig or explicit editor settings, a new contributor with a different setup can introduce tabs or different indent widths into a shared config file. The formatter normalises these without touching the values.

Machine-generated YAML. Templating systems (Helm, Jinja2, ERB) sometimes emit inconsistent indentation, particularly when a template generates a nested block conditionally. Formatting the output before committing to version control catches these issues.

Copy-paste between projects with different style conventions. One project uses 2-space, another uses 4-space — copying a block between them creates mixed indentation in the destination file that no parser will accept.

What a re-indenter cannot catch

Because this tool re-indents rather than parsing the full YAML data model, it cannot:

• Detect structural errors like a mapping key with no value, or an inconsistent mix of mappings and sequences at the same depth
• Handle YAML anchors and aliases (&anchor, *alias) — these pass through but are not resolved
• Parse multi-document files (multiple --- separators in one file)
• Validate against a schema

For structural validation, copy the formatted YAML into the YAML-to-JSON converter. If it fails to parse there, the structure — not the indentation — is the problem.

Why tabs break YAML

Unlike JSON or most programming languages, the YAML specification explicitly forbids tab characters for indentation. A tab in an indentation position causes a parse error in compliant YAML loaders. This is intentional: YAML relies on indentation to determine nesting, and tabs render at unpredictable widths in different contexts, making it impossible to determine depth reliably. The formatter converts every leading tab to two spaces before re-indenting, which fixes this class of error automatically.

Formatting is not validation — pair this with a linter

A re-indenter guarantees consistent layout; it cannot know that your replicas: "3" should have been a number, that a key is duplicated (later keys silently win in most parsers), or that an anchor is referenced before definition. For configuration that gates deployments — Kubernetes manifests, CI pipelines, docker-compose — run a semantic linter such as yamllint alongside formatting, and consult the YAML 1.2 specification when a construct behaves unexpectedly; the majority of “YAML bugs” are documented spec behaviours (implicit typing, merge keys, multi-document separators) rather than parser defects. The division of labour is clean: this tool makes files readable, the linter makes them safe, and the spec settles arguments.