Skip to main content

Authoring handbook

This section is for people writing Git Masterclass. If you are here to fix a typo, you do not need any of it — open a pull request and we will handle the rest.

For anything larger, the handbook exists so that five hundred documents written by dozens of people still read as one book.

The short version​

  1. Scaffold, do not copy

    Run pnpm content:new. It writes correct frontmatter, puts the file in the right place and picks the next free ordering prefix. Copying a neighbouring lesson reproduces its mistakes.

  2. Write against the structure

    Every lesson has the same skeleton. It is not a suggestion — the review checklist enforces it, because predictable structure is what lets a reader skim a lesson they have read before.

  3. Verify every command

    Run everything you write, on a current Git release, in a clean repository. Paste real output. Set last_reviewed to the date you did it.

  4. Validate locally

    pnpm validate runs the same checks CI runs. Fixing them locally is faster than a review round trip.

The handbook​

Authoring guide

The lesson skeleton, how to pitch a lesson, and what makes one reviewable.

Style guide

Voice, tense, terminology, code sample rules and accessibility requirements.

Naming conventions

Files, directories, ids, anchors, assets, branches and commits.

Frontmatter reference

Every field, its type, its constraints and what breaks without it.

Component reference

The MDX component library, with usage rules for each component.

Assets guide

Diagrams, screenshots, formats, sizes and where files live.

Review checklist

What a reviewer checks, in order. Self-review against this first.

Translation guide

How localisation works and what must not be translated.

Where the rules actually live​

Documentation drifts from enforcement unless there is exactly one source of truth. In this repository that source is content.config.json.

repository root
  • content.config.jsonthe rules — modules, schema, taxonomy, limits
  • scripts/
  • validate-frontmatter.mjsreads the rules
  • check-structure.mjsreads the rules
  • check-assets.mjsreads the rules
  • new-lesson.mjsreads the rules
  • docs/contributing/describes the rules to humans

If this handbook and content.config.json disagree, the config file is right and the handbook is a bug. Please report it.