Repository foundations
Git Masterclass now has its skeleton. No lessons yet — deliberately. This post records what was built and why, because the reasoning matters more than the file list.
What is here
Fifteen modules, from orientation through internals to advanced topics, each with an overview page and sections for exercises and labs. A component library of sixteen MDX components. A content schema. Validation tooling. Contribution process, governance and automation.
What is not here is content, and that ordering is intentional. Conventions invented while writing the fortieth lesson do not get applied to the first thirty-nine.
The decisions worth knowing about
Ordering lives in the filesystem. Sidebar position comes from numeric
filename prefixes, and sidebars.ts names no individual document. A sidebar file
that lists documents is edited by every content pull request and becomes a
permanent merge conflict — one that, resolved carelessly, silently reorders or
drops lessons.
Rules live in one file. content.config.json holds the module list, the
frontmatter schema, the tag vocabulary and the size budgets. The validation
scripts read it, the generator reads it, and the authoring handbook documents it.
When documentation and enforcement are separate copies of the same rule, they
drift, and contributors learn to ignore the documentation.
Validation runs without installing anything. The scripts under scripts/ use
only Node builtins, including a hand-written frontmatter parser. They run in a
pre-commit hook and in the first CI job, so a missing field is reported in
seconds rather than after a five-minute build.
Staleness is dated. Every document carries last_reviewed, and a monthly
workflow turns overdue material into an assignable issue. This is the failure
mode that actually kills teaching material: nothing about a stale lesson looks
wrong, it just quietly stops being true.
What is next
The first module, written end to end. Every convention in the authoring handbook is a hypothesis until a real lesson tests it — and some of them will turn out to be wrong.
If you would like to write one, the authoring handbook is the place to start, and lesson proposals go through the issue tracker so that placement is agreed before anyone invests hours in prose.