6.4 Formatting
Mechanical conventions. None of these affects meaning; all of them affect whether a diff is readable.
6.4.1 Line length #
Prose SHOULD wrap at 78 columns. Tables, code blocks, and link-heavy lines are exempt — breaking those hurts more than it helps.
The reason is diffs. A paragraph on one long line produces a whole-paragraph diff for a one-word change, which makes review of a large document impractical.
6.4.2 Frontmatter #
Every article carries YAML frontmatter with a title and a
description:
---
title: Freshness and Rollback Protection
description: An index that verifies is not necessarily current — monotonic
versions, staleness limits, and the defences against rollback and freeze.
---
Titles are in title case, and name the subject rather than describing it. "Freshness and Rollback Protection", not "How freshness works".
The description is one sentence saying what the article covers. It is what a reader sees in a search result, so it does the work the title deliberately does not: where the title names the subject, the description says what is in there. It SHOULD name the specific things — "monotonic versions, staleness limits" beats "the freshness rules" — because a corpus this size has many articles called Overview, Structure and Conventions, and the description is what tells them apart.
Do not restate the title. title: Persistence with
description: How persistence works has spent a line and told the
reader nothing.
Books were written without descriptions for a time, and the omission
was invisible until search made it obvious. The site build takes
--strict, which fails on any article missing one; run it that way.
6.4.3 Headings #
Articles use ## for their top-level headings. An article does not
repeat its own title as a heading — the renderer supplies it.
Heading text is short and specific. Because headings are not addressable (§5.3), they are navigation rather than citation targets, and they SHOULD read as scannable labels.
6.4.4 Code and identifiers #
Identifiers, paths, field names, and literal values are in backticks. Fenced blocks carry a language tag where one applies.
Code spans are not translated: a field named size_installed is written
that way in prose, not as "size installed".
6.4.5 Text hygiene #
Straight quotes and apostrophes rather than typographic ones; a regular hyphen rather than a non-breaking one; a normal space rather than a non-breaking space; and no zero-width characters. Each of those renders identically and greps differently, which is the worst combination.
An em dash is written as —, spaced as the surrounding prose requires.
6.4.6 Spelling #
British English, except in identifiers, code, and the names of external standards, which are reproduced exactly as their source spells them.