Style guide

Voice and person

Rule	Yes	No
Address the reader directly	"You now have two branches."	"We now have two branches."
Present tense for behaviour	"git status lists staged changes."	"git status will list staged changes."
Active voice	"Git writes a new commit object."	"A new commit object is written."
Imperative for instructions	"Run git log --oneline."	"You can run git log --oneline."

Words we do not use

Never: simply, just, easy, obviously, trivial, of course. They tell a struggling reader that their difficulty is a personal failing.

Never: master for the default branch. Use main. When historical accuracy requires it, write "the default branch, historically master".

Never: blacklist, whitelist, sanity check. Use blocklist, allowlist, consistency check.

Avoid: should for behaviour that is deterministic. git commit does not should create a commit; it creates one. Reserve should for the reader's expected observation ("you should see three entries").

Terminology

Git's own vocabulary is precise. Using it loosely is the single most common defect in Git writing.

Use	Not	Because
index	staging area (first mention only)	"index" is what the documentation, the error messages and the config keys all say
commit (noun)	revision, changeset	Git has one word for this
remote-tracking branch	remote branch	They are different things, and conflating them is the root of most push/pull confusion
detached HEAD	detached head	Capitalised, because HEAD is a ref name
fast-forward	fast forward	Hyphenated, per Git's own documentation
object ID, or OID	hash, SHA	"SHA" names the algorithm, not the identifier

Every term used precisely for the first time in a module should be wrapped in <Term> so that readers get the definition inline:

A <Term id="fast-forward">fast-forward</Term> merge moves the branch pointer.

Headings

• Sentence case: "Recovering a deleted branch", not "Recovering A Deleted Branch".
• Never skip a level. H2 to H4 is a structural error and breaks the table of contents.
• No H1 in the body — the H1 is generated from title.
• Maximum depth H4. Deeper nesting means the lesson needs splitting.
• Headings are noun phrases or gerunds, never questions.

Code samples

• Every fenced block declares a language. Enforced by markdownlint (MD040).
• Use bash for commands, console only when the block genuinely mixes prompt and output, and text for output alone.
• Prefer <Terminal> over a fenced block when you show a command and its output: the copy button then yields only the runnable part.
• Never include the $ prompt inside a bash block. Readers copy blocks whole.
• Placeholder convention: <angle-brackets-in-kebab-case>, e.g. git switch <branch-name>. Never git switch [branch] and never git switch BRANCH.
• Long flags in prose (--force-with-lease, not -f). Short flags only when you are teaching the short form.

Numbers, dates and versions

• Object IDs abbreviated to seven characters in prose, full length only when the length itself is the point.
• Dates as YYYY-MM-DD. No ambiguous regional formats anywhere.
• Git versions as 2.43 or 2.43.0, never v2.43.
• Version-dependent behaviour is marked with <VersionNote since="2.23">, not written inline, so that it can be audited later.

Accessibility

These are requirements, not preferences.

• Every image has meaningful alt text. "Diagram" is not alt text; describe what the diagram shows. Purely decorative images take alt="".
• Never rely on colour alone. The <GitGraph> component pairs colour with lane labels for this reason.
• Every <GitGraph> has a caption. It is the accessible name, and the component also renders a text description of the graph.
• Link text stands alone. Write [the reflog lesson](/history-and-rewriting/reflog), never click [here](...). Screen-reader users navigate by link list, where "here" carries no information. This one is enforced: pnpm content:links rejects here, this, link, click here and read more as link text.
• Tables have header rows and are used for tabular data only, never layout.

Punctuation and mechanics

• Serial comma.
• Em dashes for parenthetical breaks, spaced en dashes are not used.
• Spelling is British English, consistently: licence, behaviour, colour, normalise, artefact. Enforced by cspell with the en-GB dictionary.
• Code identifiers keep whatever spelling their API uses — CSS color, the LICENSE file, normalize.css. Never "correct" an identifier to match the prose rule.
• One sentence per line is not required — Prettier preserves your wrapping. Wrap at roughly 100 characters for readable diffs.
• Backticks for anything you would type: commands, flags, paths, file names, branch names, config keys.

Admonitions

Docusaurus admonitions are available, and each has one job:

:::note
Context a reader can skip without consequence.
:::

:::tip
A better way to do what was just described.
:::

:::info
Background: history, rationale, related reading.
:::

:::warning
Something that will surprise the reader and cost them time.
:::

:::danger
Something that destroys work. Reserve this. If everything is dangerous, nothing is.
:::

Never stack two admonitions consecutively. If two consecutive paragraphs both need boxing, neither does.