build: replace ad-hoc run with a full make workflow + helper scripts

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/.
This commit is contained in:
noether
2026-10-11 08:58:50 -06:00
parent 99b7546fd1
commit 2d8f79b7fd
5 changed files with 304 additions and 3 deletions
+52 -3
View File
@@ -1,3 +1,52 @@
run:
hugo server &
npx -y pagefind --site public --serve
HUGO := hugo
PAGEFIND := npx -y pagefind
LYCHEE := lychee
OUT := public
.PHONY: all build index serve run link-check link-fix external-check serve-lan clean
all: index
# Build Hugo content -> public/
build:
$(HUGO) --gc
# (Re)build the Pagefind search index from public/ -> public/pagefind/
index: build
$(PAGEFIND) --site $(OUT)
# Build content + index, then serve the built site WITH search on :1414 (dev preview).
# Uses pagefind's own server. Local only (binds 127.0.0.1) -- for LAN use `make serve-lan`.
serve: index
$(PAGEFIND) --site $(OUT) --serve
run: serve
# DEAD LINKS -- internal (offline, fast): scan the SOURCE markdown; internal links
# resolve to file:// under public/. External links are skipped by --scheme file.
# Output: linkcheck/internal.json (exit != 0 when dead links exist; that is fine).
link-check: build
mkdir -p linkcheck
$(LYCHEE) --root-dir $(OUT) --default-extension html --scheme file \
--format json --timeout 10 \
$(wildcard content/*.md) $(wildcard content/*/*.md) > linkcheck/internal.json
# Comment out confirmed dead INTERNAL page links, then rebuild content + index so they
# leave the live page AND the search index. (External failures -> manual_review.txt.)
link-fix:
python3 scripts/fix_dead_links.py --report linkcheck/internal.json --apply
$(HUGO) --gc
$(PAGEFIND) --site $(OUT)
# DEAD LINKS -- external (network): scan all http/https links in content. Report-only.
# Always exits 0; the report is the point.
external-check:
python3 scripts/check_external_links.py
# Serve the BUILT site on all interfaces so another LAN machine can open it:
# http://<this-machine-LAN-IP>:8090/ (IP printed at startup; also `hostname -I | head -1`)
serve-lan:
python3 scripts/serve_lan.py
clean:
rm -rf $(OUT) linkcheck