D0004 page-headings¶
Rule: A long page is divided into sections.
| Code | D0004 (stable, never reused) |
| Id | page-headings |
| Category | reading |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a long page without sections gives the reader no map |
| small-workspace | warn |
a long page without sections gives the reader no map |
| medium | warn |
a long page without sections gives the reader no map |
| big | warn |
a long page without sections gives the reader no map |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
min-words |
integer | 400 |
words of prose from which a page needs a section heading |
pages |
one of "all", "guide", "reference" | "all" |
the kinds of page judged |
Why¶
A long page without sections gives the reader no map: they cannot see what it covers, skip what they know, or find a part again. Section headings also become the page's table of contents and its link anchors.
The lint counts the prose words of a page. Above min-words, the page needs at least one heading below its title (## or deeper).
How to fix¶
Divide the page into ## sections, each named after what it answers. A page that covers several unrelated topics is often better as several pages.
Configure¶
[lints.page-headings]
level = "deny"
min-words = 400
pages = "all"
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(page-headings) <reason> (waivers); the code works there too, as in [lints.D0004].