Release 0.17.0 report and upgrade guide

Release summary

• Dart Sass replaces LibSass: the sass CLI becomes a build prerequisite
• Semantic classes: breadcrumb markup moves from Bootstrap to td- classes
• Install and defaults:
  • Theme-dependencies install command renamed
  • Default script-dependency versions pinned: Mermaid, KaTeX, markmap, and Redoc no longer resolve from the CDN’s latest
• Other notable changes, and for maintainers: supply-chain hardening and npm trusted publishing

Ready to upgrade?

• ⚠️ Respect the order of steps to avoid breaking your build.
• Review BREAKING changes:
  • Dart Sass replaces LibSass
  • Breadcrumb semantic classes
  • Install command renamed
• No Hugo change this release: the version list is otherwise unchanged too.
• Optionally skim:
  • Default script-dependency versions pinned
  • Other notable changes, and for maintainers
• Jump to Upgrade to 0.17.0 yourself, or ask an AI agent.

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:

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

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

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. In this release: breadcrumbs.

Selector migration table

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

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.

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 (see the table) instead of loading whatever latest resolves to on the CDN, so rendering no longer changes when an upstream major ships.

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.

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:

• ⚠️ 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.
• Use these versions:¹
  • Docsy: 0.16.0 -> 0.17.0
  • Hugo: 0.164.0 (unchanged; theme minimum 0.160.1)
  • Node: LTS 24 (unchanged)
  • Dart Sass: new requirement
• Remember to review your theme overrides: this release reworks theme files that sites commonly override, including head-css.html and breadcrumb.html.

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.

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:

• Changelog entry for 0.17.0
• Release page for 0.17.0
• Release 0.17.0 preparation issue (#2691)
• Git history since 0.16.0

• ←Précédent
• Suivant→