# Release 0.17.0 report and upgrade guide

> Docsy now builds with Dart Sass, so the sass CLI joins your build. This release also debuts semantic classes in breadcrumbs, pins the default Mermaid version, 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 starts getting
  its own `td-` class names, beginning with breadcrumbs</span>
- <i class="fa-solid fa-thumbtack text-warning fa-lg"></i> <span>**[Pinned Mermaid](#mermaid)**:
  diagrams no longer float on 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)**: breadcrumbs debut Docsy's own `td-`
  chrome classes
- **Install and defaults**:
  - [Theme-dependencies install command renamed](#install-command)
  - [Default Mermaid version pinned](#mermaid): no longer 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 Mermaid version pinned](#mermaid)
  - [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.

<!-- TODO(hold, own-warnings PR): warnings-expected clause lands here: exact
  wording to come from the css-closeout lane once Docsy's own Sass
  function-class warnings are zeroed. When adding it:
  1. Attach the 1.74.0 floor's rationale to it (1.74.0 is the first release
     with the toCSS deprecation-silencing options that the clause's silencing
     override relies on); the floor is stated bare under Actions until then.
  2. Confirm the Actions bullet and the clause read coherently together. -->

### 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][]:

- **Local and npm-managed builds**: install the [`sass-embedded`][] package from
  your project root, per [Install Dart Sass][]:

  ```sh
  npm install --save-dev sass-embedded
  ```

- **CI providers**: GitHub Actions and Netlify are covered in the [deployment
  docs][] ([GitHub Pages][gh-pages-deploy], [Netlify][]); if your build runs
  through npm scripts, the `sass-embedded` dependency above is all you need.
- **Cloudflare Pages** (and other providers where the build doesn't run through
  npm scripts): install the standalone binary and add it to `PATH`. The snippet
  below covers Linux x64 builders such as Cloudflare Pages; on other platforms,
  substitute the matching [dart-sass release asset][dart-sass releases]. Set
  `DART_SASS_VERSION` as an environment variable in your project settings, to an
  unprefixed version, 1.74.0 or later (for example, `1.102.0`; snippet adapted
  from [Hugo's Cloudflare hosting guide][cf-hosting]):

  ```sh
  curl -fLJO https://github.com/sass/dart-sass/releases/download/$DART_SASS_VERSION/dart-sass-$DART_SASS_VERSION-linux-x64.tar.gz
  tar -xf dart-sass-$DART_SASS_VERSION-linux-x64.tar.gz
  export PATH=$PWD/dart-sass:$PATH
  ```

- **Self-provisioned compilers**: use Dart Sass **1.74.0 or later**. Current npm
  releases of `sass-embedded` are well past this floor; for the officially
  supported Dart Sass version, see the [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.

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

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

You can restore the LibSass pipeline for as long as your Hugo build still
bundles LibSass, by overriding **all three** of these theme files with their
0.16 versions:

1. `layouts/_partials/head-css.html`: a plain `toCSS` call.
2. `assets/scss/main.scss`: back to `@import 'td/main';`.
3. `assets/scss/td/_code-dark.scss`: back to its nested-`@import` form.

The three are an atomic set. In particular, overriding `head-css.html` alone
**builds green but ships an unstyled site**: LibSass passes the shipped entry
point's `@use` through as an unknown at-rule instead of failing.

This hatch is terminal: it dies when Hugo removes LibSass. 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, and breadcrumbs
go first. Each migrating release's report will carry a selector table like the
one below.

<!-- TODO(#2727): once merged, wire the user guide's consumer-contract section
  (/docs/content/lookandfeel/#semantic-classes; audience split: the
  contributor page /project/implementation/semantic-classes/ is for
  maintainer-facing links only) into this section, trimming what that section
  now owns:
  1. Intro: link "semantic classes"; drop the "Each migrating release's report
     will carry a selector table" sentence (the docs own the per-release
     selector-changes promise).
  2. SCSS bullet: replace the @extend mechanism and not-a-promise clauses with
     the link (both are docs-owned); the post keeps the action: migrate now.
  3. Table note: consider trimming the "so visual state and accessibility
     state can't drift apart" rationale (owned by the implementation page's
     State styling section).
  4. What's next: drop or re-point "each with a selector table like this
     post's" (the per-release selector-changes promise is docs-owned). -->

### Selector migration table

| 0.16 emitted                | 0.17 emitted                                   |
| --------------------------- | ---------------------------------------------- |
| `ol.breadcrumb`             | `ol.td-breadcrumbs__list`                      |
| `li.breadcrumb-item`        | `li.td-breadcrumbs__item`                      |
| `li.breadcrumb-item.active` | `li.td-breadcrumbs__item[aria-current="page"]` |

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

One related fix: breadcrumbs in taxonomy-term page summaries now render without
ARIA attributes (a page summary isn't the current page), and with the attribute
gone, its styling drops too, by design.

### 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 `.breadcrumb`, `.breadcrumb-item`, or
the breadcrumb `.active`.

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

**Applies if** your project's Sass styles the old Bootstrap class names.

- Your rules keep working for now: the theme binds the new classes to
  Bootstrap's styles, which incidentally rewrites `.breadcrumb`-family Sass
  rules to also match the `td-` classes. This keep-alive is an accident of the
  transition mechanism, **not a compatibility promise**: it ends when the
  Bootstrap binding retires. Migrate your Sass selectors now, with the rest.

## <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 Mermaid version pinned {#mermaid}

Docsy now pins the default [Mermaid][mermaid-docs] version (11.16.1 for this
release) instead of loading whatever `latest` resolves to on the CDN, so diagram
rendering no longer changes when an upstream major ships. The pin advances with
each theme release.

### Actions {#mermaid-actions}

**Applies if** you want a different Mermaid version.

- Set [`params.mermaid.version`][mermaid-docs] in your site config.

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

</section>

## What's next?

The semantic-class transition continues: more chrome partials will move to `td-`
classes in coming releases, each with a selector table like this post's. 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
[cf-hosting]: https://gohugo.io/host-and-deploy/host-on-cloudflare/
[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 releases]: https://github.com/sass/dart-sass/releases
[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
[mermaid-docs]: /docs/content/diagrams-and-formulae/#diagrams-with-mermaid
[Netlify]: /docs/deployment/netlify/
[official support policy]: /project/about/changelog/#official-support
[order of steps]: /docs/update/#update-order
[overrides]: /docs/update/#update-overrides
[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 -->