Publication
10 pages filed under Decisions › publication. A decision is a choice made for the project, with its context, its options and what it affects.
| Decision | Date | First line | Links |
|---|---|---|---|
| Purpose-built contract viewer | 2026-09-13 | The contract of an API is shown by a viewer the tool builds itself, rather than by the interactive API console the specification first named for OpenAPI contracts. That console weighs more than the page budget of the site, expects to fetch the specification over the network, and offers to call the API from the page; the site is static, works from the disk, keeps every page under its budget and never calls the systems it documents. | 35 |
| One familiar chrome | 2026-09-13 | The default theme looks like a wiki its readers already know, from the analyst to the architect: spaces, a tree, a breadcrumb, a title, the text, a table of contents. What distinguishes the site is not the layout but the right panel, which shows where a subject is evoked elsewhere without anyone having written those references. Four choices hold the chrome together. One type family for the text, headings included, the hierarchy coming from size and weight, and a monospace family for paths and identifiers only. Labels in plain language, "Related pages", "Cited", "Something to correct?", never the vocabulary of the pipeline. No account: the site is static and public, without avatar, profile or share button, and the top bar carries no build statistic. An accent that is rare, marking links and the current position, never a status or a decoration; the dark mode is a second palette measured on its own, not an inversion of the light one. The page reads at three widths, the tree and the blocks of the panel folding as native disclosures where the screen has no room, so that the same HTML serves a phone and a desk without a script. | 28 |
| White label by default | 2026-09-13 | The generated site carries the organisation's identity and nothing of the tool's. The name, logo, favicon, font families, corner radius, light and dark palettes, footer and additional stylesheet all come from theme.yaml, validated by the theme schema; a faulty key is reported by its path like a configuration error. The footer credits the tool only when the project asks for it (footer.credit: true, a plain link to the repository); by default nothing a reader sees names it. Font files are shipped by the project itself and bound with @font-face rules: the site emits no request to any other host. Light and dark modes follow the system preference, the reader can force one with the mode switch and the choice is remembered; without JavaScript the theme's default applies. The accent colour never carries information on its own: wherever the default theme uses it, an underline, an outline, a weight or a text carries the same meaning. | 27 |
| Slots, islands and layers | 2026-09-13 | The site is a set of named slots rendered at build by components, each with a typed view model that is the contract between the generator and a theme; the published HTML carries the full content of every page. Only interactive components are hydrated: an island is served as its static markup inside an element carrying its props, and one small bundle per island, named after a hash of its content, mounts the same component on it, loaded only by the pages that use it, so that a page loads no framework code unless one of its islands needs it. Every such bundle is a classic script, never a module: some browsers refuse a module script on a page opened from the disk, and the site promises to work there; only the document viewer, imported on demand by its island, is a module. Styling is native CSS in four cascade layers, tokens, base, components and project, the project's stylesheet winning every cascade by construction. Without JavaScript the content stays reachable: mentions in native disclosure elements, the search field a plain form, the mode switch hidden. A budget of 150 kB per page is measured on every build. | 23 |
| Self-hosted fonts | 2026-09-13 | A font family named in theme.yaml is not a download: the project ships its font files itself under the assets of its theme and binds them with @font-face rules in its stylesheet, and the default theme emits no request to any other host. The two families of the default theme, Instrument Sans for the text and IBM Plex Mono for paths and identifiers, ship with the site under assets/fonts/ with their licence, so that a project without a theme of its own reads in them from the disk. A test checks that no page and no stylesheet references a font host. The site therefore works from the disk, behind a proxy that reaches nothing, and without telling a third party who reads which page; the price is a folder of font files, in the site for the default families and in the configuration repository for a project's own, the white label fixture of the tool showing the layout. | 22 |
| Paginated mentions | 2026-09-12 | The first twenty mentions of an entity are in the served HTML; the rest loads from a JSON fragment specific to that entity. Never a global index. | 16 |
| Fonts from a third-party host | 2026-09-12 | The first draft of the theme named its font families by loading them from a public font host, as most static sites do: one stylesheet link, no file to ship. Superseded by self-hosted fonts: a page that fetches a font from another host does not work from the disk, leaks the address of every reader to that host, and contradicts the rule that the site emits no request the project did not choose. | 14 |
| ICU message catalogues | 2026-09-13 | Every label of the generated site goes through a message catalogue per locale in ICU MessageFormat, plurals, selections, numbers and dates expressed in the message itself, stored as JSON in the format translation platforms exchange. Message identifiers are typed from the source catalogue, so that a missing key or variable fails the build, and a test checks that every locale carries every key. Messages are resolved at build: the published HTML contains final strings and no localisation library runs in the browser; dates and numbers use the platform formatters. A project overrides any message through the labels of its theme.yaml. | 13 |
| No database | 2026-09-13 | The graph is built in memory and serialised to model.json, canonically sorted and validated by a published schema; concordance render reads it without touching the sources, and a Cypher export is provided for those who want the graph elsewhere. No server, no database and no state between two builds other than the pipeline cache: the model is a file that a pipeline writes, commits, diffs and serves. | 11 |
| Static first | 2026-09-12 | The build is a pipeline command that produces a static site. The main content of every page is in the served HTML, the site works over file://, and fragments load on demand from JSON files. An optional service will consume the same model later; nothing in the site depends on it. | 10 |
10 publication of 10 — pagination by twenty. The Links column counts the related pages, which brings the most central publication of the journey to the top.