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.
Par 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 Mermaid: diagrams no longer float on 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.

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

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.

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. Each migrating release’s report will carry a selector table like the one below.

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

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

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.

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

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 Mermaid version pinned

Docsy now pins the default Mermaid 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

Applies if you want a different Mermaid version.

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, each with a selector table like this post’s. 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. ↩︎

Dernière modification August 19, 2026: Apply adversarial round 2 (gpt-5.6): accuracy and changelog scale (697c6c0)