Presence
Whether a section must exist, and whether it may be empty: required, recommended, optional, required na, allowEmpty.
Ground control: If it isn't on the manifest, it isn't on the ship.
Quick reference
| Written as | Fails with | Applies to |
|---|---|---|
required | missing-section errorempty-section error | section |
recommended | missing-recommended-section warn | section |
optional | — | section |
na | missing-section errorneeds-content-or-na errormissing-media error | section, media |
allowEmpty | — | section |
A bare section with no presence flag is optional: validated when it is there, never required. optional says so explicitly, and next to a rule set (use=name optional) it switches the set's presence off.
Examples
required
Require the section to exist and to have real content (an empty heading fails).
A required section with content passes
<!-- mdv: section required -->
## Mission Context## Mission Context
The change validates generated flight notes.✓ passes
A missing required section is flagged
<!-- mdv: section required -->
## Mission Context## Crew Roster
Six crew, all aboard.✗ missing-section error · line 1
recommended
Warn (rather than error) when the section is missing, but still validate it when present.
A missing recommended section only warns
<!-- mdv: section recommended -->
## Flight Background## Mission Context
The change validates generated flight notes.✗ missing-recommended-section warn · line 1
optional
Never require the section; validate its content only if the author included it.
An absent optional section passes
<!-- mdv: section required -->
## Mission Context
<!-- mdv: section -->
## Away Team Notes## Mission Context
The change validates generated flight notes.✓ passes
na
Require real content OR the block's empty-state marker — for sections like visual evidence that sometimes genuinely don't apply.
N/A stands in for real content
<!-- mdv: section required na -->
## Viewscreen Captures## Viewscreen Captures
N/A: no cockpit display changed.✓ passes
An empty section needs content or an N/A marker
<!-- mdv: section required na -->
## Viewscreen Captures## Viewscreen Captures✗ needs-content-or-na error · line 1
allowEmpty
with required (or required na), the section must still exist but an empty body passes — for sections that are legitimately empty at times (a changelog's Unreleased).
An empty section passes when empty is allowed
<!-- mdv: section required allowEmpty -->
## [Unreleased]## [Unreleased]✓ passes
See also: Contracts