Skip to content
noggin

The site is Astro Starlight over the repo's Markdown, with a hash-based CSP

Decided with Cansin on 2026-11-01, spec #331 (research and the CSP spike’s verdict in its comments, spike #332); ticket #333. Supersedes ADR 0009’s MkDocs Material and mkdocs-macros, and ADR 0008’s page, import map and vendored three.js.

Amended 2026-11-02 (#372): the Footer override also shows the version and the commit built, linking their GitHub pages, and /version.json gives them with the build time (macros.py build).

Amended 2026-11-02 (#538, #496): Site Checks is now part of the Checks workflow: its Site job builds and tests the site, and its Checks gate adds the pictures and the viewer, runs the Playwright smoke test and uploads it. Amended 2026-11-02 (#732): Site runs after Blender and does it all once: adds the pictures and the viewer, runs Vitest and the Playwright smoke test in its container, and uploads the site; the gate only gates. Amended 2026-11-02 (#547): commands now just, ADR 0016.

Amended 2026-11-02 (#778, ADR 0021): no Docs versions; the smoke test checks the header’s newest release and that an old version’s URL (/noggin/vX.Y/…) lands on the same page, the one redirect.

Amended 2026-11-03 (#795): Site Deploy (its own workflow) is gone; Checks’ last job, Deploy, deploys Site’s artifact on main’s push once the gate passed, so each github-pages Deployment records the commit built.

Amended 2026-11-02 (#603): the site keeps Starlight (search, Docs versions, dark mode) but no longer its default look. Cansin picked direction A, “Googly”, from a three-way prototype (branch prototype/603-site-directions): Yellow Pine’s brand v2.2 as the base (ink, paper, surfaces, links, an azure focus), the Mech’s filament colours as the accents (Milky Pink and Apricot as flat fields), Rubik 700 headings self-hosted from @fontsource/rubik (the CSP allows only the site’s own files) and the system font for the body, all in site/src/styles/custom.css. Component overrides: SiteTitle (the “noggin” wordmark, its o one of the Mech’s eyes, which looks at the pointer and blinks, holding still for reduced motion), PageTitle (the landing page’s big wordmark; each Stage guide’s Stages, read from their titles) and the Footer’s “by Yellow Pine” credit. The icon is the Mech’s eye, rendered by Blender (model/render/pictures.py FAVICON) and served at /images like every picture. /reports/ is an Astro page that scripts/site_reports.sh lists the sim’s reports on.

Amended 2026-11-04 (#894, ADR 0024): every viewer embed carries a plain link to its deep link, which GitHub shows where it cannot draw the viewer; the pages mark what is upcoming in plain Markdown (~~is~~ *will be (#N)*, *Upcoming (#N): …*, a > [!NOTE] for a section), which the Markdown plugin collects into the Roadmap page.

Material for MkDocs reaches end of life on 2027-05-05, and MkDocs 1.x is frozen while 2.0 drops plugins. The site moves to Astro Starlight with its default look: a maintained, widely used tool that keeps the site’s must-haves (numbers from the code, the viewer inside the theme, a self-only CSP), with no paid service anywhere.

  • One npm package in site/. package.json, its lockfile, astro.config.mjs, the content loader, the Markdown plugins, the viewer’s page and module, and their tests. Node 24 LTS (site/.nvmrc, engines), npm, no monorepo tool until a second JS package exists. just site still builds everything: python -m macros, npm ci, astro build into site/dist, then the GLBs, pictures and reports beside it. Install scripts are denied (allowScripts): mermaid-cli’s Puppeteer drives the installed Chrome, as Playwright does.
  • The Markdown stays where it is, with no front matter. Astro’s glob() loader reads the repo’s Markdown in place (site/src/pages.mjs: the root’s *.md and docs/**, not the README, CLAUDE.md or docs/references) into Starlight’s docs collection with docsSchema(). A page’s id is its path, lower-cased; docs/index.md is the landing page at the root, with the sidebar like every page (#740). Starlight needs a title: the loader takes it from the page’s H1, and a Markdown plugin drops the H1 itself, so Starlight draws it once. Pages read the same on GitHub and on the site.
  • Markdown plugins on Astro’s default processor, Sätteri (site/src/markdown.mjs): a relative .md link goes to its page (or to GitHub when the doc is not a page); <!--{{ name }}--> takes the Markdown macros.py writes as JSON (site/src/macros.json, never committed), an unknown name fails the build, and a <!--{# ... #}--> span (what GitHub shows in a table’s place) goes. GitHub-style alerts (> [!WARNING]) become Starlight asides (starlight-github-alerts); buttons are plain links.
  • Starlight’s own features first: Pagefind for search, sidebar for the nav (every ADR listed from the files), editLink, social with a small header component that asks api.github.com for the stars and forks in the browser, <StarlightPage> for the viewer’s page, and a Footer override that loads the viewer’s module on any page with a <div class="noggin-viewer"> (a doc can still drop one in). Mermaid renders in the browser with astro-mermaid from npm.
  • The viewer is an Astro page (site/src/pages/viewer.astro, ADR 0008): its module imports three.js and its addons from npm and Vite bundles them; the Draco decoder is copied from three’s package into the build. The lockfile’s integrity hashes and Dependabot replace vendored.py’s sha384 pins.
  • A hash-based CSP, one policy for every page (Astro’s security.csp, in a <meta>). Scripts: 'self' plus a hash for each inline script, never 'unsafe-inline'. Astro hashes the scripts it bundles; Starlight’s is:inline scripts (theme, menu, sidebar) it does not, so site/src/csp.mjs adds each built page’s missing hashes once the site is built: derived, never listed by hand (ADR 0011), and a Starlight upgrade needs no edit. Styles: 'self' and 'unsafe-inline' for style="" attributes and <style> elements, because Expressive Code (Shiki) writes style attributes and Mermaid injects <style> at run time, which no hash can cover. The viewer’s Draco decoder needs 'wasm-unsafe-eval' and worker-src blob:, GLTFLoader’s textures connect-src blob:, the header connect-src https://api.github.com, Starlight’s icons img-src data:, the pictures’ absolute URLs img-src https://yellowpine.com/noggin/images/ (the site itself, and in a local preview too). Pagefind 1.6 needs nothing more: its worker is the site’s own.
  • Fresh URLs, no redirects. Starlight’s paths under /noggin/: docs/ keeps its paths (/noggin/docs/build/parts/), the root’s pages are lower-cased (/noggin/glossary/).
  • Tests at the built site’s seam. Vitest over site/dist (site/site.test.mjs): every doc a page titled by its H1, every link lands, each number the JSON’s, every inline script hashed in the CSP, no photo; and every diagram drawn by mermaid-cli (a devDependency, so the lockfile pins the Mermaid it uses, the site’s). One Playwright smoke test in the installed Chrome (site/smoke.pw.mjs): the viewer loads Stage 1, the diagrams draw, search finds a page, the header names the newest release, an old Docs version’s URL lands on the docs, with no CSP violation or console error and no request to another host but api.github.com. pytest keeps the Python-only checks (the numbers macros.py derives, the README, photos out of git, the workflows).
  • CI keeps its shape (#310, #496): Checks’ Site job sets up Node by .nvmrc with npm’s cache, runs just site, with the pictures and the viewer, then Vitest and Playwright, and uploads site/dist (#732); Checks’ Deploy deploys it (#795). Dependabot covers npm, grouped like uv and Actions, each release waiting 14 days.
  • Zensical (Material’s successor, reads mkdocs.yml): rejected for now, 0.x with no hooks or plugin API yet, and docs_dir: . unsupported (#331’s research).
  • ProperDocs + Material: buys time only until Material’s end of life.
  • Docusaurus: built-in versions snapshot pages into the repo (against ADR 0009); VitePress: 2.0 still alpha, no Mermaid or versions.
  • Starlight’s docsLoader(): reads src/content/docs/ only, so the Markdown would move out of its place.
  • MDX components (<CardGrid>, <Aside>) for cards and callouts: GitHub would show their imports and JSX.
  • Hand-listing Starlight’s inline-script hashes in the config: they change with each Starlight release.
  • astro-shield (SRI and CSP for inline scripts): a second CSP writer beside Astro’s own security.csp; adding the missing hashes to Astro’s policy is a dozen lines (site/src/csp.mjs).
  • 'unsafe-inline' for scripts (the MkDocs policy): not needed, every script is the site’s own or hashed.
  • rehype-mermaid (build-time SVGs, no style injection): no release since 2024 and it pins Mermaid 11.
byYellow PineYellow Pine

noggin v0.2.26-6-g09bf9b7 · 09bf9b7