Handbook Layout — Reference Template

When to reach for this mode

Handbook Mode is a format, not a palette. Pick it by how the page will be read, not by how it should look — then pick a --style separately.

use it for

User guides and how-tos someone will return to
Anything with 4+ sections read in order
Reference pages with tables, caveats, and an FAQ
Explaining an output format, config file, or CLI contract
One page in a family of cross-linked pages

not for

A single diagram — that is the mermaid or architecture template
Tabular data as the whole payload — use data-table
Under 4 sections: the rail is clutter, drop it
Anything presented rather than read — use slide mode

The rail is the tell. If a reader would ever want to jump back to chapter 3, this is the right layout. If they read once, top to bottom, and never return, a plainer page serves them better.

Anatomy

Six parts. The masthead and the rail do most of the work.

masthead

Mono eyebrow, then the subject as a mono kicker, then a serif headline that reads as a sentence. The kicker carries the literal name; the headline carries the meaning.

stat band

Four to six hard numbers, serif values over small dim labels. States the page's thesis before a word of prose. Skip it if you have no real numbers — invented ones are worse than none.

contents rail

196px sticky column, scroll-spy active state, collapsing to a horizontal tab strip under 940px. Full pattern in responsive-nav.md.

numbered chapters

CSS counters, not hand-written numbers. A hairline between siblings gives rhythm with no divider markup.

margin notes

Left-border asides in three semantic colors. Used for the thing a careful reader would ask next — not only for warnings.

page family

Sibling pages listed under the rail and repeated in the footer, so a set of guides navigates as a set.

Chapter numbering, and where it breaks

Numbers belong to the document structure, so let CSS derive them.

Approach	Verdict	Why
`counter-increment` on `section`	use this	Reordering or inserting a section renumbers everything automatically
Hand-written `<span>01</span>`	avoid	Silently desyncs the moment a section moves — and it always moves
`<ol>` of sections	rarely	Correct semantics, but list styling fights the section layout for little gain
TOC link labels (`1 ·`, `2 ·`)	by hand	Counters can't reach across to the nav, so these stay manual — keep them in sync

Two counters, two scopes. Chapters count on .main; step cards count on each .steps grid. Reset them on different ancestors or the step numbers continue from the chapter number.

Annotated blocks

The one pattern here that prose genuinely cannot replace: explaining a format by pointing at it.

what the reader will actually seeoutput

stat: ok  duration=142ms          ← the field you check first
retries: 2                        ← nonzero means the transport flapped;
                                    correlate with the gateway log
payload: 4.1 KiB                  
signature: verified               ← anything but `verified` invalidates
                                    everything above it

Three rules make this work:

white-space: pre, not pre-wrap — the annotation columns depend on exact character positions, and wrapping destroys the alignment
Wrap the block in overflow-x: auto so narrow viewports scroll instead of reflowing
Dim the commentary and accent only the token being pointed at. If every line is highlighted, nothing is

Keep it under about 12 lines. Past that the reader loses which arrow belongs to which line. Split into two annotated blocks with prose between them.

Q&A

Why a <dl> instead of cards?: An FAQ is definitions: a term and its explanation. <dl>/<dt>/<dd> says so semantically, costs about six lines of CSS, and copy-pastes into a document cleanly. Cards would give each answer equal visual weight, which is the opposite of what a tail-end reference section wants.
Does this mode ever include a diagram?: It can, and then references/mermaid-rules.md applies in full — the .diagram container, the four drift guards, and re-render on themechange. But reach for --handbook because the page is a document. If a diagram is the payload, a different template fits better.
How is this different from --style paper?: Different axes, so it isn't a choice between them. --style paper sets the palette: warm cream and terracotta, informal. --handbook sets the structure — rail, chapters, stat band, marginalia — and accepts any palette. --handbook --style paper is both.
Can the rail be on the right?: Yes — flip the grid columns and the border-left to border-right. Left is the default because it matches the reading direction, but a right rail pairs well with a left-aligned masthead when you want the headline flush to the page edge.