Skip to content
lemonfiber

Repo: website-docs.lemonfiber.app

Status: Proposed

The documentation site at docs.lemonfiber.app. Astro Starlight, static, Hippocratic 3.0. Almost nothing it publishes is written here — the pages are each repo’s own documentation, pinned to a revision and rendered (ADR-0015).

Implements: the org’s user-facing documentation and the build-in-the-open commitment of governance; consumes brand (roadmap).

Why this is a separate repo

Section titled “Why this is a separate repo”

The same floor that made the org multi-repo (ADR-0004), plus one thing the frontpage cannot give it. The two sites have opposite relationships with time: the frontpage reads live org state at build so that it cannot lag (REPO-R39), while documentation must render a pinned revision, because a reader following instructions needs the instructions that match the release they installed. One repo cannot honour both rules. Folding this into website-lemonfiber.app would also mean rebuilding Starlight’s sidebar, search and version switcher inside a bespoke site that has no use for them.

It is not folded into spec either. spec is where the specification is written and checked; this site is where it is read. Publishing it from the repo that authors it would mean maintaining a second site, with a second visual language and a second search index, for a reader who was already here.

The one property to remember

Section titled “The one property to remember”

It renders; it does not own. Every page of documentation belongs to the repository that also holds the thing it describes, and reaches this site as a git submodule pinned to an exact revision, symlinked into a Starlight content collection. Nothing is fetched during a build.

  • lemonfiber/.docs/ — the architecture notes a contributor reads before touching the crate
  • brand/.docs/ — colour, type and logo rules
  • each repo’s README.md — its own front door
  • .github — conduct, security, contributing

The specification is mirrored the same way, from a pinned revision of spec — it is the largest body of prose the org has, and a reader searching the documentation for a requirement should find it rather than be sent to a different domain. It is rendered here and authored there: identifiers are still checked by integrity.py in spec, and a mirrored page’s edit link points at spec. This is what makes the pages trustworthy: they cannot quietly drift from the repo they document, because they are that repo’s files at a revision the site names on the page.

What is written here is the connective tissue — navigation, landing pages, and the task-shaped guides that mirrored prose does not provide because it was written for a repository rather than for a reader arriving from a search box.

What’s in it

Section titled “What’s in it”
website-docs.lemonfiber.app/
├── .gitmodules            the pins — one per repo whose docs are shown
├── vendor/                the submodules themselves, never edited here
├── mirrors.json           the route table — which upstream file each page is
├── src/content/docs/      the collection; this site's own pages, and mirrored
│                          trees entering by symlink beside them
├── src/lib/               the mirror loader: routes, provenance, link rewriting
├── messages/en.json       the message catalogue; every authored string
├── src/components/        VersionTrain · VersionPill · StatusPill · …
└── astro.config.ts        Starlight: sidebar, one locale, link validation

Authored and mirrored pages share one collection rather than sitting in separate trees: Starlight’s sidebar is built from route, so a split would mean two sources for one navigation. A mirrored page is a symlink into vendor/, which is what makes “this site holds no second copy” (REPO-R45) a property of the filesystem rather than a habit.

How it stays fresh

Section titled “How it stays fresh”

Deployed to GitHub Pages by CI, from a checkout that includes submodules. A pin moves by pull request in this repo, which is what makes the change reviewable and dated: the diff says which revision the site will start showing, and every rendered page carries that revision and its date so a reader can tell how old the words are. A build fetches nothing, so it succeeds offline and renders the same site from the same commit a year later.

The versions of the prose are built as a matrix from the first release, rather than retrofitted — switching versioning on later renames every published URL.

Maintenance

Section titled “Maintenance”

Bumping pins, and the site’s own structure and styling. Nothing else: a wrong sentence is fixed in the repo that owns it, which is slower and is the behaviour worth buying. Structural change, like any other, cites a spec identifier (GOV-R2). CI reuses the shared workflows (spec-check, hygiene, security, dco, commitlint, labeler) exactly as every other repo does (Q-R56), and adds a link check that reads mirrored prose as well as authored prose — this is the only build that sees all of it at once.

Requirements

Section titled “Requirements”
ID Requirement
REPO-R45 Every documentation page MUST be rendered from the repository that owns its source; this repository MUST NOT hold a second copy of it.
REPO-R46 Mirrored content MUST be pinned to an exact upstream revision recorded in this repository, never to a branch.
REPO-R47 A build MUST NOT fetch content over the network; everything it renders MUST already be in the checkout.
REPO-R48 Every link in mirrored content MUST resolve to a page on this site or to a document that is reachable elsewhere, and CI MUST fail on one that does not.
REPO-R49 Every mirrored page MUST show the upstream revision it was rendered from, and that revision’s date.
REPO-R50 Every user-facing string authored in this repository MUST come from the message catalogue and MUST NOT be written into a template.
REPO-R51 The published site MUST load no font, script, style or tracker from a third party at run time.
REPO-R52 The specification MUST be rendered on this site from a pinned revision of spec, and MUST NOT be published from any second site.
REPO-R53 A URL that a retired rendering of the specification published MUST continue to resolve, by redirect, to the page that replaced it.
Section titled “Related”

This page lives in another repository Rendered from lemonfiber/spec at 1d10402, 2026-09-09. Read the source of this page