The README now documents:
- Architecture: the static build/serving model, the content -> public/
-> pagefind/ data flow, the SCSS compile pipeline (why the Hugo
extended build is required, SRI fingerprinting), where
customizations live (_variables.scss table, search.html), the
data-pagefind-body index-scoping mechanism, the #search CSS cascade
trick, and the four Pagefind 1.5.2 quirks the UI works around
(stretched form, no-op Enter, empty thumbnail, UA-yellow marks)
- Every Makefile target with what it does and the gotchas (serve does
not rebuild; serve-lan is plain static; build runs --gc)
- Search usage incl. the new keyboard navigation, and a table of the
current #search customization values
- Dead-link automation (internal/external split, idempotent
comment-out, daily cron job)
- Troubleshooting for the new failure modes and a do-not-commit list
These compiled-SCSS cache files were being versioned but are regenerated
on every build (each build produces new hash-named files and orphans the
old ones), so they churned the working tree on every commit. They are now
gitignored (see the .gitignore change in the build-tooling commit) and
untracked here. Nothing references them at runtime; Hugo rebuilds them
from book.scss as needed.
Add site-level overrides to themes/hugo-book/assets/_variables.scss
(imported after _defaults.scss, so plain assignments override the theme):
--font-size: 17px base font up from the theme's 16px (all rem
sizes scale off it)
$container-max-width: 100rem content cap up from 80rem, so a 1920px
display no longer leaves ~310px dead gutters
on each side
$menu-width: 18.75rem sidebar (category list + search box + search
results pane) up from the 10rem theme default
so search results are readable
$mobile-breakpoint recomputed from the new values (it is derived
in _defaults.scss, so the override must redo
the arithmetic or the mobile collapse breaks)
Remove the legacy Fuse.js search from html-head.html (it double-loaded
with the new Pagefind UI; backup kept at html-head.html.bkup) and add a
Pagefind Default-UI partial (search.html) injected into the sidebar via
menu.html.
Index scoping: tag the article element with data-pagefind-body in
baseof.html, term.html, and posts/{single,list}.html so Pagefind indexes
page content only (pages without the tag are skipped; 404.html stays
untagged).
search.html (all overrides #search-scoped, since pagefind-ui.css loads in
<body> after the head CSS):
- compact input/magnifier/clear-button fitted to the sidebar; clear
button uses fixed px (not %) because the results drawer is an in-flow
child of the form, which stretches the form to results height
- hide the empty .result-thumb placeholder (no images in the index) that
was pushing result text ~90px right
- restyle matched-term <mark> from UA yellow to subdued slate
- keyboard navigation (Pagefind 1.5.2 has none; stock Enter is a silent
no-op): capture-phase keydown implements ArrowUp/Down highlighting with
wraparound across top-level hits AND their nested sub-results (each sub
highlights its own .result-nested row), Enter opens the highlighted
result (or the top result), and a fingerprint-aware MutationObserver
keeps the highlight across Pagefind's async re-renders without
resetting it on every DOM patch
The old Makefile was a single 'run' target (hugo server + pagefind --serve).
Replace it with documented targets:
build hugo --gc -> public/
index build + pagefind --site public -> public/pagefind/
serve / run index + pagefind's own server on 127.0.0.1:1414 (local)
serve-lan static-serve public/ on 0.0.0.0:8090 for other machines
link-check offline internal-link scan (lychee --scheme file) -> JSON
link-fix comment out confirmed-dead internal links, then rebuild
external-check network scan of external links (report-only)
clean / all
Add scripts/:
serve_lan.py stdlib static server rooted at public/ (prints LAN IP)
fix_dead_links.py idempotent internal dead-link comment-out
check_external_links.py external link report (drives the daily cron job)
.gitignore: add linkcheck/, resources/_gen/ (regenerable Hugo asset cache),
__pycache__/, and .hermes/.
Normalize four links that were missing an https:// scheme (defcad.com,
simplytranslate.org, airbtc.online) and one malformed double-paren
Affiliate Link target in self-hosting.md. Bare-domain hrefs render as
relative file paths and were being mis-read by the dead-link scanner.
noether