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.

Action (optional)

If your project uses the alert shortcode, consider migrating to Markdown alerts for consistency and better authoring/tooling support:

  • Use Markdown alert syntax for new content.
  • Where the output is equivalent, replace existing alert shortcodes with the Markdown syntax.
  • Keep alert shortcodes when you rely on shortcode-specific behavior.

Styles and customization

This section covers breaking changes (marked ⚠️) and new features for the navbar, internal SCSS file reorganization and its 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 now has improved styles and translucency behavior.
  • 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.

Heading aliases and in-page targets

Heading aliases are a useful convention for keeping old fragment links working. In 0.14.0, scrolling behavior is fixed (purely in CSS using scroll-padding-top), so heading alias targets and in-page targets now scroll to the right place. For details, see the Heading aliases and in-page targets and PR #2505 changes.

Action required

  • Rename td-offset-anchor to td-anchor-no-extra-offset. See Implementation notes. Applies if your site uses td-offset-anchor; for example, if you override blocks/lead.html, blocks/section.html, or layouts/community/list.html.

  • To ensure proper scrolling behavior for your project’s heading aliases and in-page targets, do the following:

    • Update heading aliases and in-page targets to be of the form <a id="..."></a>, if not already.
    • In particular, replace non-anchor targets such as <span> elements with <a id="..."></a> for more reliable scrolling.
    • Replace legacy targets like <a name="..."> with id-based targets.

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

Applies if your project customizes Swagger UI styles.

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

The blocks/cover shortcode now uses .Inner content directly, relying on Hugo’s native Markdown content processing instead of file extension testing (#939, #2480).

Actions: required and optional

  • Using blocks/cover with Markdown content? Call it with Hugo’s shortcode Markdown call syntax: {{% %}}, otherwise it might not render content correctly. Applies if you use blocks/cover in .html content files (Markdown in the body is not processed).
  • (Optional) If your navbar overlays the cover, add the td-below-navbar helper class to your blocks/cover calls to position the cover below the navbar. For details, see Below-navbar height adjustment.

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 made slightly bolder so they are 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 Extra styles.

Shortcodes

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

Upgrade steps

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

Sanity checks

After upgrading, review the following:

  • 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. See UI/UX spot-checks below.
  • 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 review the 0.12.0 Testing checklist.

Cross-checks

Ensure that you have addressed all breaking changes. For your convenience, here is a summary of the previously mentioned required and optional actions:

Required actions (as applicable)

Advanced overrides (optional)

If your project overrides Docsy templates or shortcodes, review these updated files and port changes as needed:

  • layouts/_shortcodes/blocks/lead.html
  • layouts/_shortcodes/blocks/section.html
  • layouts/community/list.html

Cleanup opportunities (optional)

If your project overrides Docsy styles (navbar, blocks, TOC, and more), review those overrides against the changes in this release. This often lets you remove custom CSS/SCSS and reduce technical debt.

Other cleanup opportunities not already covered in this section include:

UI/UX spot-checks (optional)

These quick checks relate to the style and behavior changes in 0.14.0.

  • Navbar theme, height, and cover translucency match your expectations.
  • Fragment links and in-page targets land below the fixed navbar (see Heading aliases and in-page targets).
  • <details> spacing in content pages.
  • TOC h1 weight/contrast in the right sidebar.
  • If you enable experimental extra styles, check nav link decoration and nested list spacing.

What’s next?

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

Goals and feedback

Our goal is for this post to help Docsy project maintainers upgrade to 0.14.0, with a focus on actionable items. Let us know how we can improve it by opening an issue or starting a discussion.

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 3, 2026: w (f6f2de5)