YAML Formatter

How the YAML formatter works

This formatter does not re-indent your text line by line. When you click Format, it loads the YAML into JavaScript data with js-yaml 4.1.0 and then serializes that data again with jsyaml.dump, using 2-space indentation and no line wrapping. The result is YAML written in one consistent style, whatever style the input used. If the input cannot be parsed, you get js-yaml's error message with the line and column instead of output.

Rebuilding from data has a clear benefit: the output is guaranteed to parse, and flow-style snippets like {app: web} or [80, 443] are expanded into normal block style. It also has a cost, covered below: anything that is not data, such as comments, is gone.

Example: tidying a Kubernetes manifest

A Deployment with a mix of flow style, unindented lists, and a comment:

apiVersion: apps/v1
kind: Deployment  # web frontend
metadata:
  name: web
  labels: {app: web}
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: web
        image: "nginx:1.27"
        ports: [{containerPort: 80}]
        env:
        - {name: DEBUG, value: "false"}

is formatted as:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80
          env:
            - name: DEBUG
              value: 'false'

Every list is now indented under its key, inline maps are expanded, and unnecessary double quotes around nginx:1.27 are removed. The quotes around 'false' stay, because without them the value would become a boolean, and Kubernetes requires environment variable values to be strings. The comment on the kind line is removed.

What changes besides whitespace

Because the output is regenerated from parsed data, check these before committing a formatted file:

• Comments are removed, including commented-out settings you meant to keep.
• Merge keys are expanded. <<: *defaults is replaced by a copy of every key from the anchored map. When the same map is used in several places, js-yaml writes it once with an anchor and refers back to it, but renames the anchor to &ref_0, &ref_1, and so on.
• Dates become timestamps. released: 2024-01-15 comes out as released: 2024-01-15T00:00:00.000Z. Quote dates you want kept as text.
• Numbers are normalized. python: 3.10 becomes 3.1, zip: 02134 becomes 2134, and 0x1F becomes 31. Version numbers and IDs with leading zeros must be quoted to survive.
• Quote style changes. Double quotes are dropped where they are not needed and single quotes are used where they are. YAML 1.1 boolean words such as yes, no, on and y get quoted ('on': push in a GitHub Actions file) so older parsers do not misread them.
• Folded blocks are joined. A > block is loaded as one line of text and written back as a literal | block holding that single line.

Errors you will see

• "tab characters must not be used in indentation": YAML indentation must be spaces. Replace tabs, which often come from pasting out of a Makefile or a chat message.
• "bad indentation of a mapping entry": a key is indented further or less than its siblings, or a value contains : without quotes, as in title: Note: read this. Quote the value.
• "duplicated mapping key": the same key twice in one map. js-yaml rejects it rather than silently keeping the last value.
• "unidentified alias": a value that starts with *, such as glob: *.txt, is read as a reference to an anchor. Quote it.

Limitations

• One document per run. A stream with --- separators is rejected.
• Indentation is fixed at 2 spaces, and key order is kept as written (no sorting).
• Templated YAML such as Helm charts or Jinja files is not YAML until rendered. {{ .Values.name }} either fails or is silently parsed as a nested map.
• There is no keyboard shortcut for Format. F11 toggles fullscreen and Esc exits it.

When to use a different tool

• To check a file without rewriting it, and keep your comments, use the YAML Validator.
• To see exactly how values are typed after parsing, convert with YAML to JSON.
• To generate YAML from a JSON payload, use JSON to YAML.

Frequently asked questions

Why did the formatter remove my comments?

The formatter parses your YAML into data with js-yaml and then writes that data back out. Comments are not part of the data, so they are lost. Keep a copy of the original if the comments matter, or use the output only as a reference for fixing indentation.

Why were some values wrapped in quotes?

Strings such as 'yes', 'no', 'on', 'off', 'y' and 'NO' are quoted so that older YAML 1.1 parsers (PyYAML, older Ruby and Go libraries) do not read them as booleans. Strings that look like numbers, such as '123' or 'false', are quoted for the same reason.

Can I choose 4-space indentation?

No. Output always uses 2 spaces per level, with list items indented under their parent key. Long lines are never wrapped.

Does it support files with several documents separated by ---?

No. Only a single YAML document is accepted. A file with more than one document fails with "expected a single document in the stream, but found more". Format each document separately.

Is my YAML uploaded or stored?

It is not uploaded: parsing and formatting run in your browser. The editor does save its contents to your browser's local storage every two minutes (and when you press Ctrl+S) so the text can be restored on your next visit. Click Clear to remove it.