From 2d7c724a48b172b39fffbe5ffd6c4f91f2740f89 Mon Sep 17 00:00:00 2001 From: noether Date: Mon, 12 Oct 2026 22:53:14 -0600 Subject: [PATCH] docs: README quick-start for fresh pulls (bootstrap, rebuild, serve-lan) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Top section now leads with the rebuild-after-pull workflow (public/ is never in git) including make bootstrap/tool-versions and the error-127 hint; §2 recommends bootstrap over manual installs; §4 documents the new targets; §7 gains the pagefind/livereload-404 and command-not-found bullets; §8 lists .tools/. --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9024060..7b4e2ab 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,35 @@ previewing, searching, and maintaining the site. --- +## Fresh git pull? Rebuild before serving + +`public/` (the built site) is **never in git** — it's regenerated locally and +gitignored (§8). A `git pull` brings you source only: content, theme, Makefile, +scripts. Until you rebuild, there is nothing to serve — and a stale `public/` +left over from an older workflow (e.g. `hugo server`) will render pages with a +broken search box and spurious `pagefind/*` / `livereload.js` 404s in the server +log. + +From the project root: + +``` +make bootstrap # ONCE per machine: pinned Hugo/Node/lychee into .tools/ (no system changes) +make tool-versions # diagnostic: pinned vs system tool versions +make clean && make all # wipe stale output, then hugo --gc + pagefind index +make serve-lan # serve on http://:8090/ (or: make serve, local :1414) +``` + +Success check: the `make all` log prints `Indexed N pages` (N > 0) and +`public/pagefind/pagefind-ui.js` exists. `error 127` / "command not found" +means a tool is missing: `make tool-versions` shows which, `make bootstrap` +fixes it. Full details: [Prerequisites (§2)](#2-prerequisites-install-once), +[Build & preview (§4)](#4-build--preview-make-commands). + +--- + ## Table of contents +- [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving) - [Architecture](#architecture) - [1. Clone](#1-clone) - [2. Prerequisites (install once)](#2-prerequisites-install-once) @@ -196,6 +223,13 @@ cd libertytoolsio ## 2. Prerequisites (install once) +**Recommended: `make bootstrap`.** It installs pinned versions of Hugo extended +(0.167.0), Node (22.11.0 — provides `npx` for Pagefind), and lychee (0.24.2) +into the repo-local `.tools/bin` (gitignored). Make targets always use these +pinned tools via a recipe-scoped PATH; your system PATH and any system-installed +tools (e.g. an older Hugo) are never touched. Run `make tool-versions` to see +pinned vs system versions side by side. The manual per-tool installs below are +the fallback (they install into `~/.local/bin`). All tools install into `~/.local/bin` (no sudo). Make sure `~/.local/bin` is on your `PATH` (it usually is; if not: `export PATH="$HOME/.local/bin:$PATH"`). @@ -235,11 +269,14 @@ All tools install into `~/.local/bin` (no sudo). Make sure `~/.local/bin` is on ## 4. Build & preview (make commands) -Run from the project root. `public/`, `linkcheck/`, and `resources/_gen/` are -generated and gitignored. +Run from the project root. `public/`, `linkcheck/`, `resources/_gen/`, and +`.tools/` are generated and gitignored. | Target | What it does | |-----------------------|--------------| +| `make bootstrap` | **Once per machine.** Install the pinned toolchain (Hugo 0.167.0 extended, Node 22.11.0, lychee 0.24.2) into repo-local `.tools/bin`. Idempotent; never touches your system. | +| `make tool-versions` | Diagnostic table: pinned (`.tools/bin`) vs PATH-first (system) tool versions. | +| `make preflight` | Strict tool check (runs automatically before `all`/`serve`/`serve-lan`); on failure it says `make bootstrap` instead of a bare `error 127`. | | `make build` | Build Hugo content into `public/` (`hugo --gc`). | | `make index` | `build` + build the Pagefind search index into `public/pagefind/`. **This is the normal "I edited content, re-make it" command.** | | `make serve` / `make run` | `index` + serve the built site **with search** at `http://localhost:1414/` (local only). Uses Pagefind's own server, which binds 127.0.0.1. | @@ -377,6 +414,12 @@ hermes cronjob list # confirm it exists and is enabled ## 7. Troubleshooting +- **Server log shows 404s for `/pagefind/*` or `/livereload.js`** → stale or + unindexed `public/`: run `make clean && make all` and restart the server (see + [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving)). +- **`error 127` / "command not found"** → a build tool is missing. Run + `make tool-versions` to see which, then `make bootstrap` to install the + pinned toolchain into `.tools/`. - **`hugo: command not found`** → you're using the non-extended build or it isn't on PATH. Re-run the Hugo install above and confirm `hugo version` says `+extended`. - **Search shows no results** → the index wasn't built. Run `make index`, confirm the @@ -404,9 +447,11 @@ All changes from a maintenance pass are left in the working tree for review. Com **only after you have validated the result** (`make build` exits 0 and you've checked the rendered output). The following are generated and gitignored — never commit them: -- `public/` — built site output +- `public/` — built site output; a fresh clone/pull contains none of it (rebuild + per [Fresh git pull? Rebuild before serving](#fresh-git-pull-rebuild-before-serving)) - `linkcheck/` — link-check reports - `resources/_gen/` — Hugo asset-generation cache +- `.tools/` — pinned local toolchain installed by `make bootstrap` - `.hermes/` — agent working files ## Repository layout