## Strategy and status **Current checkpoint — 2026-09-14:** Theme !329 is merged and **v0.4.1** is released. Internal !9015 uses that release, its full pipeline and Pages deployment passed, and Michael confirmed visual validation. We are waiting for Duo Code Review before proceeding with the internal merge. Public !21074 still needs its released-theme pin refresh and independent validation. Neither handbook upgrade MR is merged. Upgrade the shared theme and both handbooks together to **Hugo Extended 0.166.0 + upstream Docsy 0.17.0**, with a simple, consistent contributor workflow. Initial CI runs demonstrate that this pair works with the required template changes and npm-installed Dart Sass. Local editing workflows are implemented; remaining validation and rollout gates are tracked below. The plan is agreed and implementation is in progress, starting with Docsy GitLab and the Compose/local setup. This issue combines the strategy previously split between #42 (Docsy) and #43 (Hugo), under [FY27 Handbook maintenance](https://gitlab.com/groups/gitlab-com/content-sites/-/work_items/25). Issues #42 and #43 are now closed as superseded by this plan. ## Verified findings 1. **Hugo 0.166.0 works in CI with the current upgrade changes.** The [public pipeline](https://gitlab.com/gitlab-com/content-sites/handbook/-/pipelines/2841373501) and [internal pipeline](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/pipelines/2841373490) passed. These test the earlier shared-theme commit `55293f5a9ec7`; they do not validate subsequent edits automatically. The [current theme pipeline](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/pipelines/2841466047) also passes for branch commit `86aa547cb9cc`. 1. **Docsy 0.17.0 needs coordinated dependency and template changes.** Its relocated `github.com/google/docsy/theme` module uses an npm workspace for Bootstrap and Font Awesome. Dart Sass is supplied by the pinned `sass-embedded` 1.102.0 dependency. `npm ci` installs it; Hugo must also find the project binaries on PATH. The installation hook relinks the embedded compiler to prevent the optional JavaScript Sass fallback from claiming the same executable. 1. **The official Hugo image works with that setup.** The successful handbook jobs used `ghcr.io/gohugoio/hugo:v0.166.0`. Its bundled Sass alone is insufficient for this Docsy upgrade; the project dependency supplies the required compiler. Keep CI and local Docker on the same pinned image and dependency lockfiles. 1. **Local editing needs a simpler interface.** Contributors should not need to understand `hugoautogen`, long `docker run` commands, Sass PATH details, or npm wrappers around every Hugo command. The generated workspace is maintained and committed during dependency upgrades; normal editing uses `make view` or `make build`, which run `npm ci` automatically. 1. **Hugo 0.164.0 was a compatibility option, not a requirement to downgrade.** Local builds passed for the theme and both handbooks, and the HugoMods Dart Sass image built the theme. The selected target remains 0.166.0, supported by the CI evidence above. Upstream migration references: [Docsy 0.16](https://www.docsy.dev/blog/2026/0.16.0/), [Docsy 0.17](https://www.docsy.dev/blog/2026/0.17.0/), [Hugo 0.166.0](https://github.com/gohugoio/hugo/releases/tag/v0.166.0). ## Performance findings From the [FY27 performance discussion](https://gitlab.com/groups/gitlab-com/content-sites/-/work_items/25#note_3822554706): one successful Hugo 0.166.0 / Docsy 0.17.0 upgrade run per site was compared with the five preceding successful `main` pipelines on 2026-09-11, using Hugo 0.151.0. Baselines are medians. | Site | Hugo rendering: main → upgrade | Reduction | Full build job: main → upgrade | Reduction | | --- | --- | --- | --- | --- | | Public handbook | 327.1s → 78.4s | **76% (4.2× faster)** | 492.8s → 245.5s | **50%** | | Internal handbook | 52.5s → 27.8s | **47% (1.9× faster)** | 114.3s → 96.9s | **15%** | Evidence: [public build job](https://gitlab.com/gitlab-com/content-sites/handbook/-/jobs/16451435458), [internal build job](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/jobs/16451435189). The linked discussion includes all ten baseline job links and the measurement method. The public pipeline took **6m 15s**, versus a **10m 17s** main median. This is less directly comparable because the MR's manual Pages deployment had not run and main has different deployment/notification work. Prefer Hugo and build-job timings when assessing gains. All build jobs used the `saas-linux-medium-amd64` runner class, with different individual runners. Public output was 4,661–4,662 pages; internal output was 1,573 pages. Both upgrade jobs missed all three caches, while main restored two and missed one. Restored caches do not explain the improvement. This measures the combined Hugo, Docsy, Sass and image changes from one upgrade run, not an isolated benchmark of the Hugo fix or image. Repeat the comparison on the final version of the integration MRs. ## Required changes ### Shared theme and dependency migration - [x] Review the full upstream release span and inventory local overrides against Docsy 0.17.0. - [x] Keep Hugo 0.166.0 pins aligned across `.tool-versions`, theme compatibility configuration, CI, container configuration and documentation in all three repositories. - [x] Finalize the relocated Docsy module, committed npm workspace, lockfiles and Dart Sass dependency. Keep `hugo mod npm pack` in maintainer instructions only. - [x] Complete the template/API changes: `hugo.Data`, language configuration, GitLab API retrieval and error handling, navbar styling and duplicate TOC heading removal. Retain only necessary overrides and document their upstream source/removal condition. - [x] Validate existing raw HTML content handling and handbook-specific configuration/data changes in the affected repository. Review any stricter-parser findings without suppressing errors. ### Simple local and container workflows - [x] Make the Makefile the common entry point for setup, preview and build. Keep native instructions short: install pinned tools, then run `make view` or `make build`; both install dependencies with `npm ci` automatically. - [x] Have Makefile targets provide the project binary PATH and required data synchronization. Hide Sass and npm workspace implementation details from the everyday editing flow. - [x] Add `compose.yml` to each repository that needs an independent preview. `docker compose up` should install project dependencies, synchronize data and start Hugo at `http://localhost:1313` without host Node.js, Go or Hugo. - [x] Preserve `make docker-prep`, `make docker-view`, and `make docker-build` as direct `docker run` targets. Add separate `make compose-prep`, `make compose-view`, `make compose-build`, and `make compose-down` targets; retain `docker compose up` as the simple Compose entry point. Both workflows use the same container setup script. - [x] Use the same pinned official Hugo 0.166.0 image as CI. Ensure required sync tools are available inside the container and the npm-installed Sass compiler is selected. - [x] Keep container `node_modules` separate from host packages, handle lockfile updates, and verify bind addresses, file watching, Git metadata and Git worktrees. - [ ] Test clean-checkout setup, subsequent startup, content edits, dependency changes, shutdown and a noninteractive container build. Document only the short user commands and necessary troubleshooting. - [x] Update the canonical local/Docker docs and the Docsy upgrade issue template to match the validated workflow. ### Separate downstream validation **Yes: both public and internal handbooks must test the shared-theme MR separately before release.** A passing theme pipeline does not cover their different content, local layouts, configuration or build scale. - [x] Reuse [Docsy GitLab !329](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/merge_requests/329), [internal handbook !9015](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/9015), and [public handbook !21074](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/21074); keep them draft during this work. - [x] Refresh internal !9015 to released theme **v0.4.1**, without a local `replace` directive; source commit `eb59c0717e4c9e7e96a373309c89af04d987463e`. - [ ] Refresh public !21074 to the same released theme **v0.4.1**, without a local `replace` directive. - [x] Run the internal handbook full pipeline and manual Pages job against v0.4.1: [pipeline 2848232162](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/pipelines/2848232162) and [Pages job 16493378877](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/jobs/16493378877) passed. The merged-results pipeline tested `f054bda50f6f39313eccabef77fa38d87765d995`. - [ ] Run the public handbook full pipeline and manual Pages job after refreshing its release pin. Rerun affected checks in either handbook after further shared-theme changes. - [x] Public local homepage: purple navbar, cards, icons and typography ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823376581)). - [x] Public local Mermaid rendering, sidebar and TOC presentation ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823377693)). - [x] Public local performance-indicator layout, health badges and expandable chart embed; Tableau sign-in screen renders ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823384855)). Authenticated chart contents are not verified by this screenshot. - [x] Public local generated categories and engineering-project tables ([screenshots](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823392838)). The Features screenshot in that note is from production, not the upgraded local preview. - [x] Public local handbook-count shortcode and anchored page layout ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823397523)). - [x] Public local heading hover anchors and code-block copying: confirmed working by Michael during manual testing; copy tested on `/handbook/tools-and-tips/mermaid/`. - [x] Internal local homepage and purple navbar ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823398200)). - [x] Internal local image rendering and sidebar/TOC presentation ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823403217)). - [x] Internal local Mermaid rendering ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823404094)). - [x] Internal local Dev Section performance-indicator table after the YAML fixes ([screenshot](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823409332)); this demonstrates table rendering, not authenticated chart contents. - [ ] Complete remaining [maintenance-page checks](https://handbook.gitlab.com/docs/development/maintenance/#pages-to-check), including search interactions, dark mode, math, redirects, Git metadata, Features on the upgrade, and other changed internal performance-indicator pages. Screenshot coverage does not establish every navigation interaction. - [x] Internal !9015 visual sign-off against v0.4.1: Michael confirmed the MR visually on 2026-09-14; [deployed review app](https://gitlab-com.gitlab.io/content-sites/internal-handbook/mr9015/). This general sign-off does not imply every remaining maintenance-page interaction above was individually tested. - [ ] Complete public deployed review-app checks against the released theme pin. Explicitly verify review-prefixed breadcrumb links in both handbooks. Sidebar auto-scrolling remains tracked separately in [public handbook #562](https://gitlab.com/gitlab-com/content-sites/handbook/-/issues/562) and is outside these upgrade MRs. - [ ] Record exact theme and handbook SHAs, pipeline/review-app URLs, pages checked, screenshots for visual changes, remaining warnings and failures. CI success alone is not visual review-app sign-off. - [x] Record the expanded five-new versus five-old MR pipeline benchmarks for each project, including cache conditions and all job links: [full comparison](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/work_items/51#note_3823613262). - [ ] Record final released-pin Hugo/build-job timings and cache conditions against comparable main builds; the completed benchmark samples earlier upgrade revisions. ### Agreement, release and rollback - [x] Agree on this combined strategy, then close #42 and #43 as superseded by this issue. - [x] Merge the shared-theme upgrade: [!329](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/merge_requests/329) merged on 2026-09-14. Released-version validation remains a gate for each downstream merge, as tracked above. - [x] Publish the theme through the release automation: [v0.4.1](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/releases/v0.4.1), commit `d1dffb51baaac76a0058c1c37af120d109c296b4`, [successful release job](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/jobs/16493090120). Production updates must use this released theme version. - [ ] Roll out to the internal handbook first, then public, validating the released version in each. - [ ] Record the previous theme/Hugo pair and coordinated dependency/configuration rollback steps. Dependency security fixes are included in the upgrade work; the refreshed internal checkout passed `npm ci` and `npm audit` with zero findings. This does not establish the audit result for the pending public release-pin refresh. ## Earlier implementation checkpoint — 2026-09-11 The following records earlier commits and deployments. Local visual checks are now recorded in the checklist above; final-pin and deployed review-app validation remain separate release gates. The three existing draft MRs now contain the agreed version pair and Compose/local setup. Both handbooks pin theme commit `5f2d18b8b47f` (`v0.3.72-0.20260911164116-5f2d18b8b47f`). Issues #42 and #43 are closed as superseded. - Theme: [MR !329](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/merge_requests/329), [passing pipeline](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/pipelines/2841522116). - Internal: [MR !9015](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/merge_requests/9015), [passing pipeline](https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/pipelines/2841524265), [deployed review app](https://gitlab-com.gitlab.io/content-sites/internal-handbook/mr9015/). The review app requires GitLab sign-in; authenticated visual review remains outstanding. - Public: [MR !21074](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/21074), [pipeline](https://gitlab.com/gitlab-com/content-sites/handbook/-/pipelines/2841524294). The full pipeline and Pages deployment job passed, and GitLab lists the `mr21074` deployment. The [review URL](https://gitlab-com.gitlab.io/content-sites/handbook/mr21074/) still served the main site's 404 page after deployment; availability and visual sign-off remain unresolved. The published artifact contains the expected homepage and review-prefixed assets. Verified locally: native theme build (22 pages), Compose theme build with Git metadata (22), full internal Compose build (1,573), and full public Compose build (4,661). Direct Compose startup in a clean regular checkout and Makefile startup from a Git worktree returned HTTP 200. Saving a content edit triggered a rebuild and changed the rendered page. Restart and shutdown worked. Polling is enabled because Docker file sharing did not forward native file events in the tested environment; an optional port override also avoids collisions with existing previews. Updated development docs pass Markdownlint and Vale; the maintainer issue template passes Markdownlint. Compose configuration and entrypoint syntax checks pass. CI build timings for the final pins are 23.923s internal and 77.321s public, consistent with the earlier combined-upgrade findings. At this earlier checkpoint, release and merge were still pending. See the current checkpoint and checklist above for the subsequent theme release and internal validation; deploy internal before public. ### Docker workflow clarification Direct Docker commands remain supported. Existing `docker-*` Makefile targets use `docker run`; Compose is an additional workflow exposed through `compose-*` targets. Both use the pinned CI image, isolated dependencies, and the same setup script. ### Sidebar override removed The full `layouts/_partials/sidebar-tree.html` override was removed from !329 to inherit upstream sidebar changes. The warning-count arithmetic is tracked separately in #53 under this epic. A Hugo 0.166.0 Docker theme build passed (22 pages) using the upstream template; no truncation warning appeared in that build. Final downstream validation remains required.