The public showcase and documentation hub for the whole system — Astro, Tokyo Night, GitHub Pages.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
dotfiles-web is the public showcase + documentation hub for the
dotgibson dotfiles system — an eleven-repo,
three-layer terminal environment (Core → OS-native → Role). It documents the
system rather than configuring a machine, so it is not itself one of the three
layers. Built with Astro, themed in Tokyo Night, and
deployed to GitHub Pages at
dotgibson.github.io/dotfiles-web.
The site is data-driven and largely source-derived: the showcase cards, the
per-repo docs pages, the "by the numbers" strip, and the changelog are generated
from src/data/* and from the sibling repos — so the docs can't silently drift
from the code they describe.
| Page | Path | Purpose |
|---|---|---|
| Landing | / |
Hero, the three-layer model, the repo map, install |
| Getting started | /getting-started |
Per-platform install guide |
| Architecture | /architecture |
The layer model, subtree rationale, the loader, deep dives |
| Docs hub | /docs |
Concepts, guides, reference, and a generated page per repo |
| Changelog | /changelog |
A mirror of each repo's CHANGELOG.md |
Node.js (with npm). The site is a standard Astro project — no global tooling
beyond that.
git clone https://github.com/dotgibson/dotfiles-web ~/dotfiles-web
cd ~/dotfiles-web
npm install
npm run dev # local dev server at http://localhost:4321/dotfiles-webnpm run dev # local dev server
npm run build # production build into dist/
npm run preview # preview the production build
npm run check # astro check (types + content collections)Content is data-driven — edit these and the site updates:
src/data/site.ts— site name, owner, nav, GitHub linkssrc/data/repos.ts— the repository map / per-repo pages (prose + status)src/data/install.ts— per-platform install stepssrc/content/docs/**/*.md— the documentation hub pages
The "by the numbers" strip, per-card package counts, the changelog, the Config
explorer's baked files, and the /purple corpus + detection-coverage tables are
not hand-typed — four collectors under scripts/ derive them from the sibling
repos into src/data/:
| file | collector | source repo |
|---|---|---|
generated.json |
collect-metrics.mjs |
the eleven dotfiles repos |
snippets.json |
collect-snippets.mjs |
eight curated files across six of them |
corpus.json |
collect-corpus.mjs |
htpx |
coverage.json |
collect-coverage.mjs |
dotfiles-Defense |
Regenerate and commit whenever a source repo changes — run all four, not just one, or the untouched files quietly fall behind:
npm run data # checkout the sibling repos next to this one first
npm run data:lenient # warn instead of failing — read the caveat below firstnpm run data is the publish path, so it is strict: a missing repo, and a sibling
that is parked on a feature branch or carrying uncommitted edits in a file the
collectors read, both fail the run instead of being absorbed into the committed data.
That second check exists because it happened — a dotfiles-core checked out on a
feature branch published a changelog entry that was on no branch of Core's main.
Each individual collector (npm run metrics, corpus, coverage) stays lenient for
exploratory runs, and npm run data:lenient is the whole pipeline in that mode. Note
that "lenient" means two different things depending on which check trips, and only one
of them is harmless:
- source repo absent — the committed file is left alone and the run exits 0, so a fleet-less runner can't zero the data. Nothing is published that wasn't already there.
- fleet present but unclean — the run warns and still writes, absorbing the
unmerged work. The snapshot is stamped
generatedFrom.clean: false, which is what the two guards below key on, but the contaminated file is on disk either way.
So the lenient path is fine for looking, and is not a publish path. fleet-sync.yml runs all four weekly and opens a PR when the
output drifts; data-freshness.yml fails CI when any of the four committed files no
longer matches its source — it clones the fleet, re-runs all four collectors and diffs the
result — and additionally when generated.json's Core version is behind the latest
dotfiles-core release. The second check is not redundant: it asks whether the data names
the latest release, while the regeneration asks whether it matches the fleet's current
state, and it keeps working when the clones fail.
Because the lenient path still writes (with a warning), the thing that actually
publishes — the commit — is guarded in two places, both reading the
generatedFrom.clean verdict that collect-metrics.mjs and collect-snippets.mjs
stamp into their files. They cover the same two files, but not the same ground:
| guard | scope | files | installed by |
|---|---|---|---|
pre-commit hook |
one machine | generated.json + snippets.json |
npm install (or npm run hooks:install) |
committed-data-provenance |
every PR, every machine | generated.json + snippets.json |
data-freshness.yml |
The difference is scope, and it is the whole point: the hook lives in .git/hooks, is
untracked, is skipped when core.hooksPath is set, and is one --no-verify away from
irrelevant, so it protects exactly one machine. The CI job is the durable half.
Both matter most for snippets.json, because collect-snippets.mjs only warns on an
unclean fleet and writes anyway — unlike collect-metrics.mjs, which refuses outright.
That asymmetry also changes the advice: for generated.json, re-running the collector
fixes things; for snippets.json, re-running against a still-dirty tree just reproduces
the problem, so the repos have to be settled first. Until #160 the hook did not stage
snippets.json at all, and CI was the only thing standing between an absorbed local edit
and its publication on /config as a repo's real configuration.
The hook follows the same rules as dotfiles-core's core guard: it never clobbers an
existing pre-commit, and it skips — loudly — when core.hooksPath is set, since
writing into an ignored .git/hooks would be false protection rather than protection.
Bypass a single commit with DOTFILES_ALLOW_DIRTY_DATA=1 git commit … or
--no-verify; the CI job is the one that can't be bypassed.
Pushing to main triggers .github/workflows/deploy.yml (Astro build → GitHub
Pages). A source repo can ping a rebuild via repository_dispatch; the token and
secret walkthrough lives in docs/WEBHOOK-SETUP.md.
Because this site restates facts that live elsewhere — the repo count, the three-layer model, per-platform install commands — it is the easiest place for documentation to drift from reality.
- Treat the source-of-truth repos as canonical and keep the site in step; the
/doc-auditroutine indotfiles-corechecks exactly this cross-repo consistency. - Keep content in the data files (
src/data/*,src/content/docs/*) rather than hard-coding it into pages. - Green the gate.
npm run check(0 errors) andnpm run buildbefore you push.
Bugs and ideas: open an issue.
Distributed under the MIT License. See LICENSE for more information.
Garrett Allen - @gerrrrt - garrettallen2@gmail.com - LinkedIn
Project Link: dotgibson