Development

Working on the dotfiles themselves.

Formatting

just format    # biome + prettier + shfmt across the repo

Commits

Commits follow Conventional Commits. The commit-msg hook enforces it. See Git Workflow.

CI

• shellcheck on every shell script
• A scripts sanity check
• Tagging vX.Y.Z cuts a GitHub release, with notes generated by git-cliff, and refreshes CHANGELOG.md
• The repository is mirrored to GitLab
• Changes under docs/ rebuild and deploy this site to GitHub Pages

Working on the docs

The docs site is VitePress. Everything, including package.json, lives in docs/:

cd ~/dotfiles/docs
pnpm install
pnpm docs:dev       # live preview
pnpm docs:build     # production build, fails on dead links

To add a page, create a Markdown file under docs/ and add it to the sidebar in docs/.vitepress/config.mts.

Adding things

To add...	Do this
A config package	See GNU Stow
A package to install	Add it to the right list in scripts/utils/software_lists.sh
A shell function	See Shell Reference