Page templates

Every page in a repository section starts from one of these templates. Each one lists the sections that page should have, with a TODO in place of every piece of content, so pages stay predictable to read, search and review.

Repository overviewThe landing page of a repository section.ArchitectureSystem context, internal structure, key flows, decisions.Section indexThe table of contents for modules, components, functions, APIs.ModuleOne module or package.ComponentOne UI or service component.FunctionOne function or a tight group of functions.APIOne endpoint, command or service interface.ConfigurationEnvironment variables, config files, secrets, flags.DependenciesInternal repos, external services, key packages.ContributingSetup, workflow, standards, testing, release.

Using a template

You rarely need to copy a template by hand. The generators copy it for you and fill in the names:

# A whole new repository section (overview, architecture, section indexes,
# configuration, dependencies, contributing)
npm run new:repo -- <repo-slug> "<Display name>" "<One-line description>"

# One new page inside an existing repository
npm run new:page -- <repo-slug> module    <page-slug> "<Title>"
npm run new:page -- <repo-slug> component <page-slug> "<Title>"
npm run new:page -- <repo-slug> function  <page-slug> "<Title>"
npm run new:page -- <repo-slug> api       <page-slug> "<Title>"

The new page shows up in the sidebar straight away. There is nothing to register. To write a page by hand instead, copy the block under Template on the template's page and replace the placeholders.

Conventions

• One concept per file. A module, component, function or API gets its own page. Don't put several into one long page.
• Keep every heading. If a section doesn't apply, write Not applicable and say why, rather than deleting it. Readers learn where to look.
• TODO marks unfinished content. Search for TODO to find what's left.
• status: draft in the frontmatter shows a Draft badge beside the breadcrumbs. Delete that line once the page is written.
• Diagrams use fenced mermaid blocks. They render with zoom, pan and fullscreen.
• File names are lowercase kebab-case (run-code.md, use-auth.md). The page title goes in the frontmatter title:.

Editing a template

The generators read the block under Template straight from these pages (docs/templates/*.md), so a change here reaches every page generated later. Pages that already exist are never overwritten.