document-start¶
What this rule does¶
Requires or forbids the YAML document start marker (---).
Why this matters¶
- Multi-document streams. Files containing more than one YAML
document need
---to separate them. - Explicit intent. Requiring
---even in single-document files makes the format unambiguous and clearly signals that the file is YAML rather than another similar markup.
Configuration¶
| Option | Default | Description |
|---|---|---|
present |
true |
When true, require a --- marker at the start of every document. When false, forbid it. |
Examples¶
Allowed (with present: true)¶
Reported (with present: true)¶
Allowed (with present: false)¶
After ryl check --fix (with present: true)¶
Automatic fixing¶
ryl check --fix adds a --- start marker to every document that lacks one when
present: true: at the top of the file for the first document, and after the
... that ends the previous document for a later one. A UTF-8 BOM, leading the
file or a later document, stays before the ---. A line-1 #! shebang or
cloud-init #cloud-config header stays first, with the --- inserted after it,
since the interpreter or cloud-init reads it from byte 0.
With present: false, --fix removes the first document's optional marker.
Content or a comment on the marker line moves to column one. Directives, empty
documents and stream separators retain their markers and remain reported.
Disable with:
ryl format shares the marker fixes through [format] document-start = "add"
or "remove"; see Conflicting lint rules.
Related rules¶
document-end— the matching rule for the...end marker.