chore: add canonical-gen make targets and backfill canonical links

[Iheanacho-ai]

What

Add Make targets to run tools/canonical-gen, which fills in or corrects the canonical: frontmatter field on Talos doc pages, and use it to fix all pages currently missing/stale on that field.

Why

Auto-generated Talos pages (e.g. from talosctl docs, version upgrades) don't always get a canonical: link, and older versioned pages need to point at the equivalent page in the current Talos version rather than their own. There was no way to run the existing (but unwired) canonical-gen tool.

Change

• Makefile: add build-canonical-gen-container, canonical-links (container), canonical-links-local (local Go build)
• Ran make canonical-links-local: added/corrected the canonical: field on 121 .mdx files under public/talos/

Testing

• Ran: make canonical-links-local, by hand
• Where: local checkout
• Result: 121 files updated; a follow-up go test ./... in tools/canonical-gen (8 tests) passes
• Note: no CI check was added here — a broader frontmatter check (title/description/canonical presence) is planned for a separate PR

[sterlingkoch]

Review pass, tooling findings only. The canonical-target question below is the one that needs a decision, the rest are mechanical.

1. The red code-review check is one lint error. tools/canonical-gen/main.go:264. frontmatterBounds returns start as a hardcoded 0 on all three paths, so unparam is right that it's dead API surface. Drop the return value and have findCanonical start at 1. That's the only failure in the run; hadolint and checkmake both pass.

2. A compiled binary got committed. tools/canonical-gen/canonical-gen, 3MB, Mach-O arm64. git rm --cached it and add tools/canonical-gen/canonical-gen to .gitignore next to the other tool artifacts around line 20. Every other tool in the tree has an entry, which is why this one slipped through.

3. The canonical target is v1.13 and should be v1.14, so 52 v1.14 pages now point backward. The tool derives its target from export const version in public/snippets/custom-variables.mdx, still v1.13, while Makefile:17 in this same PR already says TALOS_VERSION := v1.14. Representative: public/talos/v1.14/configure-your-talos-cluster/hardware-and-drivers/hailo.mdx:4. Full list:

git diff origin/main...HEAD -- 'public/talos/v1.14/*' | rg '^\+canonical:.*v1\.13'

Fix is either --version $(TALOS_VERSION) on the Makefile targets, or land #741 first (it bumps the snippet) and re-run.

4. Release-notes pages need a tool exclusion. public/talos/v1.14/getting-started/what's-new-in-talos.mdx:5. "What's New in Talos 1.14.0" now declares v1.13's what's-new page as canonical. Those are different documents, not two versions of one page, so what's-new and release-notes pages should always self-canonicalize.

5. make canonical-links can't run. Makefile:15 points at ghcr.io/siderolabs/canonical-gen:latest, which was never published (403 on that manifest, mdx-normalize:latest returns 200 as a control), and there's no build-canonical-gen.yaml. Needs one alongside build-mdx-normalize.yaml. Until then only canonical-links-local works.

6. Nit. tools/canonical-gen/Dockerfile:4-5 and :24-25 install and copy ca-certificates "for HTTPS requests," but the tool makes no network calls.

Worth saying: the self-canonical fallback is fixing a live bug and it's the strongest part of this PR. On current main, 46 Talos pages carry a canonical pointing at a URL that 308-redirects to /talos/v1.14/overview/what-is-talos, so we're telling Google that 46 content pages are duplicates of the docs homepage. I followed several by hand to confirm (v1.14/networking/vip, v1.14/security/verifying-images, v1.14/platform-specific-installations/bare-metal-platforms/digital-rebar). hasEquivalentAt's filesystem check is the right fix for that. The Makefile targets also follow the existing build-X-container / X / X-local triple correctly, and the mdx diff is purely canonical: lines in both directions with zero content changes.

[sterlingkoch]

See inline comments (most are agent-to-agent comments).

[Iheanacho-ai]

fixed @sterlingkoch