Upgrade Docsy to 0.17.0 and Hugo to 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 remaining integration and release checks are listed below.

Upgrade to Docsy 0.17.0 and Hugo Extended 0.166.0 while preserving familiar editing commands, as agreed in #51. CI and local containers use ghcr.io/gohugoio/hugo:v0.166.0.

• Import github.com/google/docsy/theme, commit its Bootstrap/Font Awesome npm workspace, and pin Dart Sass through sass-embedded 1.102.0.
• Migrate Hugo data/language APIs and replace removed getJSON with remote-resource retrieval and explicit error handling. Code comments link to the relevant upstream changes.
• Preserve the purple navbar and use Docsy's own TOC heading. Inherit the upstream sidebar template; its warning-count arithmetic is tracked separately in #53. Sidebar auto-scrolling remains outside this MR.
• Keep the merged CI observability wrappers and metrics artifacts. Update local, Docker and Workspace guides, Hugo-version troubleshooting, and the maintainer upgrade checklist with manual commands.

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.
• Keep ./scripts/sync-data.sh explicit in AGENTS.md. 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.

The npm audit fixes have been pushed; the new pipeline must complete before rollout.

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). The theme build passed with the upstream sidebar template after removing the override (22 pages). 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

Both handbooks currently pin theme 9e85e9d86fa5; this predates the latest theme changes. Refresh both to the same final theme commit and rerun downstream pipelines and review-app checks. Track the remaining checks in #51.

After validation, merge the theme MR and release through the existing automation. Update both handbook MRs to the released version, validate again, and roll out internal before public. 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 the correct Directly Responsible Individual/s (DRI)
  • The when to get approval handbook section explains the workflow in more detail
• For transparency, share this MR with the audience that will be impacted.
  • Team: For changes that affect your direct team, share in your group Slack channel
  • Department: If the update affects your department, share the MR in your department Slack channel
  • Handbook: For changes that affect handbook users, but does not need company-wide attention, post in the #handbook Slack channel
  • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR
    • For high-priority company-wide announcements work with the internal communications team to post the update in #company-fyi and align on a plan to circulate in additional channels like the "While You Were Iterating" Newsletter

---