Ryan Malloy
61d9c1d0b2
Starlight renders the logo as an <img>, so CSS can't reach inside it. The single cream-on-near-black SVG left a cream wordmark on a cream page. Ship a light variant with warm ink and the darker brass the light theme already uses.
119 lines
4.3 KiB
JavaScript
119 lines
4.3 KiB
JavaScript
// The Cuckoo Escapement — Starlight, diátaxis-shaped.
|
|
//
|
|
// This site is a FIELD REPORT, not a tutorial. The build guides already exist
|
|
// (geerlingguy/time-pi, josh-blake/pixie) and they're good. What doesn't exist
|
|
// is a record of everything they get wrong on a Pi 4, with numbers. So the IA is
|
|
// deliberately inverted from the usual docs site: heavy on Explanation and
|
|
// Reference, and there is no Tutorial section at all.
|
|
//
|
|
// Telemetry + devToolbar off per project convention. The HMR block is required
|
|
// when the dev server runs behind Caddy (TLS-terminating proxy) — without an
|
|
// explicit host/protocol/clientPort, Vite's WebSocket drops every ~10s.
|
|
//
|
|
// Site URL comes from DOMAIN so one image serves both escapement.warehack.ing (prod)
|
|
// and escapement.l.warehack.ing (local dev).
|
|
|
|
import mdx from "@astrojs/mdx";
|
|
import sitemap from "@astrojs/sitemap";
|
|
import starlight from "@astrojs/starlight";
|
|
import { defineConfig } from "astro/config";
|
|
import remarkGfm from "remark-gfm";
|
|
import starlightLinksValidator from "starlight-links-validator";
|
|
|
|
const domain = process.env.DOMAIN ?? "escapement.warehack.ing";
|
|
|
|
export default defineConfig({
|
|
site: `https://${domain}`,
|
|
telemetry: false,
|
|
devToolbar: { enabled: false },
|
|
|
|
vite: {
|
|
server: {
|
|
host: "0.0.0.0",
|
|
hmr: { host: domain, protocol: "wss", clientPort: 443 },
|
|
},
|
|
},
|
|
|
|
integrations: [
|
|
starlight({
|
|
title: "The Cuckoo Escapement",
|
|
description:
|
|
"What the Raspberry Pi time-server guides get wrong, and the numbers to prove it. " +
|
|
"GPS Stratum 1 on a Pi 4: PREEMPT_RT makes PPS jitter worse, the PPS interrupt " +
|
|
"cannot be pinned, PTP is impossible, and your dashboard is taxing your clock.",
|
|
|
|
// The mark IS the word "cuckoo" — a rebus. replacesTitle stops Starlight
|
|
// rendering the title text beside it (which would read "…escapement The
|
|
// Cuckoo Escapement"). The SVG's aria-label carries the full name.
|
|
//
|
|
// Two variants, because Starlight renders the logo as an <img> and CSS
|
|
// cannot reach inside it. The single cream-on-black logo was invisible in
|
|
// the light theme — cream wordmark on a cream page.
|
|
logo: {
|
|
light: "./src/assets/logo-light.svg",
|
|
dark: "./src/assets/logo.svg",
|
|
replacesTitle: true,
|
|
},
|
|
favicon: "/favicon.svg",
|
|
customCss: ["./src/styles/brass.css"],
|
|
|
|
social: [
|
|
{
|
|
icon: "seti:git",
|
|
label: "Source",
|
|
href: "https://git.supported.systems/warehack.ing/cuckoo-escapement",
|
|
},
|
|
],
|
|
|
|
// Diátaxis, but weighted for a field report. Explanation leads, because the
|
|
// whole point is WHY the received wisdom is wrong. There is no Tutorial —
|
|
// that would be the one thing the world does not need another of.
|
|
// NB: Starlight >=0.39 removed the inline {label, autogenerate} shorthand;
|
|
// it must be nested as {label, items: [{autogenerate}]}.
|
|
sidebar: [
|
|
{
|
|
label: "Start here",
|
|
items: [
|
|
{ label: "What this is (and isn't)", slug: "index" },
|
|
{ label: "The findings, in brief", slug: "findings" },
|
|
],
|
|
},
|
|
{
|
|
label: "Explanation",
|
|
items: [{ autogenerate: { directory: "explanation" } }],
|
|
},
|
|
{
|
|
label: "Reference",
|
|
items: [{ autogenerate: { directory: "reference" } }],
|
|
},
|
|
{
|
|
label: "How-to",
|
|
items: [{ autogenerate: { directory: "how-to" } }],
|
|
},
|
|
],
|
|
|
|
components: {
|
|
// Appends the "A Supported Systems Joint" badge under Starlight's default
|
|
// footer, without rewriting the component.
|
|
Footer: "./src/components/Footer.astro",
|
|
},
|
|
|
|
plugins: [
|
|
starlightLinksValidator({
|
|
// Broken internal links fail the build rather than shipping silently.
|
|
errorOnRelativeLinks: false,
|
|
}),
|
|
],
|
|
|
|
pagination: true,
|
|
lastUpdated: true,
|
|
}),
|
|
// GFM tables do NOT render in .mdx without this, even though they work fine
|
|
// in plain .md — Astro's remark-gfm doesn't reach the MDX pipeline here. The
|
|
// failure is silent and ugly: the table falls through as a paragraph of raw
|
|
// pipe characters. It shipped that way on the landing page. Don't remove.
|
|
mdx({ remarkPlugins: [remarkGfm] }),
|
|
sitemap(),
|
|
],
|
|
});
|