0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 02:54:26 +00:00

Files

T

kevinveenbirkenbachandClaude Opus 4.7 16bdbf03d7 docs: fix repo-wide drift against documentation.md style rules

Three classes of drift cleaned up across 85 .md files:

- Em-dashes: replaced ` — ` with the contextually correct separator
  (colon for `term: explanation`, period to split clauses across
  sentences/source lines, parentheses for asides, semicolon for
  tight-linked continuations). Two intentional exceptions remain
  in `docs/contributing/documentation.md` (the rule literal) and
  inside a fenced ```sh block in `docs/contributing/actions/debugging/ci.md`.
- SPOT self-labels: rewrote "This is the SPOT for X" to describe
  the subject directly ("This directory holds X" / "This file
  describes X"). Cross-references to other artefacts' canonical
  role remain unchanged.
- Heading-emoji position: moved leading-emoji headings (`# 🧩 Title`)
  to trailing position (`# Title 🧩`) per the headline rule that
  emojis MUST come after the title text.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-15 20:12:07 +02:00

2.4 KiB

Raw Blame History

Hugo: Administration

Force a rebuild

The Hugo site is built into the custom Docker image at compose build time. The build is content-keyed via the cloned services/repository/ tree, so:

A change in services.hugo.source_version invalidates the clone, which invalidates COPY ./services/repository/ in the Dockerfile, which triggers a fresh hugo build on the next deploy.
A force rebuild without a source-version change can be triggered by clearing the role's image cache:
```
make exec CMD="docker compose -f /opt/docker/web-app-hugo/docker-compose.yml build --no-cache"
```
The next make deploy-reuse-kept-apps APPS=web-app-hugo will pull the image, restart nginx, and serve the freshly rendered output.

Bumping the source version

Pick the new tag/commit in the upstream repository (default: gohugoio/hugoDocs releases).
Update roles/web-app-hugo/meta/services.yml:
```
hugo:
  source_version: <new-tag>
```

Re-deploy:

make deploy-reuse-kept-apps APPS=web-app-hugo

Verify in the browser that the content reflects the new version.

Debugging a failed Hugo build

The Hugo build runs inside docker compose build. If hugo exits non-zero, the play fails and the previous image keeps serving. To inspect the failure log:

make exec CMD="docker compose -f /opt/docker/web-app-hugo/docker-compose.yml build --progress=plain --no-cache web-app-hugo 2>&1 | tail -200"

Common causes:

hugo reports unknown content / module errors: the upstream repository moved a directory or a Hugo Module. Pin to a known-good tag in source_version.
hugo reports template execution errors: the theme's templates are incompatible with the bundled Hugo binary. Bump services.hugo.builder_version (e.g. to a newer exts-<version> tag) or pin the source repo to a tag known to build with the current Hugo.
Module fetch fails (go.mod resolution): Hugo modules pull from proxy.golang.org. Network egress to that host must be allowed by the local firewall / proxy.

Rotating the Hugo binary

To upgrade the extended Hugo binary independently of the content repo, edit services.hugo.builder_version in meta/services.yml (e.g. exts-0.149.0). The change invalidates only the builder layer, not the cloned repo, so the next compose build reuses the same content but with the new binary.

2.4 KiB Raw Blame History