Cachix documentation

docs.cachix.org is built with Astro, Starlight, and @cachix/site-kit. The site uses the Cachix logo, Mulish font, and brand colors from cachix.org.

Development

Use Node.js 24 and npm. nix-shell provides Node.js and Lychee (the link checker).

nix-shell
npm ci
npm run dev

Open the local URL printed by Astro. Changes reload automatically. ./live is also available after installing dependencies.

Edit Markdown in src/content/docs/; navigation is in src/navigation.mjs, and brand styles are in src/styles/cachix.css. Site-kit is pinned to an immutable HTTPS commit tarball in package.json and package-lock.json.

Validation and publishing

npm test                 # types, build, internal links, and legacy URLs/anchors
npm run preview          # preview dist/, including working search
nix-build                # reproducible build with the same checks

Production is the Cloudflare Pages project docs-cachix-org. wrangler.toml sets its output directory to dist; .nvmrc selects Node.js 24. Search is generated by Pagefind during production builds. The build clears Astro's content cache so changes to code-block themes cannot leave stale stylesheet references. public/_headers requests revalidation for documents and search assets on every visit. Astro's fingerprinted assets retain the host's normal caching policy.

The cachix.org zone currently overrides these headers on the custom domain with a four-hour browser cache TTL, even with explicit no-cache. To make deployments visible immediately on repeat visits, add a Cloudflare Cache Rule matching http.host eq "docs.cachix.org" with Browser TTL set to Respect origin (browser_ttl: { mode: "respect_origin" }). This needs zone cache-settings write access; Pages deployment access alone is insufficient. Until that rule is applied, returning visitors may need a hard refresh. Purging Cloudflare's edge cache cannot clear copies already stored in visitors' browsers.

Browser checks

npx playwright install chromium
npm run check:browser
DOCS_BASE_URL=https://your-preview.docs-cachix-org.pages.dev npm run check:browser
node scripts/check-hosted.mjs https://your-preview.docs-cachix-org.pages.dev

The browser suite checks desktop, tablet, and two mobile widths, search, clipboard copying, keyboard navigation, accessibility, and screenshots. CI retains its HTML report and screenshots. On NixOS, use a system Chromium with PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/path/to/chromium.

Cloudflare deployments

npx wrangler pages deploy dist --project-name docs-cachix-org --branch astro-migration --commit-dirty=true

This creates a preview without replacing production. Pushes to master trigger production builds. The Pages project must use npm run build, output directory dist, and build image v3 for both environments. Node.js 24 is selected by .nvmrc.

Verified migration preview (2026-09-05)

Open the reviewed deployment. The astro-migration.docs-cachix-org.pages.dev alias points to its latest preview.

• npm test and nix-build --no-out-link passed.
• All 31 legacy pages and 128 anchors are preserved. The hosted comparison passed for those pages and the old search URL, including existing redirects.
• 26 Chromium browser checks passed locally and on Cloudflare at widths 1440, 900, 390, and 320 pixels. The two desktop mobile-menu cases are intentionally skipped. Search, clipboard commands, keyboard navigation, and automated WCAG checks on articles, the telemetry table, and search passed.
• Desktop and mobile screenshots were inspected against cachix.org's logo, typography, white surfaces, neutral grays, and blue accents.

This preview was validated before the merge to master. The last Sphinx production deployment was 016fce23-b395-4be2-9de2-0f7717860ee9; retain it as the migration rollback target. Reverting the source to Sphinx also requires restoring build command pip install poetry && poetry install && make html, output directory /build/html, and build image v1.

URL compatibility

Keep the explicit slug frontmatter, including .html and nested index.html paths. Headings use {#original-id} to preserve Sphinx deep links; standalone anchors preserve labels and glossary terms. New headings can use the same syntax when a stable ID is needed.

The literal .html Astro route handles these URLs in development. After building, html-file-routes.mjs flattens Astro's directory output to actual .html files. Navigation, canonical URLs, the sitemap, and search all use the same addresses. Cloudflare Pages retains its existing redirects: /guide.html redirects to /guide, and /deploy/index.html redirects to /deploy/. The hosted check compares these redirects, query strings, page headings, and anchors against production. Unknown paths now return a proper 404 instead of the existing host's 200 home-page fallback. Legacy addresses and their deep links remain valid. / and /index.html share the home page. /search.html?q=… and /genindex.html remain available.

scripts/legacy-urls.json records the old pages and anchors. The compatibility check prevents their accidental removal. public/_sources/ and public/objects.inv are frozen Sphinx compatibility downloads; edit the Markdown, not these snapshots.

Documentation remains under the license in LICENSE.md.