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 ten dotfiles repos |
snippets.json |
collect-snippets.mjs |
the OS repos' config files |
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 the committed corpus.json /
coverage.json no longer match their sources, or when generated.json's Core version
is behind the latest dotfiles-core release.
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 stamps into the file:
| guard | scope | installed by |
|---|---|---|
pre-commit hook |
one machine | npm install (or npm run hooks:install) |
committed-data-provenance |
every PR, every machine | data-freshness.yml |
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