Each post starts as a working document in a private repository. A publish pass turns it into a public page. A static build then checks the page and writes it as one self-contained HTML file that fetches nothing from anywhere else. Diagrams are written in a subset of Mermaid syntax 1 and drawn at build time as inline SVG.
Terms
- post
- One published page on this site, built from one markdown file.
- publish pass
- The step that turns a private working document into a post: it rewrites, quotes and strips.
- scrub list
- A private list of names, hosts and addresses that must never appear in a post. The build fails if one does.
Pipelineg
§The build refuses a post that breaks a rule, so a defect goes back to the publish pass instead of onto the site.
The publish pass
§The pass works on one source document at a time. It:
- keeps the argument and drops working notes, status and history
- replaces each reference to another private document with a quote of the cited section
- removes everything on the scrub list
- runs the prose review, which enforces the house rules
The prose review enforces this rule, among others:
Three or more parallel items go in a bulleted list. A sentence carrying an argument or a trade-off stays a sentence.
Rules the build checks
§| Rule | Fails when |
|---|---|
| Terms | A term is used but never defined, or defined twice |
| Links | A link points anywhere except a heading on the page, another post, or a public URL |
| Scrub | Any entry on the scrub list appears, in prose or in code |
| Dashes | A dash is used as punctuation |
| Diagrams | A diagram has no caption, or uses syntax outside the supported set |
The link rule, as the build applies it to each link in a post:
// A link may target a heading on this page, another post, or the public web.
internal static LinkVerdict Classify(string href, Page page, PostIndex posts)
{
if (href.StartsWith('#'))
{
return page.HasAnchor(href[1..]) ? LinkVerdict.Ok : LinkVerdict.MissingAnchor;
}
if (href.StartsWith("post:", StringComparison.Ordinal))
{
return posts.Contains(href[5..]) ? LinkVerdict.Ok : LinkVerdict.UnknownPost;
}
return href.StartsWith("https://", StringComparison.Ordinal)
? LinkVerdict.Ok
: LinkVerdict.PrivatePath;
}Look
§
The look of these pages comes from one rendered study of spacecraft panelling, after the black and white blocks painted on a Saturn V. Three things carry over from it:
- the charcoal to slate gradient behind each page title
- the uneven bands of grey that texture that gradient
- hard edges, cut at one corner on tags, tables and figures
Images follow the same rules as diagrams. Each is embedded in the page, framed by a hairline with one cut corner, and numbered with the figures. A tall image sits beside the text at a little over a third of the column, and the text wraps round it. A wide image takes the full column.
Worked example
§The source document says:
Retries follow the backoff rule in [retry guide](../guides/retry.md#backoff);
see the runbook for overrides.- The retry guide is private, so the pass quotes its
Backoffsection in place of the link. - The runbook is unpublished and the sentence stands without it, so the pass drops the clause.
- The build finds no private link, no scrub-list entry and no dash, and writes the page.
The published post says:
Retries follow this backoff rule:
Wait 2 to the power n seconds before retry n, up to five retries, then fail the job.