Skip to content

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].