block
The one recursive container tag. Wraps a heading plus any prose or nested tags, and is the thing presence/body rules (`required`, `minWords`, `noPlaceholder`, …) target. Blocks nest, so a schema is an AST of blocks — close every one with its `endblock` end tag.
Container · open <!-- mdv: block … --> · close <!-- mdv: endblock -->
<!-- mdv: block required minWords=20 -->
## Away Mission Summary
The landing party reached the derelict freighter, recovered the flight recorder,
and confirmed no survivors aboard. Returning to ship with the data core intact.
<!-- mdv: endblock -->Props
| Prop | Syntax | Category | Description |
|---|---|---|---|
contains | contains=<option> | body | Checks that required content appears in a block body. The value is one or more of: a block-type name — paragraph, code, table, image, list, checklist, blockquote, html (a heading is not a block type) — a /regex/, or a "quoted literal", comma-separated. So contains=table requires a table, contains=/because/ requires that word, contains=code,image requires both. |
forbid | forbid=<option> | body | Checks that forbidden text or patterns are absent from a block body. The value is a /regex/, a "quoted literal", or comma-separated terms — so forbid=/tbd|tba/, forbid="not applicable", and forbid=TODO,TBD,FIXME all work. |
noPlaceholder | noPlaceholder | body | Checks that placeholder or template residue is absent; targets a block body. |
pattern | pattern=<option> | body | Checks that prose matches a required regular expression; targets a block body. |
maxWords | maxWords=<option> | body | Checks that prose stays within a maximum word count; targets a block body. |
minWords | minWords=<option> | body | Checks that prose reaches a minimum word count; targets a block body. |
heading.level | heading.level=<option> | heading | Checks that the block's matched heading is an ATX heading of the given level (1-6) — e.g. heading.level=1 requires the block to open at a # title, heading.level=2 at a ## section. Validates the heading's level, not the body. |
heading.maxWords | heading.maxWords=<option> | heading | Checks that the block's matched heading stays within N words, to keep headings tight. Validates the heading itself, not the body. |
heading.minWords | heading.minWords=<option> | heading | Checks that the block's matched heading has at least N words, so a heading is specific rather than a single bare noun. Validates the heading itself, not the body. |
heading.noPlaceholder | heading.noPlaceholder | heading | Checks that the block's matched heading is not leftover placeholder text (TODO, TBD, an unfilled imperative stub). Validates the heading itself, not the body. |
heading | heading=<option> | heading | Checks that the block's matched heading matches a required regular expression. Written either as heading=/re/ or, equivalently, heading.pattern=/re/. Validates the heading itself, not the body. |
heading.pattern | heading.pattern=<option> | heading | Alias of heading=/re/: checks that the block's matched heading matches a regular expression. |
issueKeyword | issueKeyword=<option> | integration | Checks that an issue reference uses an accepted closing keyword; targets a block body. |
issueState | issueState=<option> | integration | Checks that a linked issue is in the required state; targets a block body. |
desc | desc=<option> | meta | An author description / generation hint for the construct — desc="One paragraph for the changelog". Like name, it is metadata: it validates nothing about the output and emits no diagnostics. Quoted values (with spaces) are one atom, so the description survives intact. |
help | help=<option> | meta | Author guidance surfaced on this field's validation errors — like a form field's help text. Metadata: it never validates the output. The value is stamped onto every diagnostic the field emits (CLI note: line, --json help, the PR-comment "What's needed" cell, and the autofix repair context), so the schema author can say HOW to satisfy the field — e.g. when it is honest to tick a checkbox — right where the failure is reported. |
name | name=<option> | meta | An author label for the construct, used in docs and diagnostics — name="Release summary". It is metadata, never a check: it validates nothing about the output and emits no diagnostics. Quoted values (with spaces) are one atom, so the label survives intact. |
optional | optional | presence | Checks that a block may be absent but validates normally when present; targets a block. |
recommended ⚗️ | recommended | presence | Checks that a recommended block is surfaced when absent; targets a block. |
requiredOrNA | requiredOrNA | presence | Checks that a construct has content or an explicit N/A note; targets a block or media construct. |
required | required | presence | Checks that a block is present and non-empty; targets a block. |
Prop details
contains
Checks that required content appears in a block body. The value is one or more of: a block-type
name — paragraph, code, table, image, list, checklist, blockquote, html (a heading
is not a block type) — a /regex/, or a "quoted literal", comma-separated. So contains=table
requires a table, contains=/because/ requires that word, contains=code,image requires both.
contains=<option> · category: body · status: stable · src/rules/content/contains.ts
<!-- mdv: block contains=table,/because/ -->
## Mars Relay Decision
We rerouted telemetry because the relay window closes at 14:30.
| Window | Status |
| ------ | ------ |
| 14:30 | closing|
<!-- mdv: endblock -->forbid
Checks that forbidden text or patterns are absent from a block body. The value is a /regex/, a
"quoted literal", or comma-separated terms — so forbid=/tbd|tba/, forbid="not applicable",
and forbid=TODO,TBD,FIXME all work.
forbid=<option> · category: body · status: stable · src/rules/content/forbid.ts
<!-- mdv: block forbid=/tbd|tba/ -->
## Rebel Briefing
The shield generator repair is ready for squad review.
<!-- mdv: endblock -->noPlaceholder
Checks that placeholder or template residue is absent; targets a block body.
noPlaceholder · category: body · status: stable · src/rules/content/no-placeholder.ts
<!-- mdv: block noPlaceholder -->
## Docking Check
Guidance telemetry now locks before final approach.
<!-- mdv: endblock -->pattern
Checks that prose matches a required regular expression; targets a block body.
pattern=<option> · category: body · status: stable · src/rules/content/pattern.ts
<!-- mdv: block pattern=/^Status: (Draft|Final)$/m -->
## Mission Packet
Status: Final
<!-- mdv: endblock -->maxWords
Checks that prose stays within a maximum word count; targets a block body.
maxWords=<option> · category: body · status: stable · src/rules/content/words/max-words.ts
<!-- mdv: block maxWords=12 -->
## Flight Note
Launch the repair drone after beacon checks pass.
<!-- mdv: endblock -->minWords
Checks that prose reaches a minimum word count; targets a block body.
minWords=<option> · category: body · status: stable · src/rules/content/words/min-words.ts
<!-- mdv: block minWords=6 -->
## Rover Update
The rover confirms soil samples before uplink.
<!-- mdv: endblock -->heading.level
Checks that the block's matched heading is an ATX heading of the given level (1-6) — e.g.
heading.level=1 requires the block to open at a # title, heading.level=2 at a ## section.
Validates the heading's level, not the body.
heading.level=<option> · category: heading · status: stable · src/rules/heading/heading-level.ts
<!-- mdv: block required heading.level=1 -->
# Mission Log: Europa Relay Alignment
<!-- mdv: endblock -->heading.maxWords
Checks that the block's matched heading stays within N words, to keep headings tight. Validates the heading itself, not the body.
heading.maxWords=<option> · category: heading · status: stable · src/rules/heading/heading-max-words.ts
<!-- mdv: block required heading.maxWords=8 -->
## Airlock repair owner
<!-- mdv: endblock -->heading.minWords
Checks that the block's matched heading has at least N words, so a heading is specific rather than a single bare noun. Validates the heading itself, not the body.
heading.minWords=<option> · category: heading · status: stable · src/rules/heading/heading-min-words.ts
<!-- mdv: block required heading.minWords=2 -->
## Rover contingency
<!-- mdv: endblock -->heading.noPlaceholder
Checks that the block's matched heading is not leftover placeholder text (TODO, TBD, an unfilled imperative stub). Validates the heading itself, not the body.
heading.noPlaceholder · category: heading · status: stable · src/rules/heading/heading-no-placeholder.ts
<!-- mdv: block required heading.noPlaceholder -->
## Sensor handoff
<!-- mdv: endblock -->heading
Checks that the block's matched heading matches a required regular expression. Written either as
heading=/re/ or, equivalently, heading.pattern=/re/. Validates the heading itself, not the body.
heading=<option> · category: heading · status: stable · src/rules/heading/heading-pattern.ts
<!-- mdv: block required heading=/^ADR-[0-9]{4}:.+/ -->
## ADR-0007: Adopt beacon validation
<!-- mdv: endblock -->heading.pattern
Alias of heading=/re/: checks that the block's matched heading matches a regular expression.
heading.pattern=<option> · category: heading · status: stable · src/rules/heading/heading-pattern.ts
<!-- mdv: block required heading.pattern=/^RFC-[0-9]{4}:.+/ -->
## RFC-0042: A new docking directive
<!-- mdv: endblock -->issueKeyword
Checks that an issue reference uses an accepted closing keyword; targets a block body.
issueKeyword=<option> · category: integration · status: stable · src/rules/integrations/issue-keyword.ts
<!-- mdv: block issueKeyword=Fixes,Closes -->
## Hangar Tracking
Fixes #123
<!-- mdv: endblock -->issueState
Checks that a linked issue is in the required state; targets a block body.
issueState=<option> · category: integration · status: stable · src/rules/integrations/issue-state.ts
<!-- mdv: block issueKeyword=Fixes issueState=open -->
## Droid Bay Tracking
Fixes #123
<!-- mdv: endblock -->desc
An author description / generation hint for the construct — desc="One paragraph for the changelog". Like name, it is metadata: it validates nothing about the output and emits no
diagnostics. Quoted values (with spaces) are one atom, so the description survives intact.
desc=<option> · category: meta · status: stable · src/rules/meta/desc.ts
<!-- mdv: block required desc="A summary a release manager can paste into the changelog" -->
## Mission Summary
One paragraph for the station changelog.
<!-- mdv: endblock -->help
Author guidance surfaced on this field's validation errors — like a form field's help text.
Metadata: it never validates the output. The value is stamped onto every diagnostic the field
emits (CLI note: line, --json help, the PR-comment "What's needed" cell, and the autofix
repair context), so the schema author can say HOW to satisfy the field — e.g. when it is honest
to tick a checkbox — right where the failure is reported.
help=<option> · category: meta · status: stable · src/rules/meta/help.ts
<!-- mdv: taskList required allChecked help="Tick only after the release CI run is green on the merge commit." -->
- [ ] CI green
<!-- mdv: endtaskList -->name
An author label for the construct, used in docs and diagnostics — name="Release summary". It is
metadata, never a check: it validates nothing about the output and emits no diagnostics. Quoted
values (with spaces) are one atom, so the label survives intact.
name=<option> · category: meta · status: stable · src/rules/meta/name.ts
<!-- mdv: block required name="Release summary" minWords=20 -->
## Mission Summary
The orbital release notes confirm that navigation, docking, telemetry, and crew handoff checks all cleared before the morning launch window.
<!-- mdv: endblock -->optional
Checks that a block may be absent but validates normally when present; targets a block.
optional · category: presence · status: stable · src/rules/presence/optional.ts
<!-- mdv: block optional -->
## Away Team Notes
Extra context for bridge reviewers.
<!-- mdv: endblock -->recommended
Checks that a recommended block is surfaced when absent; targets a block.
recommended · category: presence · status: experimental · src/rules/presence/recommended.ts
<!-- mdv: block recommended -->
## Flight Background
Prior slingshot attempts and tradeoffs.
<!-- mdv: endblock -->requiredOrNA
Checks that a construct has content or an explicit N/A note; targets a block or media construct.
requiredOrNA · category: presence · status: stable · also on: media · src/rules/presence/required-or-na.ts
<!-- mdv: block requiredOrNA -->
## Viewscreen Captures
N/A: no cockpit display changed.
<!-- mdv: endblock -->required
Checks that a block is present and non-empty; targets a block.
required · category: presence · status: stable · src/rules/presence/required.ts
<!-- mdv: block required -->
## Mission Context
The change validates generated flight notes.
<!-- mdv: endblock -->