Release 0.17.0 report and upgrade guide

Release summary

• Modernized and strengthened foundations:
  • Dart Sass replaces deprecated LibSass
  • Font Awesome 7
  • Default script-dependency versions pinned
  • Install command renamed
• Semantic classes: starting with breadcrumbs
• Internationalization:
  • Mode-menu labels localized
  • Full translation-key coverage
  • Turkish and Ukrainian locale refreshes
• Agent directive in page HTML (experimental)
• Other notable changes: footer-copyright fix, Docker-quickstart retirement
• For maintainers: supply-chain hardening, npm trusted publishing

Ready to upgrade?

• ⚠️ Respect the order of steps to avoid breaking your build.
• Review BREAKING changes:
  • Dart Sass replaces deprecated LibSass
  • Font Awesome 7
  • Install command renamed
  • Breadcrumb semantic classes
• Optionally skim:
  • Default script-dependency versions pinned
  • / Internationalization
  • Experimental agent directive in page HTML
  • Other notable changes, and for maintainers
• Jump to Upgrade to 0.17.0 yourself, or ask an AI agent.

Dart Sass replaces deprecated LibSass

Docsy’s stylesheets are now transpiled with Dart Sass, the actively developed Sass implementation, instead of Hugo’s embedded LibSass.

The wins, for theme and project styles alike:

• Modern Sass: Dart Sass tracks the evolving Sass language; LibSass stopped moving years ago. The theme’s stylesheets already use Sass modules and newer syntax, and your own project Sass can follow at its own pace.
• Ahead of Hugo’s removal: LibSass removal is coming to Hugo (deprecated in 0.153.0), and Hugo’s standard binaries won’t bundle Dart Sass.

What this means for your build:

• One new prerequisite: the sass CLI must be available on your build’s PATH.
• Silenced deprecation warnings: Dart Sass warns about deprecated Sass constructs that the theme and its dependencies, vendored Bootstrap included, haven’t fully moved off yet, so the theme silences warnings from its dependencies. The silencing also covers your own project style files (though not a custom main.scss entry point, whose warnings stay visible), so a quiet log is not evidence that your own Sass is deprecation-free.

Expected CSS changes

Dart Sass serializes some Sass-computed colors differently than LibSass did. For example:

- --bs-primary-bg-subtle: #cfe2ff;
+ --bs-primary-bg-subtle: rgb(81.0196078431%, 88.6274509804%, 99.8431372549%);

Both forms specify the same color, up to a rounding difference of less than one 8-bit step per channel. If you diff built CSS, expect this serialization churn throughout, alongside Font Awesome 7’s stylesheet changes: it is normal, not drift. Comparison tooling (bit-exact visual tests, snapshots of built CSS) needs its expectations re-captured, and code that string-matches these serialized values needs the same update.

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, 1.102.0. CI builds that run through npm scripts need nothing more; GitHub Pages and Netlify setups are covered in the deployment docs (GitHub Pages, Netlify). For the @parcel/watcher entry this adds to your lockfile, see the install note.
  • 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.

Applies if your custom Chroma style sheets (assets/scss/td/chroma/_light.scss and _dark.scss) reference theme or Bootstrap variables such as $primary.

• Inline those color values: custom Chroma files now load as isolated Sass modules, so such references fail with “Undefined variable”.

Font Awesome 7

Docsy’s icon library is upgraded from Font Awesome v6 to v7 (7.3.1). What this brings:

• A current icon set: new icons included.
• Modern accessibility defaults: icons are hidden from assistive technology unless labeled; see the Actions.
• Continuity: existing icon markup and icon: config values continue to resolve. The fa-solid/fa-brands classes and their fas/fab shorthands still ship, and every icon the theme uses remains in the Free bundle (one Free-icon exception in the Actions).
• Uniform icon width, by default: v7 draws every icon on a fixed-width canvas with the glyph centered, where v6 hugged each glyph’s natural width. Icons in navbars, footers, and icon+label lists gain a little horizontal whitespace, and some glyphs look different. For the rationale and details, see What’s changed in v7.

Actions

Applies if the new fixed-width default changes spacing that your site wants to keep.

• Add fa-width-auto to icons that should keep their natural width. The old fa-fw class is deprecated: it aliases fa-width-fixed, now the default.

Applies if you explicitly configure or load Font Awesome fonts: through the $td-font-awesome-font-name theme variable, a font-family in your project’s CSS or Sass, or a hotlink to the theme’s webfonts.

• Update a $td-font-awesome-font-name override to the v7 form of your family, for example 'Font Awesome 7 Free' (the new theme default). An override naming a custom, non-Font-Awesome font needs no change. The variable feeds only Docsy’s icon pseudo-elements, as before.
• Change a hardcoded font-family to the matching v7 family, 'Font Awesome 7 Free' or 'Font Awesome 7 Brands': v7 registers no v6-named @font-face, so a hardcoded v6 family silently falls through to another font.
• Webfonts are woff2-only in v7: the .ttf files that v6 also shipped are gone. Replace any non-woff2 hotlink under /webfonts/.

Applies if your project’s Sass reaches into Font Awesome’s Sass surface: variables such as $fa-var-* or functions like fa-content(). This surface was never part of Docsy’s documented customization API, but until now it was reachable through leaked imports, in two modes:

• Loud: two kinds of references now fail to compile, since Font Awesome 7’s Sass is module-based (see Font Awesome’s Sass upgrade notes): $fa-var-* variables, alone or inside fa-content() calls, and @includes of removed v6 mixins such as fa-icon-solid and fa-family-classic. For variables and functions, the namespaced form works: @use 'td/support/fa'; then fa.fa-content(fa.$var-NAME).
  • Alias variable names from v5/v6 (such as $var-external-link-alt) remain defined in v7, so namespacing is usually the only change variables need.
  • Don’t @use … as *: Font Awesome’s unprefixed variables collide with Bootstrap’s.
• Silent: two cases compile green but stop doing what they used to:
  • Font Awesome configuration globals set in your project Sass ($fa-font-path, $fa-font-display, and similar) no longer have any effect: the module loads with its defaults, so a green build is no evidence these settings still work. Check your rendered site, especially if you self-host webfonts via $fa-font-path: icons must render and their font requests must load. There is no override hook in this release; restoring one is tracked in #2756.
  • Bare fa-content() calls with a literal argument (no $fa-var-*) pass through as literal CSS: the content value ships as text, not a glyph.

Applies if any of your site’s icons carry meaning on their own (icon-only links or buttons, or inline icons conveying information that nearby text doesn’t repeat), or your site uses Font Awesome’s screen-reader utility classes.

• Font Awesome 7 hides webfont icons from assistive technology by default (the glyph now ships with empty CSS alternative text), per Font Awesome’s accessibility guidance. Decorative icons need nothing.
  • For an icon-only link or button, put the label on the interactive element (for example, with aria-label), not on the icon.
  • For a semantic inline icon, add aria-label and role="img" to the icon itself.
• The .sr-only, .sr-only-focusable, .fa-sr-only, and .fa-sr-only-focusable utility classes are gone from the theme’s compiled CSS: use Bootstrap’s .visually-hidden and .visually-hidden-focusable instead.

Applies if your site uses Font Awesome layout helpers or the vector-square icon.

• Layout helpers fa-pull-* and fa-ul/fa-li now position via CSS logical properties, following text direction: recheck right-to-left pages and remove any RTL compensation CSS that now double-corrects.
• Font Awesome 7 Free drops the vector-square icon (its v7 successor, draw-square, is Pro-only): a custom icon: value or content icon naming it now renders blank. Pick a different Free icon.

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

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
  

• Update every automation that invokes the old command: package scripts (such as the setup guide’s _prepare:docsy example), CI workflows, and deployment commands.

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 from node_modules/docsy/ after every clean install or update (wire it into your setup steps, since a fresh npm ci discards the result), or switch to the @docsy/theme registry package, which needs no install step.

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

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. The win: your customizations key on names Docsy owns and documents, a stable contract that survives Bootstrap upgrades.

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

Internationalization

The theme’s UI strings got a translation-coverage pass:

• Mode menu (the light/dark mode menu):
  • Its labels and the toggle button’s assistive text, previously English-only, join the theme’s translatable strings (the ui_theme_* keys) and ship translated in every bundled locale.
  • The button’s accessible name now also tracks the selected mode; it was stuck at its page-load value.
• Complete coverage: each of the theme’s 31 bundled locales now defines the theme’s full translation-key set, so none of them falls back to English.
• Locale refreshes: Turkish and Ukrainian translations updated and extended.

Applies if your project’s i18n files override theme UI strings.

• Optionally, drop redundant copies of theme strings, keeping intentional project-specific wording: your values override the theme’s, so stale copies silently pin yesterday’s wording.

Agent directive in page HTML

Sites that enable llms.txt now also point AI agents to it from their page HTML: a new theme partial, called from the theme’s baseof templates, opens each page body with a hidden agent-facing directive. For what the directive carries and how agents find it, see Discovery. This feature is experimental, part of the agent-support arc tracked in #2614.

Sites that don’t enable llms.txt are unaffected: the partial emits nothing.

Actions

⚠️ Applies if your site enables llms.txt and overrides any of the theme’s baseof templates (print variants included): without the call below, the directive silently never renders on pages that use those overrides.

• Call the new partial from each overridden template, as the first element of <body>, passing it the page context:

  {{ partial "llms-directive.html" . -}}
  

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.
• Outdated Docker setup retired: the repo’s broken Docker configuration files are removed and the Docker quickstart page is retired.

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 the run scripts’ implicit pre/post hooks are gone (inlined into their parent scripts; the pack-time lifecycle hooks remain), with the full test suite renamed to test:full. Consuming sites benefit indirectly: the theme you depend on is harder to compromise. 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, breadcrumb.html, and the baseof templates (see the agent directive).

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→