Hugo docsy upgrade - #2771
Open
AutomatedTester wants to merge 2 commits into
Open
Conversation
The repo 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: - The theme moved into theme/, so the module import path becomes github.com/google/docsy/theme. - Bootstrap and Font Awesome are npm dependencies rather than Hugo modules, so github.com/google/docsy/dependencies is dropped and `hugo mod npm pack` generates packages/hugoautogen/. Re-run it, then `npm install`, whenever Docsy is updated. - PostCSS is opt-in for sites with no RTL language and no PostCSS config of their own, so autoprefixer, postcss, and postcss-cli are removed. - Docsy no longer ships default favicon artwork. Six of the ten icons the site linked came from Docsy, not this repository; the new default partial only discovers icons in static/, while ours live in static/favicons/. layouts/_partials/favicons.html keeps every existing icon URL and uses Selenium's own pwa-*.png in place of Docsy's. Hugo changes between 0.148.2 and 0.164.0: - Language config and template APIs were renamed in 0.158.0: languageName -> label, .Language.Lang -> .Language.Name, .Language.LanguageName -> .Language.Label. - .Site.Data was deprecated in 0.156.0 in favour of hugo.Data. - The gist and twitter/tweet shortcodes were removed in 0.156.0. tweet is replaced by 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 rendering nothing, which surfaced meetings/single.html calling the Docsy content view by its pre-0.16 name. Alias handling (Hugo 0.155.0, gohugoio/hugo#14388): Aliases on a page in a non-default language are now published relative to that language's site root rather than the publish root, because languages previously clobbered each other's aliases. Both alias styles in this repo had to move, and all 508 affected URLs still publish at their current paths: - 260 aliases already carrying their own language prefix would have been published twice-prefixed (/ja/ja/...). The prefix is now 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. The URLs keep working; they now resolve to the English page rather than the translated one. Verified against a 0.148.2 baseline build: llms.txt is byte-identical, tab rendering is unchanged, canonical and hreflang links are intact, and no non-print URL is lost. The 224 remaining differences are noindex meta-refresh stubs of print-format aliases, which Hugo no longer renders for unrendered pages.
The previous commit moved 248 legacy /documentation/<lang>/... aliases onto their English counterparts, because Hugo 0.155.0 no longer lets a translated page publish an alias at the site root. Those URLs kept working but started resolving to the English page rather than the translated one. Rather than keep translated pages that the legacy URLs no longer reach, this removes them and redirects every URL they published: - 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, so nothing 404s. Permalinks were taken from `hugo list all` rather than derived from file paths. - 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" and resolve against the English page, matching where those URLs redirect. Only the file and line positions Hugo reported are changed, so refs to translated pages that still exist are untouched. Verified by diffing the built output against the pre-deletion build: every URL still resolves except /ja/documentation/webdriver/ja/documentation/webdriver/browser/, a doubled path produced by an alias that was 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.
✅ Deploy Preview for selenium-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.0The 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:
theme/, so the module import path is nowgithub.com/google/docsy/theme.github.com/google/docsy/dependenciesis dropped andhugo mod npm packgeneratespackages/hugoautogen/, which is committed sonpm ciworks in CI.autoprefixer,postcssandpostcss-cliare removed.static/, while ours live instatic/favicons/, so without an override the site emitted no icon links at all.layouts/_partials/favicons.htmlkeeps every existing icon URL and uses Selenium's ownpwa-*.pngin place of the Docsy-branded androids.Hugo changes between 0.148.2 and 0.164.0 handled here:
languageName→label,.Language.Lang→.Language.Name,.Language.LanguageName→.Language.Label..Site.Data→hugo.Data(deprecated in 0.156.0).gistandtwitter/tweetshortcodes were removed in 0.156.0.tweetbecomes the built-inxshortcode;gistis replaced by a local shortcode reproducing Hugo's removed template.text/htmlcontent files are denied by default from 0.162.0, sosecurity.allowContentexplicitly allows the.htmllanding pages this site publishes.imaging.qualitysetting was deprecated in 0.163.0. It was set to 75, already Hugo's default, so removing it changes no output..Rendernow fails the build on a missing view template instead of silently rendering nothing, which surfacedmeetings/single.htmlcalling the Docsy content view by its pre-0.16 name.Version pins updated in
netlify.toml, the three workflows,README.md,.gitpod.ymlandcontributing.{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:
/ja/ja/...). The prefix is dropped from front matter and Hugo adds it./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 EnglishA 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:
ja, 69pt-br, 70zh-cn), leaving roughly 54 translated documentation pages per language.hugo list allrather than being derived from file paths, so slug overrides cannot silently drop a URL.refshortcodes in the 51 surviving translated pages pointed at deleted pages. Hugo resolves refs within the current language, so they now passlang="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.shdoes not run against a current Hugo install, so contributors with a recentbrew install hugohave 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 allms.txtlayout. 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:
llms.txtbyte-identical (19,001 bytes). Tab rendering unchanged. Canonical andhreflanglinks intact across all four languages.noindexmeta-refresh stubs of print-format aliases, which Hugo no longer renders for unrendered pages.After the removal commit:
/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.noindexprint-format copies of the deleted pages./ja/documentation/webdriver/waits/and/documentation/ja/webdriver/waits/both resolve to the English waits page.Also verified that
npm installis now genuinely required — withnode_modulesabsent the build fails withFile to import not found or unreadable: ../../vendor/bootstrap/scss/functions.README.mdgains that step and an explanation.Known risk
GO_VERSIONinnetlify.tomlmoves from 1.20.1 to 1.25.5. I could not confirm that Netlify's build image offers that version. If it does not, deploy previews fail; production is unaffected, since that publishes fromdeploy.ymlusing the runner's own Go.Types of changes
Checklist
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. I have not yet seen the Netlify deployment, since the preview builds after this PR is opened.