Integrate Docsy 0.17.0 and Hugo 0.166.0

Why is this change being made?

Goal: Fix dependency vulnerabilities and speed up Hugo builds to reduce CI/CD compute usage for handbook updates.

After multiple Docsy and Hugo upgrade attempts and tests over the past month, this MR contains the final working upgrade approach. The released-theme integration checks are listed below; public deployment is paused at Michael’s request.

Integrate Docsy GitLab v0.4.3, including Docsy 0.17.0 and Hugo Extended 0.166.0 from Docsy GitLab !329, following upgrade issue #51, while preserving familiar editing commands.

• Pin released Docsy GitLab v0.4.3, and refresh module checksums and npm workspace metadata. This includes the sidebar truncation warning fix from Docsy !339.

• Commit the Bootstrap/Font Awesome npm workspace and lockfiles, pin sass-embedded 1.102.0, and provide the npm binary PATH to Hugo.

• Migrate local data access to hugo.Data, retain existing HTML/Markdown content handling, and document required security configuration changes.

• Align CI and local containers on ghcr.io/gohugoio/hugo:v0.166.0, preserving the merged CI observability wrappers and metrics artifacts.

• Protect /packages/ in the required handbook-operations CODEOWNERS section, using the same owners as .gitlab-ci.yml, including handbook-tools.

Contributor and agent testing workflow

• Native editing keeps make view and make build. Both run npm ci, synchronize data, and expose the project tools to Hugo automatically.
• Agents can now use Docker Compose for preview and build testing, with the same pinned Hugo image and lockfiles as CI. From a regular clone, use docker compose up; from a Git worktree, use make compose-view so Git metadata is mounted correctly. Use make compose-build for a noninteractive build and make compose-down to stop the preview.
• Compose installs the required tools inside the container; host Node.js, Go and Hugo are unnecessary. Dependency/cache volumes, localhost binding, optional ports and file polling support repeatable local tests.
• Direct Docker remains supported through make docker-view / make docker-build. The Docker guide also includes a manual docker run fallback without Compose or host Make.
• Preserve AGENTS.md and .gitlab/duo/mr-review-instructions.yaml byte-for-byte from the identical current main versions in Docsy GitLab, public handbook, and internal handbook. The generated npm workspace README explains its purpose, refresh steps and upstream references. handbooklint allows README.md at any directory depth.

Validation

Npm audit remediation: updated Browserslist to 4.28.9 and added a targeted markdownlint-cli2 / smol-toml 1.7.1 override for CVE-2026-85730. All three repositories now report zero npm audit findings. Clean npm ci, Markdownlint, and valid/malformed TOML checks pass; the Docker theme build passed with 22 pages. Remove the override when upstream Markdownlint selects a patched parser. New full downstream CI results remain pending.

Previous v0.4.2 validation: module/npm metadata refreshed, clean npm ci and npm audit passed with zero findings, shell syntax and whitespace checks passed. Full local make compose-build with Git metadata passed: 4658 pages, 156.171 seconds Hugo rendering. Refreshed MR pipeline passed, including dependency scanning. The build retains one genuine sidebar warning: 10 entries exceed the limit of 125 in /handbook/support/workflows; the bogus underflow warnings are gone. CODEOWNERS fallback warnings also remain.

Manual test evidence and remaining checks are recorded in upgrade issue #51: public/internal local homepages, purple navbar, Mermaid, generated tables, shortcodes and internal images; heading anchors and code copying were also confirmed. Tableau screenshots show the sign-in screen, not authenticated chart contents. Local screenshots do not replace final deployed review-app checks.

Earlier full local Compose builds passed for both handbooks (4,661 public / 1,573 internal pages). These historical results predate v0.4.2, which restores a narrowly modified sidebar override to correct unsigned warning-count underflow. Documentation lint, shell syntax and Makefile dry-run checks passed; README prose checks exclude the page-only frontmatter rule.

Initial performance findings: public Hugo rendering 327s → 78s and internal 52s → 28s, compared with five preceding main runs. These measure the combined upgrade, not Hugo in isolation.

Release gates

The theme prerequisite is satisfied: v0.4.3 is published and this MR now uses it. The internal handbook already uses v0.4.2. Public deployment remains paused; do not merge or deploy this MR until rollout resumes.

• Rebase onto public main c84cadf4f9 and preserve canonical agent/review instructions.
• Pin Docsy GitLab v0.4.2 and refresh Go checksums/npm workspace metadata.
• Pass the full public Compose build with v0.4.2 and Git metadata enabled.
• Pass the v0.4.2 integration pipeline: 2848423145.
• Pass the new pipeline after the CODEOWNERS-only follow-up.
• When deployment resumes, run the manual Pages review job and visually verify the final released pin.
• Merge and monitor public production after approval.

Track remaining checks in #51. Rollback requires reverting the coordinated theme, Hugo, npm and configuration changes.

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

• Provided a concise title for this Merge Request (MR)
• Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
  • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
• Assign reviewers for this MR to a code owner, typically a handbook maintainer
  • If you're unsure, please mention the handbook owner
• For transparency, share this MR with the audience that will be impacted
  • #handbook Slack channel if there is any user impact
  • #mr-buddies Slack channel if changes may impact more users
  • #whats-happening-at-gitlab linking to this MR if a large number of team members are impacted

Commits

Upgrade Hugo, integrate the new theme, and adapt the build dependencies.

---

Development tooling ownership

Extend the required handbook operations CODEOWNERS section to compose.yml, Makefile, .tool-versions, the Markdownlint formatter, .hugolint.yaml, danger/, i18n/, and archetypes/, using the same owners as .gitlab-ci.yml. Existing ownership and exemptions remain unchanged. Verified paths, unique added rules, exact owner lists, and git diff --check; pipeline validation is pending.

v0.4.3 release update

Updated the theme pin and Go checksums to v0.4.3, which adds the local/Docker troubleshooting guide and dated Hugo requirement from Docsy !343, plus the merged tooling ownership updates. The release pipeline passed. Go downloaded the new module successfully and git diff --check passed; integration validation for this pin is pending the new MR pipeline. Earlier v0.4.2 results above remain historical. This MR supersedes the generated public release MR !21115 (closed).

Final inspection after rebase (2026-09-15)

Rebased on origin/main at 56fed352d5; current MR commit 6c1730b11d86e1f12ff3838fdcf68b55845cd8cf retains Docsy GitLab v0.4.3. Rebase completed without conflicts.

• Full local make compose-build passed: 4,660 pages, 146.244 seconds Hugo rendering, using Hugo Extended 0.166.0. npm reported zero vulnerabilities.
• Worktree remained clean. Shell syntax and whitespace checks passed.
• AGENTS.md and Duo review instructions match Docsy and internal handbook main byte for byte.
• All 87 changed template lines are the intended site.Data/.Site.Data to hugo.Data substitutions.
• Generated troubleshooting page and anchors exist; generated navbar CSS uses purple #6e49cb. These are generated-output checks, not a fresh browser visual sign-off.
• Known warnings remain: 10 truncated Support workflow sidebar entries and six CODEOWNERS profile fallbacks. No build errors.

Rebased pipeline passed, including dependency scanning. The Pages review job passed and the review app is available. Verified HTTP 200 for the homepage and troubleshooting page after Pages propagation. The deployment uses merged-results commit 4be741fa1c730ac7915bb80f1e9f17249856ea8b for MR head 6c1730b11d86e1f12ff3838fdcf68b55845cd8cf. Production merge/deployment remains separate.