# Release 0.16.0 report and upgrade guide

> Release report and upgrade guide for Docsy 0.16.0, covering the theme folder move, Hugo 0.158+ support, favicon handling, an experimental shared chrome build mode, and repository packaging cleanup.

---

LLMS index: [llms.txt](/llms.txt)

---

<!-- markdownlint-disable no-space-in-emphasis -->

<div class="td-card card border me-4">
<div class="card-header">
      Highlights
    </div>
<div class="card-body">
    <p class="card-text">
        

- <i class="fa-solid fa-folder-tree text-primary fa-lg"></i>
  <span>**[Theme folder move](#theme-folder)**: the Docsy theme now lives in
  `theme/`, with one config-line update for each supported install mode</span>
- <i class="fa-solid fa-code text-success fa-lg"></i> <span>**[Hugo 0.158+](#hugo)**: Docsy's
  minimum supported Hugo version is now 0.158.0, and the project build is
  validated with Hugo 0.163.2</span>
- <i class="fa-solid fa-star text-info fa-lg"></i> <span>**[Favicons](#favicons)**: sites supply
  their own icons; Docsy discovers conventionally named files in
  `static/`</span>
- <i class="fa-solid fa-bolt text-warning fa-lg"></i> <span>**[Shared chrome](#shared-chrome)**
  (experimental): an opt-in build mode that emits repeated chrome once per
  language for faster link-checking and previews; `full` stays the
  default</span>

</p>
      </div>
  </div>


## 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 ([#2641][], [#2645][]).
- **[Hugo support](#hugo)**:
  - 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](#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](#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
  ([#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? <a id="breaking-changes"></a> {#ready-to-upgrade}

- Review <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span> changes:
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Theme folder move](#theme-folder)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Minimum Hugo version](#hugo)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Default favicons removed](#favicons)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [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.163.2.
- Optionally skim:
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> New favicon discovery behavior
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Experimental [shared chrome build mode](#shared-chrome)
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Repository packaging cleanup
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> [PostCSS is opt-in for non-RTL sites](#postcss)
  - [Other notable changes](#other-notable-changes)
- <i class="fa-solid fa-rocket text-primary px-1"></i> Jump to [Upgrade to 0.16.0](#upgrade) once
  you are ready.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Theme folder move {#theme-folder}

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 {#theme-folder-actions}

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

#### Hugo module sites {#hugo-module-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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`:

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

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

Then update the module:

```sh
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 {#npm-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your site installs Docsy from GitHub with
npm and uses `themesDir: node_modules`.

Change the theme path:

```yaml
# OLD
theme: docsy
themesDir: node_modules

# NEW
theme: docsy/theme
themesDir: node_modules
```

The install command shape is otherwise unchanged:

```sh
npm install --save-dev google/docsy#semver:VERSION --omit=peer
```

#### Git clone or Git submodule sites {#clone-submodule-sites}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your site keeps Docsy under
`themes/docsy/` as a clone or Git submodule.

Change the theme path:

```yaml
# OLD
theme: docsy

# NEW
theme: docsy/theme
```

For a fresh clone install, use this setup shape:

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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Hugo 0.158+ support {#hugo}

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][hugo-upgrade].

### Actions {#hugo-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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][].

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Bootstrap and Font Awesome via npm {#npm-deps}

**Applies to Hugo-module installs.** If your site uses Docsy as a Hugo module,
the upgrade needs one new step (see [Actions](#npm-deps-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`][hugo-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 {#npm-deps-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your site imports Docsy as a Hugo module.

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

```sh
hugo mod npm pack
npm install
```

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

## <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> PostCSS is opt-in for non-RTL sites {#postcss}

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.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Favicons {#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 {#favicons-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **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:

```sh
npx gen-favicons static/favicon.svg static/
```

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Shared chrome build mode {#shared-chrome}

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][chrome]. This feature is [experimental][] and may
change.

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

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **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][chrome].

## Other notable changes {#other-notable-changes}

### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Repository and package layout {#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](#theme-folder).

### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Build and test guards {#build-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.

## <i class="fa-solid fa-rocket text-primary px-1"></i> Upgrade to 0.16.0 {#upgrade}

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:[^vers-note]

- **Docsy**: [0.15.0][] -> [0.16.0][]
- **Hugo**: [0.157.0][] -> [0.163.2][] (theme minimum: [0.158.0][])
- **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.

> [!NOTE]
>
> **Need to roll back?** Re-pin Docsy to [0.15.0][] and restore the pre-0.16
> theme path (`github.com/google/docsy` for Hugo modules, or `docsy` for
> `theme:` installs). Then reverse the [Upgrade to Docsy 0.12.0][]
> package-update steps.

<section class="td-checkbox-list-wrapper">

### <i class="fa-solid fa-square-check text-primary px-1"></i> Sanity checks

- [ ] **Build your site** locally with Hugo 0.158.0 or later, preferably
      0.163.2.
- [ ] [Check your Docsy install path](#theme-folder-actions) for your install
      mode.
- [ ] For Hugo module sites, [pull theme npm deps](#npm-deps-actions) with
      `hugo mod npm pack` and `npm install`.
- [ ] [Check your favicon output](#favicons-actions), especially if you relied
      on Docsy's old default icons.
- [ ] For multilingual sites, review language config keys and custom language
      template overrides.
- [ ] Review the [Hugo 0.158+ upgrade guide][hugo-upgrade] for Hugo-specific
      checks, including Node version, image URL churn, and security policy
      changes.

</section>

## 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)][#2617].

<!-- prettier-ignore -->
> [!INFO]- Your opinion counts!
>
> - <i class="fa-solid fa-thumbs-up text-success px-1"></i> If you'd like a feature or fix to be
>   considered for inclusion in an upcoming release, **upvote** (with a thumbs up)
>   the associated issue or PR.
>
> - <i class="fa-solid fa-star text-warning px-1"></i> If you find Docsy useful, consider [starring
>   the repository][star-the-repo] to show your support.
{._list-unstyled}

[star-the-repo]: https://github.com/google/docsy

## References

About this release:

- Changelog entry for [0.16.0][CL@0.16.0]
- Release page for [0.16.0][]
- [Release 0.16.0 preparation issue (#2615)][#2615]
- Git history since [0.15.0][compare-0.15.0]

<!-- prettier-ignore-start -->
[#2357]: https://github.com/google/docsy/issues/2357
[#2581]: https://github.com/google/docsy/issues/2581
[#2593]: https://github.com/google/docsy/issues/2593
[#2595]: https://github.com/google/docsy/issues/2595
[#2615]: https://github.com/google/docsy/issues/2615
[#2617]: https://github.com/google/docsy/issues/2617
[#2641]: https://github.com/google/docsy/pull/2641
[#2645]: https://github.com/google/docsy/pull/2645
[#2647]: https://github.com/google/docsy/pull/2647
[#2648]: https://github.com/google/docsy/pull/2648
[#2649]: https://github.com/google/docsy/pull/2649
[#2653]: https://github.com/google/docsy/pull/2653
[#2654]: https://github.com/google/docsy/pull/2654
[#2656]: https://github.com/google/docsy/pull/2656
[#2659]: https://github.com/google/docsy/issues/2659
[#2660]: https://github.com/google/docsy/pull/2660
[#2662]: https://github.com/google/docsy/pull/2662
[#2668]: https://github.com/google/docsy/issues/2668
[0.15.0]: https://github.com/google/docsy/releases/v0.15.0
[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.158.0]: https://github.com/gohugoio/hugo/releases/tag/v0.158.0
[0.163.2]: https://github.com/gohugoio/hugo/releases/tag/v0.163.2
[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-upgrade]: hugo-0.158.0+/
[hugo-npm-pack]: https://gohugo.io/hugo-modules/nodejs-dependencies/
[Multi-language support]: /docs/language/
[Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/
<!-- prettier-ignore-end -->