loadout site

The landing page and documentation for loadout, a curated shell environment you configure.

Built with Astro and Starlight. Static output, no client-side framework.

Running it

npm install
npm run dev        # http://localhost:4321

Command	What it does
npm run dev	Dev server with hot reload
npm run build	Static build into dist/
npm run preview	Serve dist/ as it will be deployed
npm run gen	Regenerate the catalog reference from the loadout repository
npm run refresh	gen then build

Layout

src/
  pages/index.astro          the landing page, hand-written
  components/
    SiteTitle.astro          header lockup: inline mark + real text
    Field.astro              the brand's field composition
  content/docs/
    start/                   what it is, install, getting started, how it works
    guides/                  configuration, credentials, sync, the web UI, …
    reference/               commands, schema, and the generated catalog
    internals/               architecture, portability, security, releasing
  styles/
    tokens.css               copied from the brand assets
    brand.css                the brand mapped onto Starlight's variables
scripts/gen-reference.mjs    catalog → reference pages

The generated reference

reference/aliases.md, reference/functions.md and reference/packs.md are generated — do not edit them by hand. They are produced from the shipped catalog:

../loadout/internal/catalog/data/aliases.yaml     136 aliases
../loadout/internal/catalog/data/functions.yaml    14 functions

npm run gen                          # expects ../loadout alongside this repo
LOADOUT_REPO=~/src/loadout npm run gen

The output is committed, so the site builds in CI without a loadout checkout. Re-run it after every loadout release and commit the diff — that diff is exactly what changed in the shipped set.

To change an alias, change it in the loadout repository, not here.

Deployment

GitHub Actions builds on push to main and deploys to GitHub Pages. There is nothing to configure. The workflow derives the URL and base path from the repository itself, because the owner and repository name are exactly what decide them:

Repository name	Served at	Base path
loadoutsh.github.io	https://loadoutsh.github.io	none
anything else, e.g. site	https://loadoutsh.github.io/site/	/site/

Getting this wrong is not a visible error — the build succeeds and every stylesheet and link 404s — which is why it is computed rather than left to a variable someone has to remember after renaming a repository.

Later, with a domain

Set one repository variable:

Variable	Value
CUSTOM_DOMAIN	loadout.sh

That switches the site to the root of that domain and writes the CNAME into the artefact. Point the DNS at GitHub Pages and nothing else changes.

Internal documentation links are relative, so they survive all three arrangements.

Enabling Pages

Once, in the repository: Settings → Pages → Source → GitHub Actions. Without that the workflow's deploy step fails with a permissions error rather than anything descriptive.

Brand

The palette, typography and the field system come from the loadout brand assets. src/styles/tokens.css is a copy; src/styles/brand.css maps it onto Starlight's own variables.

Two assets are deliberately not used as shipped:

• The header lockup is an inline mark plus real text, because the lockup SVG hardcodes ink (invisible in dark mode) and names IBM Plex Sans, which an <img>-loaded SVG cannot resolve from the page's fonts.
• The favicon carries a prefers-color-scheme swap, because the brand asset is ink on transparent and disappears in a dark tab strip.

IBM Plex is self-hosted through @fontsource, so no request leaves the page.

Licence

Documentation content: same licence as loadout, MIT. Brand assets are governed by the brand repository.