| name | yaml-conventions |
| description | YAML formatting conventions (block style only, no flow style, no |
YAML formatting
Applies everywhere YAML appears: manifests, Helm charts/values, GitHub Actions
workflows, docs, and example snippets in README.md.
-
Never use flow style (inline {...} / [...]) in YAML. Always write
block style, one key per line. For example, write
applications:
kubeflow:
enabled: true
not kubeflow: { enabled: true }. The only acceptable inline form is an
intentionally empty collection ({} / []).
-
Never write inline arrays. A sequence must use block style, one item per
line with a leading - , even for a single element. Write
ports:
- "11434:11434"
command:
- /bin/sh
- -c
not ports: ["11434:11434"] or command: ["/bin/sh", "-c"]. The only
exception is an intentionally empty list ([]).
-
Never open a file with ---. The document start marker is optional in
YAML, means nothing for a single-document file, and every tool reads the file
identically with or without it. Start on the first key, or on the leading
comment:
apiVersion: v1
kind: Namespace
not a bare --- on line 1. The separators between documents in a
genuinely multi-document file are a different thing — required syntax, keep
them. Markdown/skill frontmatter delimiters are not YAML documents either;
leave those alone.
Enforce all of the above with a yamllint hook (document-start: present: false, braces / brackets forbid: non-empty) rather than by review — see
pre-commit-conventions for the hook and the config.
