Release 0.16.0 report and upgrade guide

Release summary

• Packaging modernization:
  • Theme folder move: a one-line path update per install mode
  • Hugo modules now source Bootstrap and Font Awesome via npm
  • PostCSS now opt-in for non-RTL sites
  • Docsy on the npm registry: the new @docsy/theme package
• Minimum Hugo raised to 0.160.1: was 0.146.0
• New features:
  • Favicon discovery from static/
  • Shared chrome build mode (experimental)
• Other notable changes, and for maintainers: repository package layout, and build and test guards

Ready to upgrade?

• ⚠️ Respect the order of steps to avoid breaking your build.
• 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:
  • Docsy on the npm registry
  • Favicon discovery
  • Experimental shared chrome build mode
  • PostCSS is opt-in for non-RTL sites
  • Other notable changes, and for maintainers
• Jump to Upgrade to 0.16.0 yourself, or ask an AI agent.

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

This keeps the installable theme surface lean, with maintainer tooling, tests, and release automation out of the theme’s way.

Actions

The version-update commands below run at their place in the order of steps – after any Node and Hugo updates. Set VERSION to the Docsy version you want to install, in a manner compatible with your shell, for example:

VERSION=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. To verify the update, confirm that your site’s go.mod now records github.com/google/docsy/theme at the version you requested.

GitHub npm installs

Applies if your site installs Docsy from GitHub with npm.

GitHub npm installs are now for development and testing only; for production use, switch to the new @docsy/theme registry package. Its Actions cover this starting state.

If you stay on the GitHub install, 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 – for example, for a submodule:

git -C themes/docsy fetch --tags && git -C themes/docsy checkout $VERSION

Then 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.

Minimum Hugo raised to 0.160.1

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 the workspace-aware hugo mod npm pack support that Hugo 0.159.0 added. 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.

The Docsy project build and example site are validated with Hugo 0.164.0. 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, which need one new upgrade step. Sites that install Docsy from GitHub with npm, 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.

Docsy on the npm registry

Hugo made npm dependencies of modules first-class; Docsy follows that lead and takes it one step further: the theme itself is now published to the npm registry as @docsy/theme. The registry package delivers the theme with Bootstrap and Font Awesome as ordinary npm dependencies, with no extra toolchain or install step:

npm install --save-dev @docsy/theme

For setup details, see Docsy as an NPM package.

Registry releases are official releases: the official support policy now counts the npm package alongside the Hugo module and GitHub release tags.

Actions

Applies if your site installs Docsy from GitHub with npm (google/docsy#semver:…).

• Switch to the registry package:

  npm uninstall docsy
  npm install --save-dev @docsy/theme
  

• Update the theme path in your site config; the quotes are required in YAML:

  # OLD (docsy/theme for 0.16, docsy before the theme folder move)
  theme: docsy/theme
  themesDir: node_modules
  
  # NEW
  theme: '@docsy/theme'
  themesDir: node_modules
  

PostCSS is opt-in for non-RTL sites

Docsy now runs postCSS only for sites with RTL languages (which need it for rtlcss, a PostCSS plugin) or that provide their own PostCSS config. Other sites no longer need a PostCSS toolchain at all.

Nothing is lost in dropping the pass: its only job on non-RTL CSS was Autoprefixer, and modern browsers have largely obviated vendor prefixing. Docsy’s shipped CSS targets the Browserslist defaults browsers (see Install PostCSS), and against those browsers Autoprefixer leaves the theme’s CSS byte-for-byte unchanged, so the pass had quietly become a no-op that only imposed a toolchain requirement.

Actions

Applies if your site has no RTL language and no postcss.config.* of its own.

• Drop autoprefixer, postcss, and postcss-cli from your dependencies; your builds no longer need them.

Applies if your site needs PostCSS: it has an RTL language, or you want Autoprefixer or other PostCSS plugins for your own CSS.

• Keep your PostCSS toolchain as documented in Install PostCSS. A project-root postcss.config.{js,mjs,cjs} opts your production build back into the PostCSS pass.

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

If you have a source SVG and ImageMagick installed, you can generate the common raster files with the new helper. For an npm package install of Docsy:

npx --no-install gen-favicons static/favicon.svg static/

For the equivalent command under other install modes, see Add your favicons.

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. 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.

• 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.
• Don’t rely on shared mode for production HTML yet. See Chrome build modes.

Other notable changes

• Russian UI strings: synced with the English originals and corrected.

For this and all other changes, see the 0.16.0 release page.

For maintainers

Changes in this section affect Docsy maintainers and contributors, not consuming sites.

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.

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

Follow Update Docsy and as you do:

• ⚠️ Respect the order of steps to avoid breaking your build.
• Apply the config changes from this release’s theme folder move; the Update Docsy pages already show the post-move install paths.
• Use these versions:¹
  • Docsy: 0.15.0 -> 0.16.0
  • Hugo: 0.157.0 -> 0.164.0; theme minimum: 0.160.1
  • Node: LTS 24 (unchanged)
• Remember to review your theme overrides: this release moves and reworks theme files that sites commonly override.

Upgrading with AI?

Give your assistant this post and the companion Hugo guide as context: they are written to double as operating instructions, with applies-if gates, per-mode actions, verification steps, and sanity checks. During review, these posts were exercised by an AI agent against the Docsy example site.

What’s next?

The 0.16.0 release completes the theme-folder move and its packaging arc, including publishing the theme to the npm registry. Work towards the next release is tracked under Release 0.17.0 preparation.

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→