# Release 0.17.0 report and upgrade guide

> Docsy now builds with Dart Sass, so the sass CLI joins your build. This release also moves breadcrumbs to semantic classes, pins default script versions, and renames the theme-dependencies install command.

---

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-palette text-primary fa-lg"></i> <span>**[Dart Sass](#dart-sass)**: Docsy
  moves off Hugo's deprecated embedded LibSass (one new build
  prerequisite)</span>
- <i class="fa-solid fa-tags text-info fa-lg"></i>
  <span>**[Semantic classes](#semantic-classes)**: Docsy chrome markup starts
  moving from Bootstrap to Docsy's own `td-` classes, beginning with
  breadcrumbs</span>
- <i class="fa-solid fa-thumbtack text-warning fa-lg"></i>
  <span>**[Pinned script versions](#script-dep-pins)**: Mermaid, KaTeX, markmap,
  and Redoc no longer resolve from the CDN's `latest`</span>

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


## Release summary

- **[Dart Sass replaces LibSass](#dart-sass)**: the `sass` CLI becomes a build
  prerequisite
- **[Semantic classes](#semantic-classes)**: breadcrumb markup moves from
  Bootstrap to `td-` classes
- **Install and defaults**:
  - [Theme-dependencies install command renamed](#install-command)
  - [Default script-dependency versions pinned](#script-dep-pins): Mermaid,
    KaTeX, markmap, and Redoc no longer resolve from the CDN's `latest`
- **[Other notable changes](#other-notable-changes)**, and
  [for maintainers](#for-maintainers): supply-chain hardening and npm trusted
  publishing

## 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> [Dart Sass replaces LibSass](#dart-sass)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Breadcrumb semantic classes](#semantic-classes)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Install command renamed](#install-command)
- No Hugo change this release: the [version list](#upgrade) is otherwise
  unchanged too.
- Optionally skim:
  - [Default script-dependency versions pinned](#script-dep-pins)
  - [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.17.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> Dart Sass replaces LibSass {#dart-sass}

Docsy's stylesheets are now transpiled with [Dart Sass][], the actively
developed Sass implementation, instead of Hugo's embedded LibSass. This adds one
build prerequisite: the `sass` CLI must be available on your build's `PATH`.

Why now? Hugo deprecated its embedded LibSass in 0.153.0, with removal to
follow, and Hugo will never bundle Dart Sass: the planned [pure-JS embedded
mode][dart-sass-2413] targets platforms without prebuilt binaries, not an
in-binary compiler. Every further LibSass-built release would grow the set of
sites on a dying pipeline.

Build logs stay quiet: the theme silences Sass deprecation warnings from
dependencies, which as a side effect covers your own [project style files][] too
(though not a custom `main.scss` entry point, whose warnings stay visible). A
quiet build log is therefore not evidence that your own Sass is
deprecation-free.

### Actions {#dart-sass-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies to all sites**: every install mode uses the
theme's default Sass pipeline.

Provide Dart Sass in each environment that builds your site, before the theme
update in the [order of steps][]:

- Follow [Install Dart Sass][]:
  - **npm-based sites**: install the Docsy-tested [`sass-embedded`][] package
    version. CI builds that run through npm scripts need nothing more; GitHub
    Pages and Netlify setups are covered in the [deployment docs][] ([GitHub
    Pages][gh-pages-deploy], [Netlify][]).
  - **Other setups**: follow the guide's pointer to Hugo's Dart Sass
    installation instructions.
- Where your platform dictates a Dart Sass version of its own, it must be at
  least 1.95.0: the theme's stylesheets rely on Sass's
  new `if()` conditional syntax, which older releases can't parse. Only the
  Docsy-tested version is [officially supported][official support policy].

### What to recheck after upgrading {#dart-sass-recheck}

Dart Sass serializes some Sass-computed colors differently than LibSass did (for
example, `rgb(81.02%, 88.63%, 99.84%)` where LibSass emitted `#cfe2ff`), across
Bootstrap-computed custom properties such as `--bs-*-bg-subtle` and
`--bs-table-*`. **Rendered colors are visually unchanged**: a bit-exact visual
regression suite found at most single-channel rounding differences on a few
dozen pixels per page.

- If you diff built CSS across the upgrade, expect thousands of changed lines:
  that is the serialization change, not drift.
- Recheck anything that string-matches `--bs-*` values in CSS, JavaScript, or
  tests, and update the expected strings.
- Custom Chroma style sheets (`assets/scss/td/chroma/_light.scss` and
  `_dark.scss`) are now loaded as isolated Sass modules. Raw
  `hugo gen chromastyles` dumps (the documented form) are unaffected, but a
  hand-tuned dump that references theme or Bootstrap variables such as
  `$primary` now fails with "Undefined variable": inline the color values
  instead.

### No LibSass fallback {#libsass-escape-hatch}

**Applies if** your build platform has no Dart Sass distribution (for example,
the BSDs).

There is no way to keep building this release with Hugo's embedded LibSass: the
theme's stylesheets now use `sass:` modules and Sass's new `if()` conditional
syntax (`if(condition: value; else: value)`), which LibSass does not implement.
In particular, overriding `head-css.html` to restore a LibSass `toCSS` call
builds green but ships an unstyled site. For binary-less platforms, the durable
path is Dart Sass's planned [pure-JS embedded mode][dart-sass-2413].

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Semantic classes: breadcrumbs {#semantic-classes}

Docsy's chrome markup is moving from Bootstrap utility and component classes to
Docsy-owned `td-` [semantic classes][] over the coming releases. In this
release: breadcrumbs.

### Selector migration table

| 0.16 selector                | 0.17 selector                                  |
| ---------------------------- | ---------------------------------------------- |
| `ol.breadcrumb`              | `ol.td-breadcrumbs__list`                      |
| `li.breadcrumb-item`         | `li.td-breadcrumbs__item`                      |
| `li.breadcrumb-item.active`  | `li.td-breadcrumbs__item[aria-current="page"]` |
| `nav.td-breadcrumbs__single` | `nav.td-breadcrumbs--single`                   |

Unchanged: the `td-breadcrumbs` class on the `<nav>` element. The markup no
longer carries an `active` class: state styling keys on the ARIA-mandated
`aria-current="page"` attribute, so visual state and accessibility state can't
drift apart.

One related change: breadcrumbs in taxonomy-term page summaries render without
ARIA attributes (a page summary isn't the current page), so current-item styling
doesn't apply there, as in 0.16.

### Actions {#semantic-classes-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** you style or script against breadcrumb
markup from outside the theme's Sass pipeline: plain CSS files, JavaScript
`querySelector` calls, or tests matching the table's 0.16 selectors.

- Update your selectors per the [table above](#selector-migration-table).

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** you override `breadcrumb.html` or
`term.html`.

- Refresh your overridden copies from the 0.17 theme: partial overrides are
  version-coupled ([review your theme overrides][overrides]). A pre-0.17
  `breadcrumb.html` copy also leaks the stale `active` class into term-page
  summaries, since `term.html`'s summary sanitizer now strips ARIA attributes
  only.

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your project's Sass styles the old
breadcrumb class names.

- Migrate all your selectors now, per the
  [table above](#selector-migration-table). Rules on the old **structural**
  Bootstrap names (`.breadcrumb`, `.breadcrumb-item`) keep matching for the
  moment, an accident of the theme's Bootstrap binding rather than a
  compatibility promise. Rules involving the **state** class are already broken:
  `.breadcrumb-item.active` no longer matches anything, and a `:not(.active)`
  now also matches the current item. The `td-breadcrumbs__single` rename has no
  keep-alive at all: the documented [single-breadcrumb display
  override][single-override] stops matching until renamed.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> Install command renamed {#install-command}

The command that installs the theme's npm dependencies is renamed:
`npm run postinstall` is now `npm run install:theme-deps`. Docsy's packages no
longer declare npm lifecycle install hooks, so installs behave the same with or
without `--ignore-scripts` (one less place where a dependency can run unreviewed
code).

### Actions {#install-command-actions}

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

- After updating the theme, run the renamed command from `themes/docsy/`:

  ```sh
  npm run install:theme-deps
  ```

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your site installs Docsy from GitHub with
npm (development and testing only).

- The theme's dependencies are no longer installed as a side effect of
  `npm install`. Run the install command yourself, from `node_modules/docsy/`,
  or switch to the [`@docsy/theme`][] registry package, which needs no install
  step.

Hugo-module and `@docsy/theme` registry installs are unaffected.

## Default script-dependency versions pinned {#script-dep-pins}

Docsy now pins the default versions of its CDN-loaded script dependencies (see
the table) instead of loading whatever `latest` resolves to on the CDN, so
rendering no longer changes when an upstream major ships.

| Dependency                         | Pinned version               | Loaded as                                     | Version param            |
| ---------------------------------- | ---------------------------- | --------------------------------------------- | ------------------------ |
| [KaTeX][katex-docs]                | 0.18.4   | Build-time stylesheet and fonts (self-hosted) | `params.katex.version`   |
| [markmap-autoloader][markmap-docs] | 0.18.12 | Page-load script                              | `params.markmap.version` |
| [Mermaid][mermaid-docs]            | 11.17.0 | Page-load script                              | `params.mermaid.version` |
| [Redoc][redoc-docs]                | 2.5.3   | Page-load script (`redoc` shortcode)          | `params.redoc.version`   |

### Actions {#script-dep-pins-actions}

**Applies if** you want a different version of one of these dependencies.

- Set the dependency's version param (last column above) in your site config;
  for details, see the dependency's Docsy docs (first column).

## Other notable changes

- **Footer copyright**: a same-year range now renders as the single year
  (`© 2026` instead of `© 2026–2026`). See the [footer copyright docs][].

For this and all other changes, see the [0.17.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> Supply-chain hardening {#supply-chain}

0.17.0 hardens the project's supply-chain posture: npm lockfiles are committed
with lock-exact, script-free installs; a committed supply-chain audit, a
script-runner lint, and an `npm audit` gate guard the dependency and workflow
surface; and npm install hooks and implicit `pre`/`post` run-hooks are gone
(inlined into their parent scripts), with the full test suite renamed to
`test:full`. The changelog's [For-maintainers list][CL@0.17.0] itemizes these.

### <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> npm trusted publishing {#trusted-publishing}

Stable [`@docsy/theme`][] releases are now published from CI via npm [trusted
publishing][] (OIDC): no long-lived registry tokens. This completes the
npm-registry arc announced with 0.16.0.

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Chrome test baselines {#chrome-baselines}

Markup goldens, a framework-class output check, and a visual regression suite
now guard the theme's chrome partials. These baselines gate the semantic-class
migration above and future chrome rework.

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

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



- :warning: Respect the [order of steps][] to avoid breaking your build.
- Provide Dart Sass in every build environment **before** updating the theme;
  see [Dart Sass actions](#dart-sass-actions).
- Use these versions:[^vers-note]
  - **[Docsy][update-theme]**: [0.16.0][] -> [0.17.0][]
  - **[Hugo][update-hugo]**:
    [0.164.0][hugo-supported-version] (unchanged;
    theme minimum [0.160.1][])
  - **[Node][update-node]**: LTS 24 (unchanged)
  - **Dart Sass**: [new requirement](#dart-sass-actions)
- Remember to [review your theme overrides][overrides]: this release reworks
  theme files that sites commonly override, including `head-css.html` and
  `breadcrumb.html`.

[^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 as context: like its predecessors, it is written
to double as operating instructions, with applies-if gates, per-mode actions,
verification steps, and sanity checks.

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

- [ ] Every environment that builds your site provides the `sass` CLI
      (`sass --version`); see [Dart Sass actions](#dart-sass-actions).
- [ ] If you diff built CSS, the changes are
      [serialization-only](#dart-sass-recheck); spot-check for visible color
      drift (single-channel rounding differences are expected).
- [ ] Breadcrumbs render styled, especially if you had custom breadcrumb CSS,
      JavaScript, or overrides; see the
      [selector migration table](#selector-migration-table).
- [ ] Mermaid diagrams render at the [pinned version](#script-dep-pins).

</section>

## What's next?

The [semantic-class transition](#semantic-classes) continues: more chrome
partials will move to `td-` classes in coming releases. For what your site can
rely on during the transition, see [semantic classes][]. Work towards the next
release is tracked under the [0.18.0 milestone][].

<!-- 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.17.0][CL@0.17.0]
- Release page for [0.17.0][]
- [Release 0.17.0 preparation issue (#2691)][#2691]
- Git history since [0.16.0][compare-0.16.0]

<!-- prettier-ignore-start -->
[#2691]: https://github.com/google/docsy/issues/2691
[0.16.0]: https://github.com/google/docsy/releases/v0.16.0
[0.17.0]: https://github.com/google/docsy/releases/v0.17.0
[0.18.0 milestone]: https://github.com/google/docsy/milestone/27
[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
[`sass-embedded`]: https://www.npmjs.com/package/sass-embedded
[check]: /docs/update/#check
[CL@0.17.0]: /project/about/changelog/#next
[compare-0.16.0]: https://github.com/google/docsy/compare/v0.16.0...main
[Dart Sass]: https://sass-lang.com/dart-sass/
[dart-sass-2413]: https://github.com/sass/dart-sass/pull/2413
[deployment docs]: /docs/deployment/
[footer copyright docs]: /docs/content/lookandfeel/#footer-copyright
[gh-pages-deploy]: /docs/deployment/github-pages/
[Install Dart Sass]: /docs/get-started/docsy-as-module/installation-prerequisites/#install-dart-sass
[katex-docs]: /docs/content/diagrams-and-formulae/#katex-version
[markmap-docs]: /docs/content/diagrams-and-formulae/#markmap-version
[mermaid-docs]: /docs/content/diagrams-and-formulae/#diagrams-with-mermaid
[redoc-docs]: /docs/content/shortcodes/#redoc
[Netlify]: /docs/deployment/netlify/
[official support policy]: /project/about/changelog/#official-support
[order of steps]: /docs/update/#update-order
[overrides]: /docs/update/#update-overrides
[Project style files]: /docs/content/lookandfeel/#project-style-files
[semantic classes]: /docs/content/lookandfeel/#semantic-classes
[single-override]: /docs/content/navigation/#breadcrumb-navigation
[trusted publishing]: https://docs.npmjs.com/trusted-publishers
[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 -->