docs: publish the prose documentation to docs.lyrapup.pet #96

2026-08-19T17:41:20+01:00

lyrathorpe commented

2026-08-19 17:41:20 +01:00

Why

The docs-site build syncs only two things from this repo:

README.md   ->  docs/nixfiles/index.md
docs/       ->  docs/nixfiles/

There was no docs/ directory, so the site published exactly one page — the root README — and that page carried 18 link targets that resolved to nothing (7 into unsynced markdown, 11 into source files that do not exist in the site tree). mkdocs build runs non-strict, so this failed silently.

What

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 awesome-pages an explicit order; the trailing ... picks up new pages without an edit.

Links are rewritten so one URL is correct in both Gitea and the published site:

From	To	Form
anywhere	a source file or dir	absolute Gitea `src/branch/main/…`
a page under `docs/`	another page under `docs/`	relative
the root README	a page under `docs/`	absolute `docs.lyrapup.pet/nixfiles/…`

The root README is the only file republished at a different depth from the rest of the tree, which is why it is the only one needing absolute links inward.

In-code comments pointing at a moved README are updated. The README gains a Documentation section covering the sync contract and the linking rules; CLAUDE.md carries the short version so future edits do not reintroduce unsynced pages or dead links.

Validation

nix flake check passes; all five NixOS hosts evaluate.
The docs-site assembly was reproduced 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 in the README, in the order .pages declares.

Needs the docs-site nav fix

This PR alone will not make the pages appear. The nav: block in docs-site/mkdocs.yml references directories:

nav:
  - Home: index.md
  - Terraform: terraform
  - nixfiles: nixfiles

awesome-pages does not expand bare directory references. It warns A reference to 'nixfiles' is included in the 'nav' configuration, which is not found in the documentation files and drops the section. Deleting the nav: block makes the plugin auto-discover both trees and honour the .pages ordering — confirmed locally. This affects the Terraform section today, independently of this change.

## Why The docs-site build syncs only two things from this repo: ``` README.md -> docs/nixfiles/index.md docs/ -> docs/nixfiles/ ``` There was no `docs/` directory, so the site published exactly one page — the root README — and that page carried 18 link targets that resolved to nothing (7 into unsynced markdown, 11 into source files that do not exist in the site tree). `mkdocs build` runs non-strict, so this failed silently. ## What 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 awesome-pages an explicit order; the trailing `...` picks up new pages without an edit. Links are rewritten so one URL is correct in both Gitea and the published site: | From | To | Form | | -------------------- | -------------------------- | -------------------------------------- | | anywhere | a source file or dir | absolute Gitea `src/branch/main/…` | | a page under `docs/` | another page under `docs/` | relative | | the root README | a page under `docs/` | absolute `docs.lyrapup.pet/nixfiles/…` | The root README is the only file republished at a different depth from the rest of the tree, which is why it is the only one needing absolute links inward. In-code comments pointing at a moved README are updated. The README gains a Documentation section covering the sync contract and the linking rules; CLAUDE.md carries the short version so future edits do not reintroduce unsynced pages or dead links. ## Validation - `nix flake check` passes; all five NixOS hosts evaluate. - The docs-site assembly was reproduced 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 in the README, in the order `.pages` declares. ## Needs the docs-site nav fix This PR alone will not make the pages appear. The `nav:` block in `docs-site/mkdocs.yml` references directories: ```yaml nav: - Home: index.md - Terraform: terraform - nixfiles: nixfiles ``` awesome-pages does not expand bare directory references. It warns `A reference to 'nixfiles' is included in the 'nav' configuration, which is not found in the documentation files` and drops the section. Deleting the `nav:` block makes the plugin auto-discover both trees and honour the `.pages` ordering — confirmed locally. This affects the Terraform section today, independently of this change.

lyrathorpe added 1 commit 2026-08-19 17:41:20 +01:00

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

CI / flake (push) Skipped

CI / flake (pull_request) Successful in 4m21s

Details

dcc13f94e0

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.

lyrathorpe merged commit c7adcccbb3 into main

2026-08-19 17:51:40 +01:00

lyrathorpe deleted branch docs/publish-to-docs-site

2026-08-19 17:51:41 +01:00

lyrathorpe referenced this pull request

2026-08-19 18:16:07 +01:00

fix(docs): pin the site section title so it renders as nixfiles #97

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lyrathorpe/nixfiles#96