A heading names a command its section's code does not show

heading-command-missingon by default (info)Japanese / English

A command or option named in a heading that the section's examples never use

Example

Flagged

# Usage ## `--dry-run` Show what would change without changing it. ```bash npx chaffjs fix --dryrun README.md ```

What chaff prints

3:1 "--dry-run" in this heading does not appear in the section's code

Fixed

# Usage ## `--dry-run` Show what would change without changing it. ```bash npx chaffjs fix --dry-run README.md ```

What chaff prints

no finding

chaff.yaml used for this example

genre: docs/manual

How to fix

Check which of the heading and the example has the current name, and correct the other.

Why it matters

When the section "## `--dry-run`" shows an example using "--dryrun", the reader cannot tell which is right. It happens when a command or an option is renamed and only the heading or only the example is updated. chaff points out a heading's code part (`npm install`, `--force`, `init`) that appears in none of the code blocks or code spans of its section (up to the next heading of the same or a higher level). A section with no code at all is not checked.

What it does not flag

Sections with no code, headings naming a file or a function (`config.yaml`, `useEffect`), and headings with no code part are not checked. `--force` inside `--force-with-lease` does not count as shown.

Turning it off or relaxing it

Silence this one spot (in the document)

Relax it for the team (the reason is kept as a comment in chaff.yaml)

npx chaffjs relax heading-command-missing --why "reason"

Turn it off for the team (chaff.yaml)

rules: heading-command-missing: off

Technical details

Layer: L1
Status: stable
Severity: info
Languages: Japanese and English
Suited to: technical, docs, blog, legal, academic, literature, speech
Reads from the document: markdown

Levels

Set a level for this rule under rules in chaff.yaml. With nothing set, it runs at the level its genre gives it (see By genre below).

strict	warning
normal	info
relaxed	info

This rule has no limit to count to. A level sets how a finding is marked: relaxed keeps the finding and marks it a step lower.

By genre

Runs by default in: technical/spec, technical/readme, blog/tech, blog/essay, blog/owned-media, docs/manual, docs/faq, docs/glossary
Turned off by the genre in: legal/contract, legal/statute, legal/judgment, legal/patent, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript
Not suited to, and not run in: business/proposal, business/report, business/email, business/press-release, business/meeting-notes

Genres

Message

"{command}" in this heading does not appear in the section's code

Rewrite depth (chaff fix-plan --depth): light — words and sentences; the structure and the voice stay

This page is built from the rule's definition file:packages/chaff/rules/heading-command-missing.yaml