docs: add the handbook and publish it to pages

hutao commented

2026-09-25 18:18:38 +00:00

Owner

An mdBook handbook in docs/, published to pages, with the README cut down to the short version. Same shape as the vps repo's handbook.

What's in it

The book (docs/src/): architecture (hosts and layers, the user layer, colours, secrets, network and the tailnet, the laptop as a third monitor) and operations (installing, rebuilding and deploying, the VM and install rehearsal, CI and pages, known hazards). Diagrams are mermaid, so they also render in the Forgejo UI.
Pages (.forgejo/workflows/pages.yml): builds the book on every push to main and uploads a pages artifact. The VPS's pages-pull serves it at https://pages.hu-tao.dev/hutao/nixos-dotfiles/docs/; nothing on the VPS lists this repo. Runs on nix-node, so no node-on-PATH step.
Pre-commit hook: mdbook build, so a broken book fails on the commit and in PR CI rather than first in the main-only pages run. It catches what mdbook rejects (a SUMMARY.md chapter with no file); a dead link inside a page still builds.
README: badges, the tree, a chapter index and a quick start. The stale parts it carried (four secrets where nine are declared, an NTFS HDD that is LUKS ext4, art that moved to third-party-assets, the install.sh line count and patch list) are corrected in the book. install.sh and secrets.example.yaml point at the chapters instead of README sections that no longer exist.
nix run .#docs serves the book with live reload; both dev shells gain mdbook and mdbook-mermaid.

Checked

mdbook build docs in the CI shell; the new hook fails on a missing chapter and passes clean.
pre-commit run --all-files clean.
All five diagrams rendered with mermaid-cli, which fails on a deliberately broken one.
Every fact in the book checked against the modules it describes.

Not yet

The pages workflow only runs on main, so its first real run is this merge.

An mdBook handbook in `docs/`, published to pages, with the README cut down to the short version. Same shape as the vps repo's handbook. ## What's in it - **The book** (`docs/src/`): architecture (hosts and layers, the user layer, colours, secrets, network and the tailnet, the laptop as a third monitor) and operations (installing, rebuilding and deploying, the VM and install rehearsal, CI and pages, known hazards). Diagrams are mermaid, so they also render in the Forgejo UI. - **Pages** (`.forgejo/workflows/pages.yml`): builds the book on every push to `main` and uploads a `pages` artifact. The VPS's `pages-pull` serves it at https://pages.hu-tao.dev/hutao/nixos-dotfiles/docs/; nothing on the VPS lists this repo. Runs on `nix-node`, so no node-on-PATH step. - **Pre-commit hook**: `mdbook build`, so a broken book fails on the commit and in PR CI rather than first in the main-only pages run. It catches what mdbook rejects (a `SUMMARY.md` chapter with no file); a dead link *inside* a page still builds. - **README**: badges, the tree, a chapter index and a quick start. The stale parts it carried (four secrets where nine are declared, an NTFS HDD that is LUKS ext4, art that moved to third-party-assets, the install.sh line count and patch list) are corrected in the book. `install.sh` and `secrets.example.yaml` point at the chapters instead of README sections that no longer exist. - `nix run .#docs` serves the book with live reload; both dev shells gain `mdbook` and `mdbook-mermaid`. ## Checked - `mdbook build docs` in the CI shell; the new hook fails on a missing chapter and passes clean. - `pre-commit run --all-files` clean. - All five diagrams rendered with mermaid-cli, which fails on a deliberately broken one. - Every fact in the book checked against the modules it describes. ## Not yet - The pages workflow only runs on `main`, so its first real run is this merge.

hutao added 4 commits

2026-09-25 18:18:38 +00:00

feat(docs): add the handbook, an mdBook in docs/ 1bb0be282d

The same shape as the vps repo's handbook: docs/src/ is the source, the
render is gitignored, and diagrams are mermaid so they also render in the
Forgejo UI and in a pull request. Eleven chapters across architecture
(hosts and layers, the user layer, colours, secrets, the network, the
laptop as a third monitor) and operations (installing, deploying, the VM,
CI and pages, known hazards), taking over the depth the README carried and
correcting what had gone stale in it.

`nix run .#docs` serves it with live reload; both dev shells gain mdbook
and mdbook-mermaid.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

feat(ci): publish the handbook to pages.hu-tao.dev 56db965e07

The vps repo's pages.yml, trimmed: build the book on every push to main
and upload it as an artifact named `pages`, which the VPS's pages-pull
discovers on any public repo and serves at
https://pages.hu-tao.dev/hutao/nixos-dotfiles/docs/. Nothing on the VPS
lists this repo. Runs on nix-node, so unlike the vps copy it needs no
dev-shell node on PATH for the upload action.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

feat(ci): build the handbook in pre-commit 0c922f4163

The pages workflow only runs on main, so a broken book would otherwise
first fail after merge. As a hook it fails on the commit that breaks it,
and in CI on every pull request. It catches what mdbook rejects, such as a
SUMMARY.md chapter with no file; a dead link inside a page still builds,
which the hook's comment says rather than overstating.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

docs(readme): keep the short version, point at the handbook

CI / Evaluate the installer image (pull_request) Successful in 1m0s

Details

CI / Format and lint (pull_request) Successful in 1m12s

Details

9d77e559bf

The README carried the whole manual, and parts had gone stale: four
secrets where nine are declared, an NTFS HDD that is LUKS ext4, art that
has since moved to third-party-assets, an install.sh line count and patch
list that no longer matched. The depth now lives in docs/ and is corrected
there; the README becomes the vps repo's shape -- badges, the tree, the
chapter index and a quick start.

install.sh and secrets.example.yaml pointed at README sections that no
longer exist; they now point at the handbook chapters.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

hutao added 2 commits

2026-09-25 18:36:49 +00:00

docs(handbook): correct the deploy story and untangle the diagrams 6f210a65b5

The introduction drew deploy-rs from the desktop to the laptop as if that
were the only direction and the only deploy. The flake declares one node,
hutao-laptop, deployable from any machine on the tailnet with Nix; the
desktop has none and is rebuilt in place. The VPS is deploy-rs too, from
its own repo, over its own sshd on 2222 rather than Tailscale SSH, which
the book never mentioned.

The hosts and introduction diagrams had crossing edges and colliding
labels. The hosts one becomes the sentence it was trying to say, and the
introduction's becomes two tables: the machines, and who talks to whom.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

docs(agents): keep the handbook in step at the end of every task

CI / Evaluate the installer image (pull_request) Successful in 1m1s

Details

CI / Format and lint (pull_request) Successful in 1m12s

Details

03af326d08

A repo-level AGENTS.md with one rule: before a task is done, check
docs/src/, the README and the comments that point into the docs against
what changed, and update them on the same branch -- or say that nothing
needed changing. The book build does not check links inside a page, so
the rule says to follow those by hand.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

hutao merged commit 2e914839ff into main

2026-09-25 18:38:17 +00:00

hutao referenced this pull request from a commit

2026-09-25 18:38:18 +00:00

Merge pull request 'docs: add the handbook and publish it to pages' (#3) from docs/mdbook-creation into main

Rows
Columns

docs: add the handbook and publish it to pages #3

What's in it

Checked

Not yet