lyrathorpe/nixfiles
1
0
Fork 0
Code Issues 6 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: move prose documentation into docs/ so the docs site publishes it
CI / flake (push) Skipped
CI / flake (pull_request) Successful in 4m21s
Details

Browse Source 
The docs-site build syncs this repo's README.md and docs/ into the site
tree; nothing else is copied. All prose apart from the README therefore lived
outside the sync and never appeared on https://docs.lyrapup.pet/nixfiles/, and
the one page that did publish carried 18 link targets that resolved to nothing.

Moves:

  home/README.md           -> docs/shell.md
  home/KEYBINDINGS.md      -> docs/keybindings.md
  hosts/<Name>/README.md   -> docs/hosts/<name>.md

docs/.pages and docs/hosts/.pages give the awesome-pages plugin an explicit
order; new pages are picked up by the trailing '...' without an edit.

Links are rewritten so a single URL is correct in both Gitea and the published
site: absolute Gitea source URLs for .nix files and directories, relative links
between pages under docs/, and absolute docs.lyrapup.pet URLs from the root
README, which the build republishes at a different depth from the rest of the
tree. In-code comments that pointed at a moved README are updated to the new
path.

The README gains a Documentation section covering the sync contract and the
linking rules, and CLAUDE.md carries the short version so future edits do not
reintroduce unsynced pages or dead links.

Verified by reproducing the docs-site assembly locally against its pinned
toolchain (mkdocs 1.6.1, mkdocs-material 9.7.7, awesome-pages 2.10.1): pages
render at the URLs used above and in the declared order.
This commit is contained in:
Emma Thorpe
2026-08-19 17:38:50 +01:00
parent d30d8f9892
commit dcc13f94e0
16 changed files with 111 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+56 -23
View File
@@ -5,16 +5,16 @@ single flake.
## Hosts
Defined in the host table in [`flake.nix`](./flake.nix):
Defined in the host table in [`flake.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/flake.nix):
| Configuration | System | Machine |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) |
| `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](./hosts/T400/README.md) |
| `lyrathorpe-macpro31` | `x86_64-linux` | Mac Pro 3,1, desktop — [install notes](./hosts/MacPro31/README.md) |
| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) — [notes](./hosts/EDaaS/README.md) |
| `lyrathorpe-rpi5` | `aarch64-linux` | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](./hosts/RPi5/README.md) |
| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) — [notes](./hosts/Darwin/README.md) |
| Configuration | System | Machine |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `lyrathorpe-mbp` | `aarch64-linux` | MacBook Pro (Apple Silicon, Asahi) |
| `lyrathorpe-t400` | `x86_64-linux` | ThinkPad T400 — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/t400/) |
| `lyrathorpe-macpro31` | `x86_64-linux` | Mac Pro 3,1, desktop — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/macpro31/) |
| `emmathorpe-edaas` | `x86_64-linux` | Work WSL box (NixOS-WSL) — [notes](https://docs.lyrapup.pet/nixfiles/hosts/edaas/) |
| `lyrathorpe-rpi5` | `aarch64-linux` | Raspberry Pi 5 headless server: Docker host + nginx reverse proxy — [install notes](https://docs.lyrapup.pet/nixfiles/hosts/rpi5/) |
| `lyrathorpe-mac` | `aarch64-darwin` | macOS (nix-darwin) — [notes](https://docs.lyrapup.pet/nixfiles/hosts/darwin/) |
Shared layers: `home` (home-manager: shell, git, editor),
`modules/common-nixos.nix` (all NixOS hosts: fonts, nix-ld, caches),
@@ -31,6 +31,7 @@ flake.nix # inputs, mkHost/mkDarwinHost, the host tables, dev shell
flake.lock # pinned input revisions (Renovate keeps this fresh)
modules/ # reusable NixOS system modules (see "Module catalogue")
home/ # home-manager profile: shell, git, editor, claude, secret-service, desktop, sway
docs/ # all prose documentation; published to docs.lyrapup.pet (see "Documentation")
users/ # identity registry + per-user home extras (see "Users")
hosts/<Name>/ # per-machine config: configuration.nix + hardware-configuration.nix
lib/ # small pure helpers (currently the Catppuccin Mocha palette)
@@ -50,7 +51,7 @@ host's table entry.
## Module catalogue
Reusable NixOS modules under [`modules/`](./modules). "Imported by" says how a
Reusable NixOS modules under [`modules/`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules). "Imported by" says how a
module reaches a host: **baseModules** (every NixOS host, via `flake.nix`),
**host table** (listed explicitly per host in `flake.nix`), or **transitively**
(pulled in by another module's `imports`).
@@ -86,7 +87,7 @@ declares what it is and the shared modules derive from that:
are level 1). Ignored on non-x86_64 hosts.
- `features.claudeCode.enable` — derived: on unless the host is below
x86-64-v2, because Claude Code's Node runtime needs SSE4.2/POPCNT.
[`home/claude.nix`](./home/claude.nix) reads it through home-manager's
[`home/claude.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/claude.nix) reads it through home-manager's
`osConfig` and installs nothing (CLI, `CLAUDE.md`, output style, memory
symlink) when it is off. Hosts with no such option — the Darwin host and the
standalone `homeConfigurations` — fall back to enabled.
@@ -101,12 +102,12 @@ editing every host.
Identity is data, kept separate from the reusable modules:
- [`users/registry.nix`](./users/registry.nix) — one entry per user (display
- [`users/registry.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/registry.nix) — one entry per user (display
name, email, supplementary groups, authorized + signing keys). This is the
single source of identity; no user data is hardcoded in the modules.
- Each host's table entry declares a `users` set keyed by username; every entry
lists that user's home-module composition (the shared `./home` bundle plus any
per-user modules, e.g. [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix))
per-user modules, e.g. [`users/emmathorpe/work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix))
and optional per-host-user system bits such as `linger`.
- `mkHost` builds each account from the registry and injects the matching
identity into that user's home config as the `identity` module arg. A host can
@@ -114,13 +115,13 @@ Identity is data, kept separate from the reusable modules:
Per-user home extras live under `users/<name>/`:
- [`users/lyrathorpe/home.nix`](./users/lyrathorpe/home.nix) — personal extras
- [`users/lyrathorpe/home.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/lyrathorpe/home.nix) — personal extras
(an ssh host shortcut, gammastep coordinates); imported on Lyra's hosts.
- [`users/emmathorpe/work.nix`](./users/emmathorpe/work.nix) — the work
- [`users/emmathorpe/work.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/work.nix) — the work
toolchain (kubectl/helm/az/etc.), work-only LSP servers, the corporate ssh
handling, and the headless Secret Service that gcx needs for its keychain
tokens (see [`home/secret-service.nix`](./home/secret-service.nix)); imports
[`users/emmathorpe/renovate-review.nix`](./users/emmathorpe/renovate-review.nix),
tokens (see [`home/secret-service.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/home/secret-service.nix)); imports
[`users/emmathorpe/renovate-review.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/users/emmathorpe/renovate-review.nix),
the daily headless Renovate-PR review timer (EDaaS only).
### Portable home (off-NixOS / external consumers)
@@ -179,20 +180,20 @@ automatically.
## Shell environment & keybindings
- Interactive shell features (zsh, tmux, git, ssh, CLI tools, auto-tmux):
[`home/README.md`](./home/README.md).
[`docs/shell.md`](https://docs.lyrapup.pet/nixfiles/shell/).
- Which classic utilities are shadowed by modern replacements, and the flag
differences that will bite:
[`home/README.md` → "Replacing the classics"](./home/README.md#replacing-the-classics).
[`docs/shell.md` → "Replacing the classics"](https://docs.lyrapup.pet/nixfiles/shell/#replacing-the-classics).
- All Sway / tmux / foot / zsh keyboard shortcuts:
[`home/KEYBINDINGS.md`](./home/KEYBINDINGS.md).
[`docs/keybindings.md`](https://docs.lyrapup.pet/nixfiles/keybindings/).
## Login / greeter
Graphical (Sway) hosts log in through a Wayland greeter — `greetd` running
ReGreet inside the `cage` kiosk compositor — implemented in
[`modules/sway.nix`](./modules/sway.nix), gated on
[`modules/sway.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules/sway.nix), gated on
`features.swayDesktop.enable` (the option is declared in
[`modules/features.nix`](./modules/features.nix), so headless hosts
[`modules/features.nix`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/modules/features.nix), so headless hosts
can leave it off without importing `modules/sway.nix`). The greeter is forced to Dvorak
to match the console and Sway session. Headless hosts (the WSL work box and the
Raspberry Pi server) keep plain TTY login. The target account needs a password
@@ -212,6 +213,38 @@ To refresh them, copy the firmware extracted during the Asahi install (from
[Asahi NixOS docs](https://github.com/tpwrules/nixos-apple-silicon)) into
`modules/firmware/` and commit with `git add -f`.
## Documentation
All prose documentation lives in [`docs/`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/docs); this README is the overview. The pages are
published to **<https://docs.lyrapup.pet/nixfiles/>** by the
[`docs-site`](https://code.emmathe.dev/lyrathorpe/docs-site) repository, which clones this repo on
every build (on its own push, nightly, or on demand) and assembles the tree:
```
README.md -> docs/nixfiles/index.md # this file becomes the section landing page
docs/ -> docs/nixfiles/ # everything here, ordering from docs/.pages
```
Nothing is pushed from this side and there is no build step here — editing a
page and merging is all that is required. Files outside `docs/` (bar this
README) are **not** synced, so a doc kept next to the code it describes will
never appear on the site.
### Linking rules
The site has no copy of the source tree, and this README is republished at a
different depth from the rest of `docs/`. Both facts break naive relative
links, so:
| Link from | To | Use |
| ----------------- | ----------------------- | ---------------------------------------------------------------- |
| anywhere | a source file or dir | absolute `https://code.emmathe.dev/.../src/branch/main/…` |
| a page in `docs/` | another page in `docs/` | relative (`./keybindings.md`) — correct in Gitea and on the site |
| this README | a page in `docs/` | absolute `https://docs.lyrapup.pet/nixfiles/…` |
`mkdocs build` runs non-strict on the docs-site side, so a broken link fails
silently rather than failing the build. Check links by hand when moving a page.
## Development
A dev shell and a formatting/lint gate are wired through the flake:
@@ -227,7 +260,7 @@ A dev shell and a formatting/lint gate are wired through the flake:
## CI
[`.gitea/workflows/ci.yaml`](./.gitea/workflows/ci.yaml) runs `nix flake check`
[`.gitea/workflows/ci.yaml`](https://code.emmathe.dev/lyrathorpe/nixfiles/src/branch/main/.gitea/workflows/ci.yaml) runs `nix flake check`
(formatting, `deadnix`, `statix`, the pre-commit hooks) and evaluates every
NixOS and Darwin host configuration on push/PR. It always runs (no `paths:`
filter) so the required check never hangs pending; the heavy Nix steps are