Release 0.14.0 report and upgrade guide

By Patrice Chalin (CNCF), for the Docsy Steering Committee |
Tags:
Highlights

  • Enhanced internationalization support with updates to Bengali, Serbian, Chinese, and German translations.
  • Documentation improvements including Hugo Markdown-style alert support and reorganization.
  • Hugo 0.153+ upgrade with breaking changes — see upgrade guide for details.

Release summary

Docsy 0.14.0 comes with the following notable features and improvements:

  • Internationalization improvements for multiple locales
  • Documentation enhancements including Hugo Markdown-style alert support
  • Hugo upgrade to 0.154.5 with important breaking changes

Ready to upgrade?

Markdown alert syntax

Docsy 0.14.0 adds support for Hugo’s Markdown alert syntax that looks like this:

> [!NOTE] :star: Markdown alert syntax
>
> This syntax is more author, tooling, and AI friendly.

Which renders as:

While we continue to support the alert shortcode, we recommend using the Markdown alert syntax whenever possible. For details about the supported syntax, and how to customize the appearance of alerts, see Alerts.

Prior to 0.14.0, the navbar element always used a dark color theme, regardless of the site’s color theme or the active color mode. This restriction has been removed:

The default navbar style now matches the base page style, offering a clean and consistent look and feel.1

Learn more:

Action may be required to update your project in the following areas:

  • Navbar theme now follows the page theme (default light), instead of always forcing dark. Set params.ui.navbar_theme to dark to restore the old behavior. Details.

  • Review your project’s navbar style overrides. The new style design, SCSS and CSS variables may simplify your customization.

  • Review _nav.html if your project overrides it.

  • Internal navbar cover-image translucency class changes (update your custom styles targeting these classes if present):

    • .td-navbar-transparent replaces .navbar-bg-on-scroll (used with .td-navbar-cover)
    • .navbar-bg-onscroll--fade has been dropped: it was not used by Docsy, and the transition effect is now handled by .td-navbar-cover

Improved separation of project and internal SCSS files

Docsy 0.14.0 moves all internal SCSS files from assets/scss/ into the assets/scss/td/ subdirectory. This change distinguishes project customization files from internal theme files and prevents projects from inadvertently overriding internal SCSS files. For details on how to customize Docsy’s look and feel for your project, see Project styles that covers:

Action required

If your project has any of the files listed below in assets/scss/, you’re overriding Docsy’s internal SCSS files.

List of internal assets/scss/ files moved into the td/ subdirectory
assets/scss/
├── _alerts.scss
├── _blog.scss
├── _boxes.scss
├── _breadcrumb.scss
├── _code.scss
├── _colors.scss
├── _content.scss
├── _drawio.scss
├── _main-container.scss
├── _nav.scss
├── _navbar-mobile-scroll.scss
├── _pageinfo.scss
├── _search.scss
├── _sidebar-toc.scss
├── _sidebar-tree.scss
├── _swagger.scss
├── _table.scss
├── _taxonomy.scss
├── _variables_forward.scss
├── _variables.scss
├── blocks/_blocks.scss
├── blocks/_cover.scss
├── section-index.scss
├── shortcodes.scss
├── shortcodes/cards-pane.scss
├── shortcodes/tabbed-pane.scss
├── support/_bootstrap_vers_test.scss
├── support/_mixins.scss
├── support/_rtl.scss
└── support/_utilities.scss

To continue using your customizations from _abc.scss add the following import to your _styles_project.scss file:

@import 'abc';

Alternatively, you can copy the styles directly into your _styles_project.scss file.

For details about style customizations, see Project style files and Advanced style customization.

Swagger UI style customization

Prior to 0.14.0, the Docsy User Guide incorrectly recommended overriding _swagger.scss to customize Swagger UI styles. Docsy’s internal SCSS files are not intended to be overridden. The User Guide has been corrected, but since this was documented, moving the file constitutes a breaking change.

If your project has Swagger UI style customizations, follow the steps in Action required to continue using your customizations.

Hugo 0.153+ upgrade

Docsy 0.14.0 requires Hugo 0.154.5, upgraded from 0.152.2 in Docsy 0.13.0. This upgrade includes several breaking changes introduced in Hugo 0.153+ that may affect your site.

Breaking changes in Hugo 0.153+

Hugo 0.153+ introduces several breaking changes that you should be aware of:

  • macOS installations: Hugo installation on macOS needs to be handled differently as of 0.153.0. See issue #2429 for details.
  • Default language alias: Changes to default language alias behavior may cause refresh page issues. See gohugoio/hugo#14361 for details.
  • Page aliases: Page aliases may refer to the wrong language in some configurations. See issue #2433 for details.

New Hugo features

Hugo 0.154.4+ introduces new features that may be useful:

  • Canonical method: New canonical method available on page output formats. See Hugo documentation.
  • disableDefaultLanguageRedirect: Configuration option available since Hugo 0.140.0. See Hugo documentation.

Resources for Hugo upgrade

For a comprehensive list of issues and considerations when upgrading to Hugo 0.153+, see Hugo 0.153+ upgrade & issues (#2431). This issue tracks the various problems we’ve encountered (and that other projects might face) during the upgrade process.

Before upgrading, we strongly recommend:

  1. Review Hugo’s release notes for versions 0.153.0 through 0.154.5
  2. Test your site with Hugo 0.154.5 in a development environment
  3. Check for any custom Hugo configurations that might be affected
  4. Review the Hugo 0.153+ upgrade tracking issue for known issues and workarounds

Other notable changes

  • …

Internationalization improvements

This release includes significant improvements to internationalization support:

  • i18n file format migration: All translation files have been converted from TOML to YAML format for better maintainability and consistency
  • Bengali localization: Added feedback section and table of contents translations, fixed newline issues, added alert labels
  • Serbian translations: Updated both Cyrillic and Latin variants
  • Chinese translations: Updated Simplified and Traditional Chinese locales, added alert labels
  • German localization: Completed German translation support
  • Japanese translations: Converted to YAML format, added alert labels and all-rights-reserved translations
  • Hebrew translations: New locale added with alert and table of contents labels
  • Ukrainian translations: Converted to YAML format
  • Alert label translations: Added across multiple locales for consistent alert messaging

These updates improve the experience for users of Docsy sites in these languages and make the translation files easier to maintain.

Upgrade to 0.14.0

Prerequisites

We recommend that you Upgrade to Docsy 0.13.0 first because it contains significant breaking changes.

Upgrade procedure

To upgrade from 0.13.0 to 0.14.0, follow the same steps as described in Upgrade to Docsy 0.13.0 from 0.12.0, but use version 0.14.0 instead:

  • Docsy: 0.13.0 → 0.14.0
  • Hugo: 0.152.2 → 0.154.5 2
  • Node: LTS 24 (unchanged)

After upgrading, review the breaking changes and test your site thoroughly. Pay special attention to:

For a testing checklist, see the Upgrade to Docsy 0.13.0 guide.

What’s next?

For general work items tentatively planned for future releases, or to track our progress, see Release 0.14.0 preparation (#2404).

References

About this release:

Other references:

  1. Prior to 0.14.0, the navbar background was set to the primary color. ↩︎

  2. These are the officially supported Node.js and Hugo versions associated with the named Docsy versions. Later versions may work, but are not officially supported. ↩︎

Last modified January 26, 2026: Update 0.14.0 release notes and changelog details (bf7c497)