All rules

Headings that are only a label and a number

numbered-generic-headingon by default (info)Japanese / English

Headings such as "Benefit 1" and "Tip 2" that are only a label and a number

Example

Flagged
# The new room booking system ## Benefit 1 You can see free rooms at once. ## Benefit 2 You can cancel a booking in one step.
What chaff prints
3:1 The heading "Benefit 1" is only a label and a number and says nothing about the section (2 such headings) 7:1 The heading "Benefit 2" is only a label and a number and says nothing about the section (2 such headings)
Fixed
# The new room booking system ## Free rooms at a glance You can see free rooms at once. ## One-step cancelling You can cancel a booking in one step.
What chaff prints
no finding

How to fix

Say what the section says ("Benefit 1" becomes "Benefit 1: no setup" or simply "No setup needed").

Why it matters

Headings such as "Benefit 1", "Benefit 2" and "Tip 3" say nothing about their sections. A reader scanning the table of contents learns nothing until they open each one, and cannot find a section again later. Documents written to a template are full of them. The labels are in the lexicon generic-heading-label; step labels ("Step 1") are left out, since in a procedure the order is the content.

What it does not flag

A heading with a title after the label ("Benefit 1: no setup"), step, lesson, reason and feature headings ("Step 1", "Lesson 2", "Reason 3"), and chapter or section numbers ("Chapter 1") are not reported: each is a unit cited by its number. Only Markdown headings are read.

Turning it off or relaxing it

Silence this one spot (in the document)
<!-- stet: numbered-generic-heading — reason -->
Relax it for the team (the reason is kept as a comment in chaff.yaml)
npx chaffjs relax numbered-generic-heading --why "reason"
Turn it off for the team (chaff.yaml)
rules: numbered-generic-heading: off
Technical details
Layer
L1
Status
stable
Severity
info
Languages
Japanese and English
Suited to
blog, business, technical, docs, academic, legal, 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).

strictreported from 1 such headings
normalreported from 2 such headings
relaxedreported from 3 such headings

By genre

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

Genres

Message

The heading "{heading}" is only a label and a number and says nothing about the section ({count} such headings)

Rewrite depth (chaff fix-plan --depth): structure — sections, headings and paragraphs are reorganised

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