ci: add PR build gate via reusable workflow

[Arthurvdv]

What

Adds a pull-request build gate so broken builds, dead internal links, and lint regressions are caught before merge — without duplicating the deploy pipeline's build steps.

The build logic now lives in one reusable workflow (build.yaml, workflow_call) that both the PR gate and the release deploy call, so they can never drift.

ci.yaml ────────┐
                ├─► build.yaml (toolchain + strict build + htmltest + markdownlint)
hugo.yaml ──────┤        deploy adds: configure-pages + upload + deploy-pages
link-check.yaml ┘        link-check adds: lychee (external only)

Checks on every PR (and every deploy)

• Strict Hugo build — --gc --minify --panicOnWarning --printPathWarnings; broken ref/relref already fail via Hugo's default refLinksErrorLevel: ERROR. (Verified: the current tree builds warning-clean.)
• htmltest — internal links, anchors, and image existence over the rendered public/. External checking is off here (deterministic gate).
• markdownlint (markdownlint-cli2) — content/**/*.md.

Also pins what CI previously left implicit: Node 22 (setup-node + .nvmrc) and Go from go.mod (setup-go), plus a Hugo resource cache.

Off the gate: scheduled external-link check

link-check.yaml runs lychee weekly (and on demand) for external links only — internal is htmltest's job (.lycheeignore skips our own domain). Kept off PRs so a flaky/rate-limited third-party site never blocks a merge; opens a tracking issue on failure.

Fast-follow: pre-existing broken links (NOT fixed here)

htmltest surfaced real issues already live on the site. Per scope, this PR keeps to CI infra and temporarily allowlists them in .htmltest.yml with anchored, self-expiring patterns (they stop matching once each link is fixed, and they do not mask new breakage). To be fixed in a follow-up:

Broken internal cross-refs (bare xxxx/ resolves under the current page dir -> 404; correct form is ../xxxx/). The convention in CLAUDE.md / .claude/rules/rule-pages.md ([PC0034](pc0034/)) is itself the buggy form and should become ../pc0034/:

• AC0024 -> ac0012/
• LC0081 -> lc0082/, LC0082 -> lc0081/
• PC0005 -> pc0006/, PC0017 -> pc0018/, PC0020 -> pc0021/, PC0021 -> pc0020/
• downloading-analyzers -> getting-started/vscode/, getting-started/cicd/github/
• getting-started/cicd/cli -> azure-devops/
• lintercop-migration -> ../lintercop-migration-script (missing trailing slash)

{{< relref >}} inside a link destination renders as href="hahahugoshortcode…" (the render-link hook mangles it) — LC0007, LC0008, LC0010 -> Configuration. Use a plain lowercase path or fix the hook.

Missing image alt (10 images) — AC0003, AC0016, AC0017 (x2), LC0028 (x4), LC0090, getting-started/vscode. htmltest's IgnoreAltMissing is set until these get alt text.

Verification

All three gates confirmed green locally on the current tree (Hugo 0.165.0 extended, Go 1.26, Node): strict build ✓, htmltest ✓ (157 docs), markdownlint ✓ (148 files). This PR's own CI run exercises the new gate end-to-end.

Action for maintainer

Make build / build a required status check on main (Settings -> Branches -> branch protection). I'll confirm the exact check name once CI runs here.

🤖 Generated with Claude Code