# Release 0.16.0 report and upgrade guide

> Docsy is now on npm as @docsy/theme. This release also moves the theme into theme/, raises the Hugo minimum, and drops its default favicons in favor of discovery, each with upgrade actions.

---

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

---

<!-- markdownlint-disable descriptive-link-text 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-cubes text-primary fa-lg"></i>
  <span>**[First-class npm support](#npm-registry)**: install Docsy from the
  registry, and [more][]</span>
- <i class="fa-solid fa-star text-info fa-lg"></i> <span>**[Favicons](#favicons)**: drop your
  icons into `static/` and Docsy does the rest</span>
- <i class="fa-solid fa-bolt text-warning fa-lg"></i> <span>**[Shared chrome](#shared-chrome)**
  (experimental): a build mode for much faster link checking of large
  sites</span>
- <i class="fa-solid fa-robot text-info fa-lg"></i>
  <span>**[Agent-ready upgrade guide](#upgrading-with-ai)**: hand this post to
  your AI assistant</span>

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


## Release summary

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

## Ready to upgrade? <a id="breaking-changes"></a>

- :warning: Respect the [order of steps][] to avoid breaking your build.
- 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.164.0.
- Optionally skim:
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [Docsy on the npm registry](#npm-registry)
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> [Favicon discovery](#favicons)
  - <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> [PostCSS is opt-in for non-RTL sites](#postcss)
  - [Other notable changes](#other-notable-changes), and
    [for maintainers](#for-maintainers)
- <i class="fa-solid fa-rocket text-primary px-1"></i> Jump to [Upgrade to 0.16.0](#upgrade)
  yourself, or [ask an AI agent](#upgrading-with-ai).

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

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

### Actions {#theme-folder-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:

```sh
VERSION=v0.16.0
```

#### 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
```

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

GitHub npm installs are now for [development and testing
only][official support policy]; for production use, switch to the new
[`@docsy/theme` registry package](#npm-registry). Its
[Actions](#npm-registry-actions) cover this starting state.

If you stay on the GitHub install, 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
```

#### 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
```

Then update your clone or submodule to `$VERSION` using your existing update
workflow -- for example, for a submodule:

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

Then re-run the theme's install step from inside `themes/docsy/`:

```sh
npm run postinstall
```

> [!WARNING]
>
> Run `npm run postinstall`, not `npm install`: a plain `npm install` inside
> `themes/docsy/` pulls in the repository's maintainer workspaces, not just the
> theme's runtime dependencies.

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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Minimum Hugo raised to 0.160.1 {#hugo}

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](#npm-deps) 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][hugo-upgrade].

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 {#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.160.1 or later. Prefer Hugo
  0.164.0; for install commands, see the Hugo guide's
  [Upgrade to Hugo 0.164.0][hugo-upgrade-install]
  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][hugo-language-apis] in the Hugo guide.

## <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**, 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`][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.

### 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-square-check fa-lg text-success px-1"></i> Docsy on the npm registry {#npm-registry}

Hugo made [npm dependencies of modules][hugo-npm-pack] first-class;
[Docsy follows that lead](#npm-deps) 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:

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

<i class="fa-regular fa-square-check fa-lg text-success px-1"></i> **Applies if** your site installs Docsy from GitHub with npm
(`google/docsy#semver:…`).

- Switch to the registry package:

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

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

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

## <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`, 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 {#postcss-actions}

<i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> **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.

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

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:

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

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

## <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 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][chrome]. The 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.

- 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][chrome].

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

### <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 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](#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.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.

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

Follow [Update Docsy][] and as you do:



- :warning: Respect the [order of steps][] to avoid breaking your build.
- Apply the config changes from this release's
  [theme folder move](#theme-folder-actions); the Update Docsy pages already
  show the post-move install paths.
- Use these versions:[^vers-note]
  - **[Docsy][update-theme]**: [0.15.0][] -> [0.16.0][]
  - **[Hugo][update-hugo]**: [0.157.0][] ->
    [0.164.0][hugo-supported-version]; theme minimum:
    [0.160.1][]
  - **[Node][update-node]**: LTS 24 (unchanged)
- Remember to [review your theme overrides][overrides]: this release moves and
  reworks theme files that sites commonly override.

[^vers-note]:
    Matches `docsy.dev`'s tested Hugo pin and the theme's declared minimum Hugo
    version. Later Hugo or Node versions may work; see the [official support
    policy][].

### <i class="fa-solid fa-robot text-info px-1"></i> Upgrading with AI?

Give your assistant this post and the companion [Hugo guide][hugo-upgrade] 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][docsy-example].

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

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

In addition to the [generic site checks][check], for this release:

- [ ] [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 per the Hugo guide's [language-API
      renames][hugo-language-apis].
- [ ] Confirm the [theme path landed](#theme-folder-actions) for your install
      mode.
- [ ] For Hugo-module sites, confirm the site
      [builds without SCSS import errors](#npm-deps-actions).

</section>

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

<!-- 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 -->
[#2615]: https://github.com/google/docsy/issues/2615
[#2691]: https://github.com/google/docsy/issues/2691
[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.160.1]: https://github.com/gohugoio/hugo/releases/tag/v0.160.1
[hugo-supported-version]:
  <https://github.com/gohugoio/hugo/releases/tag/v0.164.0>
[`@docsy/theme`]: https://www.npmjs.com/package/@docsy/theme
[Add your favicons]: /docs/content/iconsimages/#add-your-favicons
[check]: /docs/update/#check
[chrome]: /docs/deployment/chrome/
[CL@0.16.0]: /project/about/changelog/#v0.16.0
[compare-0.15.0]: https://github.com/google/docsy/compare/v0.15.0...v0.16.0
[Docsy as an NPM package]: /docs/get-started/other-options/#option-3-docsy-as-an-npm-package
[docsy-example]: https://github.com/google/docsy-example
[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
[more]: #npm-deps
[official support policy]: /project/about/changelog/#official-support
[Other installation options]: /docs/get-started/other-options/
[order of steps]: /docs/update/#update-order
[overrides]: /docs/update/#update-overrides
[Update Docsy]: /docs/update/
[update-hugo]: /docs/update/#update-hugo
[update-node]: /docs/update/#update-node
[update-theme]: /docs/update/#update-theme
<!-- prettier-ignore-end -->