Hugo docsy upgrade

[AutomatedTester]

Description

Two commits, deliberately separate so they can be reviewed — or reverted — independently.

1. Upgrade Hugo to 0.164.0 and Docsy to 0.16.0

The site was pinned to Hugo 0.148.2 and Docsy 0.10.0, six Docsy minor releases behind. Docsy 0.16.0 requires Hugo 0.160.1 or later and is validated against 0.164.0, so both move together.

Docsy 0.16.0 breaking changes handled here:

• The theme moved into theme/, so the module import path is now github.com/google/docsy/theme.
• Bootstrap and Font Awesome are npm packages rather than Hugo modules. github.com/google/docsy/dependencies is dropped and hugo mod npm pack generates packages/hugoautogen/, which is committed so npm ci works in CI.
• PostCSS is opt-in for sites with no RTL language and no PostCSS config, so autoprefixer, postcss and postcss-cli are removed.
• Default favicon artwork was removed from the theme. Six of the ten favicon links this site emitted came from Docsy, not from this repository. The new discovery partial only looks in static/, while ours live in static/favicons/, so without an override the site emitted no icon links at all. layouts/_partials/favicons.html keeps every existing icon URL and uses Selenium's own pwa-*.png in place of the Docsy-branded androids.

Hugo changes between 0.148.2 and 0.164.0 handled here:

• Language config and template API renames from 0.158.0: languageName → label, .Language.Lang → .Language.Name, .Language.LanguageName → .Language.Label.
• .Site.Data → hugo.Data (deprecated in 0.156.0).
• The gist and twitter/tweet shortcodes were removed in 0.156.0. tweet becomes the built-in x shortcode; gist is replaced by a local shortcode reproducing Hugo's removed template.
• text/html content files are denied by default from 0.162.0, so security.allowContent explicitly allows the .html landing pages this site publishes.
• The global imaging.quality setting was deprecated in 0.163.0. It was set to 75, already Hugo's default, so removing it changes no output.
• .Render now fails the build on a missing view template instead of silently rendering nothing, which surfaced meetings/single.html calling the Docsy content view by its pre-0.16 name.

Stylesheet regressions found in review. Until Docsy 0.16.0 the theme kept _alerts.scss and _nav.scss directly under assets/scss/, so Hugo's union filesystem served this repository's same-named files in their place. Docsy 0.16.0 moved its stylesheets under assets/scss/td/, which left both project files orphaned — present in the repository, imported by nothing. Separately, Docsy 0.16.0 prefixed the Google Fonts variables with td- and changed $td-enable-google-fonts to default to false, so $google_font_name and friends were silently ignored.

Together those accounted for twelve CSS classes present on the live site and absent from the first build of this branch:

Lost	Effect	Cause
alert-static	The announcement banner lost padding-top: 80px, so it rendered behind the fixed navbar and looked as though it had gone	orphaned _alerts.scss
alert-blue, alert-green, alert-cyan, alert-orange, alert-purple, alert-yellow, alert-webdriver	The 8px coloured left border framing sections on /support/ and similar pages	orphaned _alerts.scss
navbar-bg-onscroll, and .td-navbar { background: $primary }	Navbar lost its Selenium green, falling back to the Docsy default	orphaned _nav.scss
googleapis	Encode Sans was never requested; the site fell back to the Bootstrap system font stack	renamed font variables

Fixed by importing alerts and nav from _styles_project.scss and renaming the font variables. Importing layers the project files over the theme's versions rather than replacing them, and _styles_project is imported last, so these rules still win. _nav.scss also needed $font-awesome-font-name → $td-font-awesome-font-name.

A full class-level diff of the minified stylesheet against production now shows two remaining differences, both benign: fa-sharp, a Font Awesome Pro family class this site never uses, and td-offset-anchor, whose :target offset hack Docsy 0.16.0 replaced with a global scroll-padding-top on html, body. The resolved --bs-font-sans-serif stack is byte-identical to production.

Note for maintainers, not changed here: assets/scss/_buttons.scss is imported by nothing and compiles into neither the production stylesheet nor this one, yet .selenium-button-container is used across ten templates and content files. That is pre-existing on trunk. Wiring it up would change how the site looks, so it is left alone.

Version pins updated in netlify.toml, the three workflows, README.md, .gitpod.yml and contributing.{en,ja,pt-br,zh-cn}.md.

Alias handling — the largest part of this commit. Hugo 0.155.0 (gohugoio/hugo#14388) changed alias publication for non-default languages: an alias now publishes relative to that language's site root rather than the publish root, because languages previously clobbered each other's aliases. Both alias styles used here had to move, and all 508 affected URLs still publish at their current paths:

• 260 aliases already carrying their own language prefix would have published twice-prefixed (/ja/ja/...). The prefix is dropped from front matter and Hugo adds it.
• 248 legacy /documentation/<lang>/... aliases predate the 2021 restructure and sit at the site root, which is the English namespace. A translated page can no longer publish there, so they move to the English counterpart.

2. Remove translated pages whose legacy URLs now resolve to English

A consequence of the above is that those 248 legacy URLs now resolve to the English page rather than the translated one. This commit removes the translated pages they no longer reach, and redirects everything:

• 209 translated pages deleted (70 ja, 69 pt-br, 70 zh-cn), leaving roughly 54 translated documentation pages per language.
• 426 URLs preserved as aliases on the English counterparts, covering each deleted page's own permalink and every alias it carried. Permalinks came from hugo list all rather than being derived from file paths, so slug overrides cannot silently drop a URL.
• 97 ref shortcodes in the 51 surviving translated pages pointed at deleted pages. Hugo resolves refs within the current language, so they now pass lang="en". Only the file and line positions Hugo reported are changed, so refs between translated pages that still exist are untouched.

Motivation and Context

The version gap had become a practical problem: ./build-site.sh does not run against a current Hugo install, so contributors with a recent brew install hugo have no working local build. Every release in the 0.148 → 0.164 range also carried security hardening, and 0.164.0 fixes a template-rendering slowdown affecting 0.128.0 onwards.

It also unblocks planned work. Docsy 0.15.0 added per-page Markdown alternate outputs (theme/layouts/all.md, built on .RenderShortcodes) and a llms.txt layout. Building those by hand against Docsy 0.10.0 would have been thrown away by this upgrade, so the upgrade came first.

Reviewers: the judgement call

The second commit removes 179 pages of genuine Japanese, Portuguese and Chinese prose — the other 30 of the 209 were English text sitting in a translated filename. That is the substance of the decision and it is worth arguing about. The commit is kept separate precisely so it can be dropped or reverted without disturbing the upgrade, which stands on its own.

Verification

Both commits were verified by diffing the full built output against a Hugo 0.148.2 baseline captured before any change.

After the upgrade commit:

• Zero non-print URLs lost. llms.txt byte-identical (19,001 bytes). Tab rendering unchanged. Canonical and hreflang links intact across all four languages.
• 224 differences remain, all noindex meta-refresh stubs of print-format aliases, which Hugo no longer renders for unrendered pages.

After the removal commit:

• Every URL still resolves except /ja/documentation/webdriver/ja/documentation/webdriver/browser/, a doubled path produced by an alias missing its leading slash. The URL it was meant to create, /ja/documentation/webdriver/browser/, did not exist before this change either.
• The other 48 differences are noindex print-format copies of the deleted pages.
• Redirects spot-checked: /ja/documentation/webdriver/waits/ and /documentation/ja/webdriver/waits/ both resolve to the English waits page.

Also verified that npm install is now genuinely required — with node_modules absent the build fails with File to import not found or unreadable: ../../vendor/bootstrap/scss/functions. README.md gains that step and an explanation.

Rebased onto current trunk

This branch was rebased onto a47553c and force-pushed, replacing the earlier Merge branch 'trunk' commit so the two commits stay separately reviewable. Everything trunk gained in the meantime is included, including #2769 and the JSON-LD structured data from #2759.

Three resolutions were needed:

• package.json / package-lock.json: trunk bumped postcss, postcss-cli, autoprefixer and browserslist via Renovate. This upgrade removes those dependencies, so the removal wins and the Renovate bumps are moot.
• The JSON-LD block added to layouts/partials/hooks/head-end.html by #2759 sets inLanguage from .Language.Lang, which Hugo 0.158.0 renamed. It now uses .Language.Name, matching the hreflang code directly above it. Verified rendering as "inLanguage":"ja" on translated pages.
• Nine translated pages the second commit deletes were modified on trunk by #2792, #2800 and #2793. Each of those changes is mechanical and already mirrored in the English page that survives, so the deletion stands.

Re-verified against a fresh Hugo 0.148.2 build of a47553c:

• One non-print URL lost, the same /ja/documentation/webdriver/ja/documentation/webdriver/browser/ doubled path described above. The other 272 are noindex print-format alias stubs; all 272 were checked.
• llms.txt byte-identical to the baseline.
• 206 pages lose their JSON-LD block, and all 206 are pages the second commit turns into redirect stubs. No surviving page lost one.
• hreflang still complete on pages that are still translated: 1,166 alternate links across the site.

Resolved risk

GO_VERSION in netlify.toml moves from 1.20.1 to 1.25.5, which I could not confirm locally. The deploy preview for this PR now builds and serves, so Netlify's image does provide it.

Types of changes

• Change to the site
• Code example added (and I also added the example to all translated languages)
• Improved translation
• Added new translation (and I also added a notice to each document missing translation)

Checklist

• I have read the contributing document.
• I have used hugo to render the site/docs locally and I am sure it works.

Note on the first checkbox: the site does change, and I verified it by diffing the complete rendered output against a pre-upgrade baseline rather than by eye. The Netlify deploy preview has since been checked: /documentation/webdriver/bidi/ renders, and both /ja/documentation/webdriver/waits/ and /documentation/ja/webdriver/waits/ redirect to the English page.

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	3fba2aa
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6aaab201823e1a000879728a
😎 Deploy Preview	https://deploy-preview-2771--selenium-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[diemol]

@AutomatedTester the font looks different. Is that intentional?