Authoring specifications
How to add a specification, describe it with front matter, and explain it with diagrams that match the rest of the library.
Adding a specification#
A specification is a page bundle under www/specifications/content/specs/. The
directory name is its slug and its address: specs/catalog-descriptors/ is
published at /catalog-descriptors/, which is where owner documentation links to
it.
hugo new --source www/specifications specs/my-specification/index.md
The archetype lists every front matter key with a comment. Drop an icon.svg
beside index.md to give the specification its own mark — usually the icon of
the repository area it describes. Without one, the library generates a sigil
from the slug, so every specification still has a stable identity.
Front matter#
| Key | Purpose |
|---|---|
title | The name of the concept |
description | One sentence; used on cards, in search, and as the page lead |
kinds | One of architecture, orchestration, contract, lifecycle, convention |
domains | One of product, infrastructure, tooling, delivery, documentation |
traits | Any of the terms under content/traits/ |
path | Where in a repository the specification applies |
source | The repository file that is its source of truth |
status | stable, emerging, or draft |
managed | true when the source is a managed standard file |
color | Optional accent; defaults to the colour of the kind |
featured | Offer it as a starting point on the home page |
defines | The anatomy panel: what it defines |
appliesWhen | The anatomy panel: when it applies |
boundaries | The anatomy panel: where it stops |
expectations | Statements of expected behaviour |
relations | Outbound refines, composes, uses, precedes, contrasts by slug |
Write relationships in one direction only. The inverse appears on the other page automatically, and an unknown slug fails loudly as a build warning.
Voice#
Describe behaviour, not compliance. A good specification explains what a thing does, why it is shaped that way, and how it meets its neighbours — the reader should come away able to recognise the pattern elsewhere. Stay faithful to the source files; the library explains them, it does not extend them.
Explaining with diagrams#
The library has a small vocabulary of diagrams that render at build time, work without JavaScript, and look the same on every page.
Flows#
One step per line: Label | detail | optional-spec-slug.
{{< flow "Assembling the command surface" >}}
Configure | `repository.mk` declares components
Register | Each module appends to a registry | make-module-registries
Aggregate | `90-aggregates.mk` is read last
{{< /flow >}}
Lifecycles#
One phase per line: Label | cadence | detail | optional-spec-slug. A line
loop | Trigger | Phase label draws a return path.
{{< phases "From rebuild to development session" >}}
onCreateCommand | once on create | Container-local state | on-create-phase
postStartCommand | every start | Fast checks | post-start-phase
loop | Restart container | postStartCommand
{{< /phases >}}
Layouts#
A fenced text block inside tree, indented two spaces per level. A # note
annotates a row; @slug at the end of a note links a specification.
{{< tree >}}
```text
.devcontainer/
lifecycle/ # Hook directories @devcontainer-lifecycle
```
{{< /tree >}}
Comparisons, examples, and callouts#
{{< compare >}}
{{< column "Good uses" >}}
- an item
{{< /column >}}
{{< column "Avoid" >}}
- an item
{{< /column >}}
{{< /compare >}}
{{< example "path/to/file.sh" >}} …fenced code… {{< /example >}}
{{< callout note|tip|caution "Optional title" >}} Markdown {{< /callout >}}
{{< spec "catalog-descriptors" >}}
Mermaid code blocks also render, as a progressive enhancement loaded only on pages that use them. Prefer the built-in diagrams: they need no third-party script and follow the library’s visual language.
Keeping it formatted#
Prettier checks every Markdown file in the repository. Keep the blank lines
shown above inside tree, compare, column, and example, and run
make format before committing.