Release 0.16.0 report and upgrade guide

Release summary

• Theme folder move: the canonical theme files moved under theme/, separating the consumer-facing theme tree from repository and website tooling (#2641, #2645).
• Hugo support:
  • The theme minimum moved from Hugo 0.146.0 to 0.158.0.
  • The Docsy project build was upgraded to Hugo 0.163.2.
  • Theme templates and docs moved off deprecated Hugo language APIs (#2647, #2648, #2649).
• 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 (#2357, #2595, #2653, #2654, #2656).
• Shared chrome build mode (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 (#2659, #2660, #2662).
• 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.

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.163.2.
• 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. It also makes theme/package.json the owner of theme runtime dependencies such as Bootstrap and Font Awesome.

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

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.

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 --omit=peer

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

For a fresh clone install, use this setup shape:

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

For a Git submodule install, keep your existing submodule update workflow, then run the same docsy postinstall step after updating the submodule.

Hugo 0.158+ support

Docsy 0.16.0 raises the theme’s minimum supported Hugo version to 0.158.0. Theme templates now use Hugo’s newer language APIs, introduced in 0.158.0, so sites building with Hugo 0.157.x or earlier must upgrade Hugo before or while upgrading Docsy (#2581, #2593).

The Docsy project build is validated with Hugo 0.163.2. We recommend moving directly to 0.163.2 unless your project has a reason to pin a lower version. For the detailed Hugo changes between 0.158.0 and 0.163.2, see the companion Hugo 0.158+ upgrade guide.

Actions

Applies to all projects upgrading to Docsy 0.16.0.

• Upgrade to Hugo 0.158.0 or later. Prefer Hugo 0.163.2.
• If your site declares module.hugoVersion.min, set it to at least 0.158.0.
• 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.

/ 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 (#2668).

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.

Docsy’s CSS targets the 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.

/ 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 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. This 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 Bootstrap and Font Awesome runtime 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.163.2 upgrade range and the new theme folder install matrix.

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.163.2 (theme minimum: 0.158.0)
• 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).

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→