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 default script versions, and renames the theme-dependencies install command.
By Patrice Chalin (CNCF), for the Docsy Steering Committee |
Tags:
Highlights

  • Dart Sass: Docsy moves off Hugo’s deprecated embedded LibSass (one new build prerequisite)
  • Semantic classes: Docsy chrome starts getting its own td- class names, beginning with breadcrumbs
  • Pinned script versions: Mermaid, KaTeX, markmap, and Redoc no longer resolve from the CDN’s latest

Release summary

Ready to upgrade?

Dart Sass replaces LibSass

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

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:

    npm install --save-dev sass-embedded

  • CI providers: GitHub Actions and Netlify are covered in the deployment docs (GitHub Pages, 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. Set DART_SASS_VERSION as an environment variable in your project settings, to an unprefixed version, 1.95.0 or later (for example, 1.102.0; snippet adapted from Hugo’s Cloudflare hosting guide):

    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.95.0 or later. The theme’s stylesheets rely on Sass’s new if() conditional syntax, which older releases can’t parse. 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 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

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. A 0.16-style rollback through theme-file overrides now fails to compile, and overriding head-css.html alone builds green but ships an unstyled site. For binary-less platforms, the durable path is Dart Sass’s planned pure-JS embedded mode.

Semantic classes: breadcrumbs

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.

Selector migration table

0.16 emitted0.17 emitted
ol.breadcrumbol.td-breadcrumbs__list
li.breadcrumb-itemli.td-breadcrumbs__item
li.breadcrumb-item.activeli.td-breadcrumbs__item[aria-current="page"]
nav.td-breadcrumbs__singlenav.td-breadcrumbs--single

Unchanged: the td-breadcrumbs class 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 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

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.

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). 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 breadcrumb class names.

  • Migrate all your selectors now, per the table above. 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 stops matching until renamed.

Install command renamed

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

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

    npm run install:theme-deps

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

Docsy now pins the default versions of its CDN-loaded script dependencies instead of loading whatever latest resolves to on the CDN, so rendering no longer changes when an upstream major ships. Pinned in this release:

  • Mermaid 11.16.1 (page-load script)
  • KaTeX 0.18.4 (build-time stylesheet and fonts, self-hosted)
  • markmap-autoloader 0.18.12 (page-load script)
  • Redoc 2.5.3 (page-load script for the redoc shortcode)

Actions

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

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.

Supply-chain hardening

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

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

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

Upgrade to 0.17.0

Follow Update Docsy and as you do:

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.

Sanity checks

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

  • Every environment that builds your site provides the sass CLI (sass --version); see Dart Sass actions.
  • If you diff built CSS, the changes are serialization-only; 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.
  • Mermaid diagrams render at the pinned version.

What’s next?

The semantic-class transition 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.

References

About this release:

  1. 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. ↩︎

Last modified August 24, 2026: Pin default Redoc version (#2738) (4f4716f)