Release 0.16.0 report and upgrade guide

Release summary

• Theme folder move: the canonical theme now lives under theme/; each install mode needs a one-line path update
• Hugo 0.160.1+ support: the theme minimum was raised from 0.146.0; the project build now runs Hugo 0.164.0
• Bootstrap and Font Awesome via npm: theme dependencies now come from npm via hugo mod npm pack, and PostCSS is opt-in for non-RTL sites
• Favicons: no more default artwork – sites supply their own icons, discovered from static/ by filename convention
• Shared chrome build mode (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: repository package layout, and build and test guards

Ready to Upgrade?

• Review BREAKING changes:
  • Theme folder move
  • Minimum Hugo version
  • Default favicons removed
  • Bootstrap and Font Awesome via npm
• Review the companion Hugo 0.158+ upgrade guide if your site is not already building cleanly with Hugo 0.164.0.
• Optionally skim:
  • New favicon discovery behavior
  • Experimental shared chrome build mode
  • Repository packaging cleanup
  • PostCSS is opt-in for non-RTL sites
  • Other notable changes
• Jump to Upgrade to 0.16.0 once you are ready.

/ Theme folder move

Docsy’s canonical theme tree has moved from the repository root to theme/. This is the main structural change in 0.16.0.

For most sites, the upgrade is intentionally small: update the place where Hugo 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.

Actions

Replace VERSION with the Docsy version you want to install, for example v0.16.0.

Hugo module sites

Applies if your site imports Docsy as a Hugo module.

Change the module import path from github.com/google/docsy to github.com/google/docsy/theme:

# OLD
module:
  imports:
    - path: github.com/google/docsy

# NEW
module:
  imports:
    - path: github.com/google/docsy/theme

Then update the module:

hugo mod get github.com/google/docsy/theme@VERSION
hugo mod tidy

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

Applies if your site installs Docsy from GitHub with npm and uses themesDir: node_modules.

Change the theme path:

# OLD
theme: docsy
themesDir: node_modules

# NEW
theme: docsy/theme
themesDir: node_modules

The install command shape is otherwise unchanged:

npm install --save-dev google/docsy#semver:VERSION

Git clone or Git submodule sites

Applies if your site keeps Docsy under themes/docsy/ as a clone or Git submodule.

Change the theme path:

# OLD
theme: docsy

# NEW
theme: docsy/theme

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/:

npm run postinstall

For a fresh clone or submodule setup, see Other installation options.

Hugo 0.160.1+ support

Docsy 0.16.0 raises the theme’s minimum supported Hugo version from 0.146.0 to 0.160.1. The minimum reflects three changes in this range:

• Theme templates use Hugo language APIs introduced in 0.158.0; older Hugo versions fail with template errors.
• The theme’s npm-sourced dependencies rely on hugo mod npm pack support introduced in 0.159.0. On older Hugo versions the pack step exits successfully but writes empty dependency lists, so the failure surfaces only later, as a hard-to-trace SCSS import error — Hugo’s minimum-version warning is the only early signal.
• 0.160.1 excludes the known regressions in the 0.159.2 to 0.160.0 range, such as Markdown-link escaping, and passthrough and shortcode rendering.

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, as are the Docsy example site and at least one large downstream Docsy site. 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.

This distinction — the minimum Hugo version versus the officially supported version that the project pins and tests — is now documented as part of Docsy’s official support policy.

Actions

Applies to all projects upgrading to Docsy 0.16.0.

• Upgrade to Hugo 0.160.1 or later. Prefer Hugo 0.164.0; for install commands, see the Hugo guide’s Upgrade to Hugo 0.164.0 section.
• If your site declares module.hugoVersion.min, set it to at least 0.160.1.
• If your site is multilingual or overrides language-related templates, follow the language-API renames in the Hugo guide.

/ Bootstrap and Font Awesome via npm

Applies to Hugo-module installs. If your site uses Docsy as a Hugo module, the upgrade needs one new step (see Actions). Sites that install Docsy as an npm package or via clone or submodule are unaffected — they continue to get Bootstrap and Font Awesome through Docsy’s postinstall.

Docsy now sources Bootstrap and Font Awesome from npm rather than importing each project’s GitHub repository as a Hugo module. Those imports were a workaround, since neither project publishes a Go module. Hugo’s first-class npm-module support makes them unnecessary: theme/package.json declares Bootstrap and Font Awesome, and hugo mod npm pack delivers them to your project. This also retires the theme’s generated Go-module requires, a module-sync script, and a Bootstrap rfs vendor workaround.

Actions

Applies if your site imports Docsy as a Hugo module.

After updating the Docsy module, consolidate and install the theme’s npm dependencies:

hugo mod npm pack
npm install

Re-run hugo mod npm pack whenever you update Docsy; Hugo warns when the dependency set drifts.

PostCSS is opt-in for non-RTL sites

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. For the current install guidance, see Install PostCSS.

/ Favicons

Docsy no longer ships default favicon artwork. Sites now own their favicon files, which avoids accidentally publishing Docsy-branded icons on downstream projects.

To keep the common case simple, Docsy’s default favicon partial now discovers and links conventionally named files from your site’s static/ directory. A site that provides files such as static/favicon.ico, static/favicon.svg, and static/apple-touch-icon.png gets the matching <link> elements without overriding a partial.

For the full filename list and helper command reference, see Add your favicons.

Actions

Applies if your site relied on Docsy’s bundled default favicon files.

• Add your own favicon files under static/.
• Build your site and inspect the generated page <head> to confirm the icon links you expect are present.

Applies if your site overrides layouts/_partials/favicons.html.

• Keep your override if you need custom link tags, non-default filenames, a web app manifest, or additional platform icons.
• Otherwise, consider deleting the override and using the default discovery behavior documented in Add your favicons.

If you have a source SVG and ImageMagick installed, you can generate the common raster files with the new helper:

npx gen-favicons static/favicon.svg static/

Shared chrome build mode

Docsy 0.16.0 adds an experimental shared chrome build mode. With td.chrome = shared, Docsy renders the repeated page chrome – the top navbar, the footer, and the left sidebar navigation – on a single donor page per language, then restores it in the browser on every other page using the theme’s chrome-nav.js runtime. The default mode, td.chrome = full, renders complete chrome on every page exactly as before.

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 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. The feature is experimental and may change.

Actions

Applies if you want faster link-checking, output diffing, or previews – especially for a large or multilingual site.

• No action is required. full is the default and existing sites are unaffected.
• To try it, build with td.chrome set to shared (for example, HUGO_PARAMS_TD_CHROME=shared) for non-production builds such as link-checking or CI, and keep full for published output.
• Because shared mode is experimental, don’t rely on it for production HTML yet. See Chrome build modes.

Other notable changes

Repository and package layout

The Docsy repository now has a clearer package boundary:

• theme/ contains the theme files that consuming sites need.
• 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.

This is mostly a maintainer-facing cleanup. The user-facing effect is the theme path change covered in Theme folder move.

Build and test guards

Docsy’s own test suite now includes guards for Hugo deprecation output and small fixture-site regression tests. These checks helped validate the Hugo 0.158.0 to 0.164.0 upgrade range and the new theme folder install matrix. The project’s link checking also moved from the unmaintained htmltest to Lychee, with a committed link cache for fast, reproducible checks.

Upgrade to 0.16.0

Some upgrade steps are the same for each Docsy release, such as updating your Docsy package or Hugo module. Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.16.0 where the guide refers to 0.12.0. For this release, use:¹

• Docsy: 0.15.0 -> 0.16.0
• Hugo: 0.157.0 -> 0.164.0 (theme minimum: 0.160.1)
• Node: LTS 24 (unchanged)

What’s next?

The 0.16.0 release closes the main user-facing pieces of the theme-folder move. Follow-up repository cleanup and future packaging work continue under Finalize monorepo setup - 26Q2 (#2617). The experimental shared chrome build mode evolves under #2659, and further favicon improvements, such as light- and dark-mode variants, are tracked in #2357.

References

About this release:

• Changelog entry for 0.16.0
• Release page for 0.16.0
• Release 0.16.0 preparation issue (#2615)
• Git history since 0.15.0

• ←Previous
• Next→