Release 0.14.0 report and upgrade guide

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

Release summary

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:

We still support the alert shortcode, but recommend the Markdown alert syntax for new content. For the new alert syntax and customization, see Alerts.

Styles and customization

This section covers breaking changes (marked ⚠️) and new features for the navbar, internal SCSS file reorganization and it’s impact on Swagger UI customization.

Highlights:

  • Light or dark navbar theme is now configurable site-wide or per page, defaulting to your site’s theme otherwise.
  • Navbar height is now adjustable via a single SCSS variable!
  • New variables and classes make it easier to customize the navbar look.
  • Navbar over cover images style fixes and translucency behavior improvements.
  • No more accidental SCSS file overrides! Internal SCSS files now live under the private td/ subdirectory.

Before 0.14.0, the navbar always used a dark theme and primary-colored background. The navbar’s light/dark color theme is now configurable site-wide and per page, defaulting to your site’s theme. The default navbar style matches your base site’s style for a consistent look and feel.1

Navbar height and styling are tunable via:

  • $td-navbar-min-height SCSS variable

  • CSS variables (experimental)- `--td-navbar-bg-color` - `--td-navbar-backdrop-filter` - `--td-navbar-border-bottom` - `--bs-bg-opacity` (used with `--td-navbar-bg-color` for background opacity) - `--bs-link-underline-opacity` (nav link underline)

Learn more about the default Navbar appearance and Customizing the navbar.

You may need to update your project in the following areas:

  • Navbar light/dark color theme: To restore the previous (always dark) behavior, set params.ui.navbar_theme to dark (details).

  • Height and variables: If you customize navbar height or styling, review and simplify your customizations by using the new variables and styles – see Customizing the navbar.

  • Navbar over cover: If your project targets navbar cover translucency classes, review and simplify your styles (navbar cover-image translucency):

    • .td-navbar-transparent (with .td-navbar-cover) replaces .navbar-bg-on-scroll
    • .navbar-bg-onscroll--fade removed

  • If your project overrides the navbar partial, review _nav.html for renamed classes and variables.

    Summary of edits to layouts/_partials/navbar.html
    BeforeAfter
    Cover translucency
    - `- `
    Light/dark theme
    - `data-bs-theme="dark"` always set on `- `data-bs-theme="dark"` only when `params.ui.navbar_theme` is `"dark"` - Otherwise follows site theme

    For details, see the previous bullets of this Action required section.

Improved separation of project and internal SCSS files

Docsy 0.14.0 moves all its internal SCSS files from assets/scss/ into the assets/scss/td/ subdirectory. This change clearly distinguishes project style files from internal theme files and helps projects avoid accidental overrides of Docsy’s 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 in assets/scss/ listed next, then 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, for example, assets/scss/_table.scss, add the following import to your _styles_project.scss file:

@import 'table';

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

Swagger UI style customization

Before 0.14.0, the User Guide incorrectly recommended overriding _swagger.scss to customize Swagger UI styles. Internal SCSS files are not meant to be overridden; the guide has been corrected. Because the override was documented, moving the file is considered a breaking change and so we are calling it out as such.

If your project has Swagger UI style customizations, follow the steps outlined in the previous section’s Action required.

blocks/cover shortcode changes

Using blocks/cover with markdown content? Call it with the Hugo’s shortcode Markdown call syntax: {{% %}}.

Implementation details

Before 0.14.0, the blocks/cover shortcode would check if the page file had a .md extension and apply markdownify to the shortcode’s inner content.

The shortcode now uses .Inner content directly, relying on Hugo’s native Markdown content processing based on the shortcode delimiter used.

This change is the final cleanup step removing pre-Hugo-0.54.x behavior (#939, #2480).

Hugo requirement and breaking changes

Docsy 0.14.0 officially supports Hugo 0.155.0 or later, up from 0.152.2 in Docsy 0.13.0. Hugo 0.153+ introduce breaking changes that may affect your site, as well as major new features such as the multidimensional content model provided through sites.matrix.

For all the details, see our companion post on Hugo 0.152.0 to 0.155.1. For a comprehensive list of issues and considerations when moving to Hugo 0.153+, see Hugo 0.153+ breaking changes & issues (#2431).

Other notable Docsy changes

Internationalization

Summary of changes:

  • Theme i18n converted from TOML to YAML; redundant other form entries removed in favor of default singular/plural syntax (#2447).
  • New locale: Hebrew.
  • Alert type labels added to multiple locales (#2390).

Action (optional): If your project has i18n files, you have an opportunity to clean up and reduce technical debt:

  • Remove redundant entries from your files where Docsy’s additions or updates already cover them.
  • Simplify your i18n files by dropping redundant other form entries (whether you convert to YAML or not).

Style improvements and fixes

Docsy 0.14.0 includes the following style improvements and fixes:

  • <details> margin fixes
  • TOC h1 entries are made slightly bolder to make them more visually distinct

Experimental extra styles:

  • Navbar link decoration for active and hover states
  • Nested-list margin fix for the last child.

For details, see Experimental extra styles.

Clarified public vs internal theme features

We added definitions to clarify Docsy’s public customization surface, internal/private features, and support limits, so expectations are clear about what’s supported and what changes require action:

Upgrade to 0.14.0

Some upgrade steps are the same for each Docsy release (for example, updating your Docsy NPM package or Hugo module). Those steps are described in Upgrade to Docsy 0.12.0: follow them, using version 0.14.0 where the guide refers to 0.12.0. For this release, use:2

After upgrading, ensure that you are aware of and have addressed breaking changes, and test your site thoroughly. Pay special attention to:

  • Build output: ensure that your site builds without errors, warnings, and deprecation notices
  • Styles and customization: ensure that your site’s look and feel is as expected
  • Aliases: Verify default-language redirects and that page aliases resolve to the correct language version. See Hugo 0.152.0 to 0.155.1 for alias-related changes in 0.153+

Also walk through the 0.12.0 Testing checklist.

What’s next?

For general work items tentatively planned for the next release, see Release 0.15.0 preparation (#2501).

References

About this release:

Other references:

  1. Before 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 February 1, 2026: Update 0.14 release notes, Hugo upgrade guide, style adjustments, and more (#2502) (2aef956)