structure atoms
Scope-level constraints on a document or section's child sections.
Scope-level atoms on a document or section directive that constrain its child sections (not the section's own content). Not field rules — they drive the structure pass.
Atoms
| Atom | Syntax | Scope | Description |
|---|---|---|---|
ordered | ordered | document, section | The declared child sections must appear in the declared relative order. |
noExtraSections | noExtraSections | document, section | Closure: every child section must be one the schema declares here — no undeclared sections. |
strict | strict | document, section | Sugar for noExtraSections + ordered: exactly the declared sections, in the declared order. |
freeText | freeText | document, section | Opt this scope out of noExtraSections/strict — arbitrary extra child sections are allowed. |
occurs | occurs=<range> | section | This child section's cardinality (SPEC §3): 0..*, 1..*, N (exact), or N..M. min AND max are enforced; with a sibling heading.mask the matching headings select the instances, without one the exemplar heading is the literal selector. Replaces v1's repeat/repeat=N, which are compile errors. |
requiredWhen | requiredWhen.<key>=<value> / requiredWhen.checked="<label>" | section | This child section is required only when a condition holds: a frontmatter key equals a value (requiredWhen.<key>=<value>), or a matching checkbox is ticked (requiredWhen.checked="<label>"). |
forbiddenWhen | forbiddenWhen.front.<key>=<value> | section | The symmetric negative of requiredWhen: this child section must be ABSENT whenever frontmatter <key> equals <value>. Equality-only, front-matter only. |
exactlyOne | exactlyOne=<group-id> | section | This LITERAL child belongs to a sibling XOR group: the parent requires exactly one member sharing the same group id to be present, and emits one group-level diagnostic naming the group and its present members on zero or 2+. A member's own requiredWhen/forbiddenWhen evaluates first — only members currently permitted count toward the group. Groups are literal child sections only. |
exhaustive | exhaustive | section (a masked occurrence selector) | On a masked occurrence set: every real sibling heading at the selector's own declared level must match its mask or a declared literal sibling — anything else is an unmatched-instance-heading error. Independent of the parent's noExtraSections/freeText. |
Details
ordered
The declared child sections must appear in the declared relative order.
ordered · scope: document, section · src/pipeline/directives/atoms.ts
<!-- mdv: document ordered -->noExtraSections
Closure: every child section must be one the schema declares here — no undeclared sections.
noExtraSections · scope: document, section · src/pipeline/directives/atoms.ts
<!-- mdv: document noExtraSections -->strict
Sugar for noExtraSections + ordered: exactly the declared sections, in the declared order.
strict · scope: document, section · src/pipeline/directives/atoms.ts
<!-- mdv: document strict -->freeText
Opt this scope out of noExtraSections/strict — arbitrary extra child sections are allowed.
freeText · scope: document, section · src/pipeline/directives/atoms.ts
<!-- mdv: section freeText -->occurs
This child section's cardinality (SPEC §3): 0..*, 1..*, N (exact), or N..M. min AND max are enforced; with a sibling heading.mask the matching headings select the instances, without one the exemplar heading is the literal selector. Replaces v1's repeat/repeat=N, which are compile errors.
occurs=<range> · scope: section · src/pipeline/directives/atoms.ts
<!-- mdv: section required occurs=2 -->requiredWhen
This child section is required only when a condition holds: a frontmatter key equals a value (requiredWhen.<key>=<value>), or a matching checkbox is ticked (requiredWhen.checked="<label>").
requiredWhen.<key>=<value> / requiredWhen.checked="<label>" · scope: section · src/pipeline/directives/atoms.ts
<!-- mdv: section requiredWhen.checked="Breaking change" -->forbiddenWhen
The symmetric negative of requiredWhen: this child section must be ABSENT whenever frontmatter <key> equals <value>. Equality-only, front-matter only.
forbiddenWhen.front.<key>=<value> · scope: section · src/pipeline/directives/atoms.ts
<!-- mdv: section forbiddenWhen.front.status=accepted -->exactlyOne
This LITERAL child belongs to a sibling XOR group: the parent requires exactly one member sharing the same group id to be present, and emits one group-level diagnostic naming the group and its present members on zero or 2+. A member's own requiredWhen/forbiddenWhen evaluates first — only members currently permitted count toward the group. Groups are literal child sections only.
exactlyOne=<group-id> · scope: section · src/pipeline/directives/atoms.ts
<!-- mdv: section exactlyOne=design -->exhaustive
On a masked occurrence set: every real sibling heading at the selector's own declared level must match its mask or a declared literal sibling — anything else is an unmatched-instance-heading error. Independent of the parent's noExtraSections/freeText.
exhaustive · scope: section (a masked occurrence selector) · src/pipeline/directives/atoms.ts
<!-- mdv: section required occurs=1..* exhaustive heading.mask="<word>" -->front
A frontmatter key, written `front <key>`. Attaches presence/value rules to a single YAML frontmatter field. A structural marker — it takes no `end<name>`.
Markdown Crimes: how often generated Markdown goes wrong, and why a static check misses it
A variance-aware benchmark of structured-Markdown failure modes in cheap, fast language models — full method, results, and reproduction steps.