Emma Thorpe
dcc13f94e0
CI / flake (push) Skipped
CI / flake (pull_request) Successful in 4m21s
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.
75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# Working on this flake
|
|
|
|
Project notes for changes to this repository. Persona and memory rules live in
|
|
the user-global config; this file is about the flake's checks and conventions.
|
|
|
|
## Before you commit: run the formatter
|
|
|
|
Formatting and linting are driven by the flake. CI (`.gitea/workflows/ci.yaml`)
|
|
runs `nix flake check`, which fails the build if any file is unformatted or trips
|
|
a lint. From the repo root:
|
|
|
|
- `nix fmt` — format the whole tree (writes changes).
|
|
- `nix flake check` — run every check read-only (what CI runs).
|
|
- `nix develop` — dev shell; its `shellHook` installs the git pre-commit hooks so
|
|
the same gates run on `git commit`.
|
|
|
|
Never commit with `--no-verify`. A bypassed commit ships unformatted content and
|
|
turns CI red on the next push to `main` (see "Docs are checked too").
|
|
|
|
## What gets checked
|
|
|
|
Defined in `flake.nix` (the `treefmt`, `pre-commit`, and `checks` blocks) and
|
|
`statix.toml`:
|
|
|
|
| Check | Tool | Covers |
|
|
| ------------ | --------------------------------- | ------------------------------------------------------- |
|
|
| `formatting` | treefmt → `nixfmt` | all `*.nix` |
|
|
| `formatting` | treefmt → `shfmt` | shell scripts |
|
|
| `formatting` | treefmt → `prettier` | **Markdown, YAML, JSON** (incl. `README.md`, this file) |
|
|
| `deadnix` | deadnix | dead Nix bindings (`--no-lambda-pattern-names`) |
|
|
| `statix` | statix | Nix antipatterns (config in `statix.toml`) |
|
|
| pre-commit | nixfmt-rfc-style, deadnix, statix | the same gates, run on commit |
|
|
|
|
Excluded from formatting: `*/hardware-configuration.nix` (generated by
|
|
`nixos-generate-config`) and `flake.lock`. Editor defaults (indent, EOL, final
|
|
newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which
|
|
encodes hard line breaks.
|
|
|
|
## Docs are checked too
|
|
|
|
prettier formats `*.md`, so **documentation edits must be run through `nix fmt`**
|
|
exactly like code. prettier re-aligns Markdown tables in particular; hand-editing
|
|
a table almost always leaves it non-conformant and fails the `formatting` check.
|
|
|
|
Prose documentation lives in `docs/` and is **published** to
|
|
<https://docs.lyrapup.pet/nixfiles/> by the separate `docs-site` repo, which
|
|
clones this one at build time. Two consequences when editing docs:
|
|
|
|
- A markdown file outside `docs/` (other than the root `README.md`) is not
|
|
synced and will never appear on the site. Put new prose in `docs/`.
|
|
- Links must follow the rules in the README's "Documentation" section: absolute
|
|
Gitea URLs to source files, relative links between `docs/` pages, and
|
|
absolute `docs.lyrapup.pet` URLs from the root README into `docs/`. The site
|
|
builds non-strict, so a broken link is silent.
|
|
|
|
The CI `formatting` step runs on **every** PR — including docs- and config-only
|
|
changes — so a Markdown/YAML/JSON edit is format-checked before merge, not just
|
|
after it lands on `main`. (The heavier `deadnix`/`statix`/`pre-commit` lints and
|
|
the per-host evaluation still run only when a `.nix` file, `flake.lock`, or the
|
|
workflow changed; see `.gitea/workflows/ci.yaml`.) Run `nix fmt` before you
|
|
commit and the formatting check stays green.
|
|
|
|
## Host evaluation
|
|
|
|
CI also evaluates every `nixosConfigurations` / `darwinConfigurations` host's
|
|
toplevel (eval only, no build) on an x86_64 runner, so eval errors fail cheaply.
|
|
Reproduce locally:
|
|
|
|
```sh
|
|
nix eval --raw ".#nixosConfigurations.<host>.config.system.build.toplevel.drvPath"
|
|
```
|
|
|
|
Host lists are discovered from the flake, so adding or removing a host needs no
|
|
change to the workflow.
|