felis-docs

Documentation site for felis — tutorials, how-to guides, reference, and the design docs, on the Diátaxis map — built with Astro Starlight and themed to look like a terminal — every base16 colour scheme is selectable at runtime.

Where the content lives

The content itself is not in this repository. It lives in the felis repo under docs/ (next to the code it documents, so it can't rot) and is vendored here via the vendor/felis submodule — every entry of docs/ is symlinked into src/content/docs/, so site routes mirror the repo layout (docs/reference/spec.md → /reference/spec/). The only pages authored here are the landing page and the site chrome. The sidebar groups in astro.config.mjs mirror the reading order in felis docs/README.md.

Relative links inside the docs are rewritten at build time (plugins/remark-felis-links.mjs): links between published pages become site routes; links escaping docs/ (crate sources, the config JSON schema) become URLs into the felis repository.

Updating the docs

A docs change lands in felis first. Publishing it here is a submodule bump:

git submodule update --remote vendor/felis
git commit -am 'chore: bump felis docs'
git push   # CI rebuilds and deploys

The same flow with vendor/schemes picks up new base16 schemes.

Development

The Nix flake pins the toolchain (Node.js + wrangler):

nix develop
git submodule update --init   # felis docs + base16 schemes
npm install
npm run dev                   # generates schemes, serves on :4321

npm run generate converts vendor/schemes/base16/*.yaml into src/generated/schemes.json (picker UI) and src/styles/base16.generated.css (one [data-base16="…"] rule per scheme). Both are gitignored — the submodule pin is the source of truth.

Theming model

• ThemeProvider.astro applies the stored scheme before first paint and sets Starlight's data-theme from the scheme's dark/light variant.
• ThemeSelect.astro replaces Starlight's dark/light toggle with a picker over every scheme.
• terminal.css maps Starlight's grey ramp + accents onto --base00..--base0F, and code blocks use Shiki's css-variables theme so syntax highlighting follows the palette (Expressive Code is disabled — it bakes token colours per theme at build time, which doesn't scale to ~250 runtime-switchable schemes).

Deploy

Forgejo Actions (.forgejo/workflows/deploy.yml) builds on push to main and deploys dist/ to Cloudflare Pages with wrangler. Repo secrets required: CLOUDFLARE_API_TOKEN (Pages:Edit) and CLOUDFLARE_ACCOUNT_ID.