Source: https://contributors.home-assistant.io/writing/reference/yaml/ (formerly
developers.home-assistant.io/docs/documenting/yaml-style-guide). Archived 2026-10-25 as a close
summary with short quotes (the fetch tool returns summaries, not verbatim pages).
- Indentation: 2 spaces.
- Booleans: only lowercase
true and false. "Values like yes, no, on, and off look friendly,
but they confuse people who are new to YAML"; YAML 1.2 dropped them as booleans.
- Comments: "Put the comment on its own line, above the line it explains." Rationale: "Comments at the
end of a line get hard to read on small screens." "Indent the comment at the same level as the line
it belongs to." "Put a space after the #, and start the comment with a capital letter." Purpose:
"Comments help the reader understand what an example does."
- Lists: block style, each item under its key; avoid flow style (square brackets) - "It looks compact,
but it gets hard to read once the values grow." If used: a space after each comma, none inside the
brackets.
- Mappings: "Always write mappings in block style. Flow style, which looks like JSON, is not allowed."
- Null values: leave empty rather than
null or ~.
- Strings: double quotes; long text in block scalars (
| keeps line breaks, > folds them) instead
of \n escapes or long single lines. No numeric line-length limit.
- Omit options at their default values and empty sections, unless the example is about them.
- Placeholders in capitals with underscores (
YOUR_API_KEY); fixed identifiers stay unquoted.
- A single value when there is one, a block list when there are several (no comma-separated strings).
- Split long templates over lines with a block scalar so the reader can follow the logic.