Release 0.17.0 report and upgrade guide

Release summary

• Modernized and strengthened foundations:
  • Dart Sass replaces LibSass
  • Font Awesome 7
  • Install command renamed
  • Default script-dependency versions pinned
• 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 LibSass
  • Breadcrumb semantic classes
  • Font Awesome 7
  • Install command renamed
• 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 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 has no plans to bundle Dart Sass; migrating now spares your site a forced move later.

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.

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

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

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.

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.

Font Awesome 7

Docsy’s icon library is upgraded from Font Awesome 6.7.2 to 7.3.1. Existing icon markup and icon: config values continue to resolve, with one Free-icon exception noted in the Actions: the fa-solid/fa-brands classes and their fas/fab shorthands still ship, and every icon the theme uses remains in the Free bundle.

What you will see: icons now render at a uniform width by default. Font Awesome 7 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 glyphs are redrawn. To restore natural width on a given icon, add fa-width-auto; the old fa-fw class is deprecated (it aliases fa-width-fixed, now the default). For the rationale and details, see What’s changed in v7.

Actions

Applies if you override the $td-font-awesome-font-name theme variable with a Font Awesome family name.

• Update it 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.

Applies if you set font-family for Font Awesome in your project’s CSS or Sass.

• Change it 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.

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: $fa-var-* references (alone or inside fa-content() calls) now fail to compile, since Font Awesome 7’s Sass is module-based; so do @includes of removed v6 mixins such as fa-icon-solid and fa-family-classic (see Font Awesome’s Sass upgrade notes). If you accept the same no-stability caveat as for internal styles, the namespaced form works for variables and functions: @use 'td/support/fa'; then fa.fa-content(fa.$var-NAME). Never @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.

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

Applies if you hotlink theme webfonts, or use Font Awesome’s screen-reader utility classes, layout helpers, or the vector-square icon.

• Webfonts are woff2-only in v7: the .ttf files that v6 also shipped are gone. Replace any non-woff2 hotlink under /webfonts/.
• 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.
• 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.

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.

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

Internationalization

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

• Mode menu: the light/dark mode menu labels join the theme’s translatable strings (ui_theme_light, ui_theme_dark, ui_theme_auto) and ship translated in every bundled locale; they were previously English-only.
• 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).

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

• ←Previous
• Next→