lyrathorpe/nixfiles

Fork 0

Files

T

Emma Thorpe dcc13f94e0

CI / flake (push) Skipped

CI / flake (pull_request) Successful in 4m21s

Details

docs: move prose documentation into docs/ so the docs site publishes it

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.

2026-08-19 17:38:50 +01:00

3.7 KiB

Raw Permalink Blame History

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:

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.