bdeshi
80057aa183
The default locale stays at the root; every other language is the same key under
/{lang}/ (ADR-0009). /en/… is never live and redirects to the root form so the URL
space cannot fork. Lookup now takes a language and reports which one it served,
following requested → default → any rather than 404ing when a translation is
missing.
That is the second routing case, so the resolver is extracted to resolve.go and
the mux keeps one entry: URL shape is the resolver's business. A leading segment
counts as a language only when some bundle is written in it, so an unknown prefix
is a 404 rather than a stripped path — and a section may not be named after a
language in use, now recorded in content-model.md.
Because the served variant can differ from the URL requested, Page gained
.Canonical (the variant actually served) and .Alternates for hreflang. A theme
must never build a path, so both come from the engine.
Evidence: /bn/pages/about/ serves the Bengali body with lang="bn" and canonical
/bn/pages/about/; /bn/posts/hello-world/ falls back to English with canonical
/posts/hello-world/; /en/pages/about/ 301s to /pages/about/; /fr/… is 404.
5.3 KiB
Theme contract
What the engine promises a theme, and the only thing this repository is bound to (ADR-0023). A theme's markup, layout and styling are not the engine's business; a theme's inputs are.
STATUS: partly live. The fields under Live today exist and are gated; everything else is the shape the contract takes when the feature arrives. All of it is engine obligation, not theme instruction — a theme may ignore any of it.
Live today
A bundle page receives:
| Field | Contents |
|---|---|
.Title |
may be empty; a template falls back to .Key rather than failing |
.Lang |
the locale of this variant, always set |
.Key |
the bundle's identity, without language or extension |
.HTML |
the rendered body, already escaped |
.Extra |
every frontmatter key the parser does not name (ADR-0002) |
.Style |
the reference theme's stylesheet, inlined so a bare site root needs no asset route |
.Canonical |
the permalink of the variant actually served — not the URL requested, which differs when the fallback chain supplied another language |
.Alternates |
every language this key exists in, as .Lang and .URL, for hreflang |
Two named templates: base is executed for every page; main is the block a theme redefines to change
the body while inheriting the document. Nothing else is promised yet.
The stability rule
Fields and names are added, never renamed or removed. Absence is always legal: a template reading a
field that does not exist gets the zero value and must not crash, and the engine must not make a missing
field fatal at request time (ADR-0002, invariant 1). This is the View-layer freeze from
architecture.md, arriving as soon as a theme exists rather than at Arc 2.
Breaking the contract is not a feature — it is a new contract version, and it needs an ADR.
What the engine provides
| Provides | Detail |
|---|---|
| the page object | known fields plus an Extra bag carrying unknown frontmatter (ADR-0002) |
| the resolved cascade | settings after site → section → bundle resolution (ideas/deferred-decisions.md) |
| queries the page needs | its sequence neighbours, its taxonomy terms, its section's members |
| named template lookup | per-type sets; a theme redefines a named block and inherits the rest (ADR-0019) |
| URLs | every path the engine emits, so a theme never constructs one by hand |
| per-page assets | the styles / scripts frontmatter lists, resolved relative to the bundle |
| chrome strings | looked up by key and language, never hardcoded English in a template |
| validity windows | a template that renders time-dependent output declares one |
Extras view
For a request under a bundle's extras directory (ideas/deferred-decisions.md) the engine additionally provides:
| Field | Contents |
|---|---|
.Extras.Entries |
the tree: Name, Path, URL, RawURL, Kind, Size, IsDir, ModTime |
.Extras.Selected |
nil on the bare listing; otherwise the chosen entry |
.Extras.Selected.HTML |
rendered output for markdown and text kinds; empty otherwise |
.Extras.Selected.RawURL |
always present — for <img src>, <object data>, or a download link |
.Bundle is the parent, so a theme has its title, language and breadcrumb. Selecting an entry is an
ordinary link and a full re-render, so a sidebar-plus-pane layout needs no JavaScript; swapping the pane
client-side is a later enhancement over working markup, never a requirement.
What the engine does not provide
Layout, class names, CSS, client-side behaviour, and any choice about how something looks — including how media is embedded, how a listing is arranged, and whether something appears in a sidebar. Those are theme decisions, and a request touching them is split: a contract extension here, a change there.
The engine also does not provide a component library, a CSS build step, or a JavaScript runtime.
conventions.md holds the output floor the engine itself meets — semantic HTML, zero-JS, every image
carrying width, height and alt — and a theme is expected to stay inside it, but the engine does not
enforce a theme's markup.
The reference theme
The binary embeds a reference theme — templates plus one small stylesheet — so a bare site root renders (ADR-0026). It exists to make this document executable: it implements every field and block named here and nothing else, and a golden-file test through it catches contract regressions before a real theme does.
It is not a design. Legibility only, no branding, no visual opinions, no JavaScript — verify.sh fails on
a <script tag in it. If it starts accumulating taste, it has stopped being a reference.
It demonstrates the contract; it is not the contract. Changing it does not change what a theme may rely on
— which is why verify.sh also fails when it changes without this document changing, since in practice the
two drift together.
Splitting a request
When a feature spans engine and theme, this repo delivers:
- the contract extension — new fields, new named blocks, new queries, new URLs;
- a note stating what a theme must do to use it, precise enough to act on without this conversation;
- embedded defaults updated far enough to prove the extension works.
It does not deliver the theme. Claiming otherwise is the same error as claiming to have migrated content in a site root this repo cannot see.