Skip to content

Lean and DRY pass over the 0.16.0 release artifacts #2682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chalin merged 12 commits into from
Jul 19, 2026
Merged

Lean and DRY pass over the 0.16.0 release artifacts #2682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
e691552
Defer restated 0.16.0 mechanics to canonical homes
chalin Jul 18, 2026
96c9a43
Lean intra-page pass over the 0.16.0 release post
chalin Jul 18, 2026
436b32a
Guidance: release posts are lean, summaries read as selective ToCs
chalin Jul 18, 2026
329a9a2
Lean intra-page pass over the Hugo 0.158+ upgrade guide
chalin Jul 18, 2026
e2ae4a0
Make the release post the sole owner of the Hugo version requirements
chalin Jul 19, 2026
59870b0
Freeze Hugo version literals in the 0.152 post; document the rule
chalin Jul 19, 2026
42574f1
Freeze post Hugo versions via page params, guarded by test
chalin Jul 19, 2026
50636e4
Rename post page param hugoTarget to hugoSupportedVersion
chalin Jul 19, 2026
7268f42
Drop comments restating the frozen-version rule
chalin Jul 19, 2026
e2350a8
Require draft posts to freeze the currently declared Hugo versions
chalin Jul 19, 2026
1b29769
Blog: keep double-homed facts in their canonical sections
chalin Jul 19, 2026
7dc9d5e
Close two false greens in the frozen-Hugo-version guard
chalin Jul 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 67 additions & 88 deletions docsy.dev/content/en/blog/2026/0.16.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ author: >-
for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
body_class: release-highlights
tags: [release, upgrade]
params:
hugoSupportedVersion: 0.164.0
cSpell:ignore: CatmullRom favicons TOF
---

Expand All @@ -36,34 +38,20 @@ cSpell:ignore: CatmullRom favicons TOF

## Release summary

- **[Theme folder move](#theme-folder)**: the canonical theme files moved under
`theme/`, separating the consumer-facing theme tree from repository and
website tooling.
- **[Hugo support](#hugo)**:
- The theme minimum moved from Hugo 0.146.0 to **0.160.1**.
- The Docsy project build was upgraded to **Hugo 0.164.0**.
- Theme templates and docs moved off deprecated Hugo language APIs.
- **[Bootstrap and Font Awesome via npm](#npm-deps)**:
- The theme sources Bootstrap and Font Awesome from npm through
[`hugo mod npm pack`][hugo-npm-pack], rather than importing their GitHub
repositories as Hugo modules.
- Hugo-module sites pull the dependencies with `hugo mod npm pack` and
`npm install`; other install modes are unaffected.
- PostCSS is now [opt-in for non-RTL sites](#postcss).
- **[Favicons](#favicons)**:
- The theme no longer ships default favicon artwork.
- The default partial discovers and links common favicon filenames from a
site's `static/` directory.
- A `gen-favicons` helper can generate raster icons from a source SVG.
- **[Shared chrome build mode](#shared-chrome)** (experimental): a new opt-in
`td.chrome = shared` mode that emits the repeated chrome (navbar, footer,
left-nav) once per language and restores it in the browser, so one build
serves both readers and link checkers; the default `full` mode is unchanged.
- **Other notable changes**:
- Theme runtime dependencies now live in `theme/package.json`.
- The repository uses npm workspaces for `docsy.dev` and `theme`.
- Test coverage now includes Hugo deprecation checks and small fixture-site
regression tests.
- **[Theme folder move](#theme-folder)**: the canonical theme now lives under
`theme/`; each install mode needs a one-line path update
- **[Hugo 0.160.1+ support](#hugo)**: the theme minimum was raised from 0.146.0;
the project build now runs Hugo {{% param hugoSupportedVersion %}}
- **[Bootstrap and Font Awesome via npm](#npm-deps)**: theme dependencies now
come from npm via [`hugo mod npm pack`][hugo-npm-pack], and
[PostCSS is opt-in](#postcss) for non-RTL sites
- **[Favicons](#favicons)**: no more default artwork -- sites supply their own
icons, discovered from `static/` by filename convention
- **[Shared chrome build mode](#shared-chrome)** (experimental): emits the
repeated chrome once per language and restores it in the browser, so one build
serves both readers and link checkers
- **[Other notable changes](#other-notable-changes)**: repository package
layout, and build and test guards

## Ready to Upgrade? <a id="breaking-changes"></a> {#ready-to-upgrade}

Expand All @@ -73,11 +61,11 @@ cSpell:ignore: CatmullRom favicons TOF
- {{% _param BREAKING %}} [Default favicons removed](#favicons)
- {{% _param BREAKING %}} [Bootstrap and Font Awesome via npm](#npm-deps)
- Review the companion [Hugo 0.158+ upgrade guide][hugo-upgrade] if your site is
not already building cleanly with Hugo 0.164.0.
not already building cleanly with Hugo {{% param hugoSupportedVersion %}}.
- Optionally skim:
- {{% _param NEW %}} New favicon discovery behavior
- {{% _param NEW %}} New [favicon discovery](#favicons) behavior
- {{% _param NEW %}} Experimental [shared chrome build mode](#shared-chrome)
- {{% _param CLEANUP %}} Repository packaging cleanup
- {{% _param CLEANUP %}} [Repository packaging cleanup](#package-layout)
- {{% _param CLEANUP %}} [PostCSS is opt-in for non-RTL sites](#postcss)
- [Other notable changes](#other-notable-changes)
- {{% _param FAS rocket primary %}} Jump to [Upgrade to 0.16.0](#upgrade) once
Expand All @@ -93,8 +81,7 @@ looks for the theme. The exact edit depends on how your site installs Docsy.

This change lets the project keep the installable theme surface lean while
moving repository-only tooling, website tooling, tests, and release automation
out of the theme's way. It also makes `theme/package.json` the owner of theme
runtime dependencies such as Bootstrap and Font Awesome.
out of the theme's way.

### Actions {#theme-folder-actions}

Expand Down Expand Up @@ -127,9 +114,9 @@ hugo mod get github.com/google/docsy/theme@VERSION
hugo mod tidy
```

Users still request `@v0.16.0` in the command above. The release process creates
the matching nested Hugo module tag, `theme/v0.16.0`, at the same commit as the
repository release tag.
You still request the plain release version, as in the command above; each
release also creates the matching nested Hugo module tag, such as
`theme/v0.16.0`.

#### GitHub NPM package sites {#npm-sites}

Expand Down Expand Up @@ -169,17 +156,14 @@ theme: docsy
theme: docsy/theme
```

For a fresh clone install, use this setup shape:
Then update your clone or submodule to _`VERSION`_ using your existing update
workflow, and re-run the theme's install step from inside `themes/docsy/`:

```sh
cd themes
git clone -b VERSION https://github.com/google/docsy
(cd docsy && npm run postinstall)
cd ..
npm run postinstall
```

For a Git submodule install, keep your existing submodule update workflow, then
run the same `docsy` postinstall step after updating the submodule.
For a fresh clone or submodule setup, see [Other installation options][].

## {{% _param BREAKING %}} Hugo 0.160.1+ support {#hugo}

Expand All @@ -199,10 +183,13 @@ Docsy 0.16.0 raises the theme's minimum supported Hugo version from 0.146.0 to
Sites building with an older Hugo version must upgrade Hugo before or while
upgrading Docsy.

The Docsy project build is validated with **Hugo 0.164.0**. We recommend moving
directly to 0.164.0 unless your project has a reason to pin a lower version. For
the detailed Hugo changes between 0.158.0 and 0.164.0, see the companion [Hugo
0.158+ upgrade guide][hugo-upgrade].
The Docsy project build is validated with **Hugo
{{% param hugoSupportedVersion %}}**, as are the Docsy example site and at least
one large downstream Docsy site. We recommend moving directly to
{{% param hugoSupportedVersion %}} unless your project has a reason to pin a
lower version. For the detailed Hugo changes between 0.158.0 and
{{% param hugoSupportedVersion %}}, see the companion [Hugo 0.158+ upgrade
guide][hugo-upgrade].

This distinction — the **minimum** Hugo version versus the **officially
supported** version that the project pins and tests — is now documented as part
Expand All @@ -212,19 +199,13 @@ of Docsy's [official support policy][].

{{% _param BREAKING %}} **Applies to all projects upgrading to Docsy 0.16.0.**

- Upgrade to Hugo 0.160.1 or later. Prefer Hugo 0.164.0.
- Upgrade to Hugo 0.160.1 or later. Prefer Hugo
{{% param hugoSupportedVersion %}}; for install commands, see the Hugo guide's
[Upgrade to Hugo {{% param hugoSupportedVersion %}}][hugo-upgrade-install]
section.
- If your site declares `module.hugoVersion.min`, set it to at least `0.160.1`.
- If your multilingual site config still uses Hugo's older language keys,
consider updating them:
- `languageName` -> `label`
- `languageDirection` -> `direction`
- If your site overrides Docsy templates or language-related partials, check for
deprecated Hugo language API names such as `.Language.Lang`, `.LanguageName`,
and `.LanguageDirection`.

The old language config keys still work in site configuration, but updating them
keeps builds quiet as Hugo moves deprecations from info messages toward warnings
and, later, errors. For current Docsy examples, see [Multi-language support][].
- If your site is multilingual or overrides language-related templates, follow
the [language-API renames][hugo-language-apis] in the Hugo guide.

## {{% _param BREAKING %}} / {{% _param CLEANUP %}} Bootstrap and Font Awesome via npm {#npm-deps}

Expand Down Expand Up @@ -261,12 +242,8 @@ dependency set drifts.
Docsy now runs `postCSS` only for sites with RTL languages (which need it for
`rtlcss`) or that provide a project-root `postcss.config.{js,mjs,cjs}`. Other
sites no longer need a PostCSS toolchain at all and can drop `autoprefixer`,
`postcss`, and `postcss-cli` from their dependencies.

Docsy's CSS targets the [Browserslist `defaults`][browserslist-defaults]
browsers. To keep Autoprefixer (or other PostCSS plugins) for a non-RTL site,
add a project-root `postcss.config.js` and install your own PostCSS
dependencies.
`postcss`, and `postcss-cli` from their dependencies. For the current install
guidance, see [Install PostCSS][].

## {{% _param BREAKING %}} / {{% _param NEW %}} Favicons {#favicons}

Expand Down Expand Up @@ -319,21 +296,18 @@ The motivation is the contributor and CI experience, not a change to your
published site. Because the chrome's many repeated links appear on one page
instead of on every page, a `shared` build is dramatically cheaper to
link-check, output-diff, and preview -- the outer loop of working on a site --
while readers still get the full page once JavaScript runs. The default `full`
mode stays the default, and a normal production build is unchanged.

The existing large-site navigation optimization is intact and generalized, not
lost. A `full` build on a site above `sidebar_cache_limit` still renders the
left-nav once as a shared cached menu; 0.16.0 only moved that activation from
per-page inline jQuery into the shipped `chrome-nav.js`. As a result,
`chrome-nav.js` now loads on every page regardless of build mode -- worth a note
for JS-audit-conscious sites, and harmless for everyone else.

Think of `shared` mode as a small, experimental first step toward a more
component-oriented Docsy, where shared page regions are authored and shipped
once. For configuration, the kept-or-restored contract, and current limitations,
see [Chrome build modes][chrome]. This feature is [experimental][] and may
change.
while readers still get the full page once JavaScript runs.

The existing large-site navigation optimization is intact: a `full` build on a
site above `sidebar_cache_limit` still renders the left-nav once as a shared
cached menu -- 0.16.0 only moved that activation from per-page inline jQuery
into the shipped `chrome-nav.js`, which now loads on every page regardless of
build mode.

The `shared` mode is a small first step toward a more component-oriented Docsy,
where shared page regions are authored and shipped once. For configuration, the
kept-or-restored contract, and current limitations, see [Chrome build
modes][chrome]. The feature is [experimental][] and may change.

### Actions {#shared-chrome-actions}

Expand All @@ -355,7 +329,7 @@ or previews -- especially for a large or multilingual site.
The Docsy repository now has a clearer package boundary:

- `theme/` contains the theme files that consuming sites need.
- `theme/package.json` owns Bootstrap and Font Awesome runtime dependencies.
- `theme/package.json` owns the theme's runtime npm dependencies.
- `docsy.dev/` owns the website build and site-specific tooling.
- The repository root owns workspace orchestration, release tooling, and tests.

Expand All @@ -378,13 +352,15 @@ Docsy package or Hugo module. Those steps are described in [Upgrade to Docsy
0.12.0. For this release, use:[^vers-note]

- **Docsy**: [0.15.0][] -> [0.16.0][]
- **Hugo**: [0.157.0][] -> [0.164.0][] (theme minimum: [0.160.1][])
- **Hugo**: [0.157.0][] ->
[{{% param hugoSupportedVersion %}}][hugo-supported-version] (theme minimum:
[0.160.1][])
- **Node**: LTS 24 (unchanged)

[^vers-note]:
Matches `docsy.dev`'s tested Hugo pin and the theme's declared minimum Hugo
version. Later Hugo or Node versions may work but are not officially
supported until validated by Docsy.
version. Later Hugo or Node versions may work; see the [official support
policy][].

> [!NOTE]
>
Expand All @@ -398,7 +374,7 @@ Docsy package or Hugo module. Those steps are described in [Upgrade to Docsy
### {{% _param FAS square-check primary %}} Sanity checks

- [ ] **Build your site** locally with Hugo 0.160.1 or later, preferably
0.164.0.
{{% param hugoSupportedVersion %}}.
- [ ] [Check your Docsy install path](#theme-folder-actions) for your install
mode.
- [ ] For Hugo module sites, [pull theme npm deps](#npm-deps-actions) with
Expand Down Expand Up @@ -453,17 +429,20 @@ About this release:
[0.16.0]: https://github.com/google/docsy/releases/v0.16.0
[0.157.0]: https://github.com/gohugoio/hugo/releases/tag/v0.157.0
[0.160.1]: https://github.com/gohugoio/hugo/releases/tag/v0.160.1
[0.164.0]: https://github.com/gohugoio/hugo/releases/tag/v0.164.0
[hugo-supported-version]:
<https://github.com/gohugoio/hugo/releases/tag/v{{% param hugoSupportedVersion %}}>
[Add your favicons]: /docs/content/iconsimages/#add-your-favicons
[browserslist-defaults]: https://github.com/browserslist/browserslist
[chrome]: /docs/deployment/chrome/
[CL@0.16.0]: /project/about/changelog/#next
[compare-0.15.0]: https://github.com/google/docsy/compare/v0.15.0...main
[experimental]: /project/about/changelog/#experimental
[hugo-language-apis]: hugo-0.158.0+/#language-apis
[hugo-upgrade]: hugo-0.158.0+/
[hugo-upgrade-install]: hugo-0.158.0+/#upgrade
[hugo-npm-pack]: https://gohugo.io/hugo-modules/nodejs-dependencies/
[Install PostCSS]: /docs/get-started/docsy-as-module/installation-prerequisites/#install-postcss
[Lychee]: https://github.com/lycheeverse/lychee
[Multi-language support]: /docs/language/
[official support policy]: /project/about/changelog/#official-support
[Other installation options]: /docs/get-started/other-options/
[Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/
<!-- prettier-ignore-end -->
2 changes: 2 additions & 0 deletions docsy.dev/content/en/blog/2026/hugo-0.152.0+.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ author: >-
for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
body_class: release-highlights
tags: [hugo, upgrade]
params:
hugoMinVersion: 0.157.0
# prettier-ignore
cSpell:ignore: dartsass libsass IPTC multihost libwebp opentelemetry
---
Expand Down
Loading
Loading