Release 0.14.0 report and upgrade guide

Release summary

• Styles and customization:
  • Navbar improvements, including configurable light/dark theme and adjustable height
  • Heading aliases and in-page targets
  • Reorganized internal SCSS files

    ⚠️ If you customize Swagger UI, this impacts you!

• Content and shortcodes:
  • New Markdown alert syntax
  • blocks/cover shortcode changes
  • New shortcode for Netlify build info
  • Internationalization updates
• Hugo 0.155.0 or later required; discussion of breaking changes and new features such as sites.matrix
• Public vs internal features: added definitions for customization surface, private/internal, and support limits

Ready to upgrade?

• Review BREAKING changes:
  • Styles and customization
  • Heading aliases and in-page targets
  • blocks/cover shortcode content processing
  • Hugo 0.155.0 requirement and 0.153+ breaking changes
• Optionally skim:
  • New features (look for the green checkmark icon)
  • Cleanup / improvement opportunities (look for this icon)
  • Other notable changes
• Jump to Upgrade to 0.14.0 once you’re ready

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.

Actions (optional)

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

Navbar style improvements

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

Navbar height and styling are tunable via (EXPERIMENTAL):

• SCSS variables:

  • $td-navbar-min-height
  • $td-navbar__main-min-height-mobile
• CSS variables

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

Actions: required and optional

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

• / Navbar light/dark color theme: the always-dark navbar was an early Docsy constraint and isn’t a fit for all sites. You can now choose the theme that best matches your project’s overall design.

  • If your design does not require a dark navbar, you may be able to drop any overrides you added just to force that theme.
  • If your design does require a dark navbar, set params.ui.navbar_theme to dark to restore the previous behavior (details).

• Navbar over cover: applies if your project targets navbar cover translucency classes.

  • Review and simplify your styles (navbar cover-image translucency).
  • Replace .navbar-bg-on-scroll and .navbar-bg-onscroll--fade with .td-navbar-transparent (used alongside .td-navbar-cover).

• Height and variables: applies if you customize navbar height or styling. Review and simplify your customizations using the new variables and styles — see Customizing the navbar.

• Navbar partial overrides: applies if your project overrides the navbar partial. Review _nav.html for changes.

  Summary of edits to layouts/_partials/navbar.html

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

Actions: required and optional

• Applies if your site uses td-offset-anchor; for example, if you override blocks/lead.html, blocks/section.html, or layouts/community/list.html.

  Rename td-offset-anchor to td-anchor-no-extra-offset. See Implementation notes.

• Scrolling behavior: applies if you want to ensure proper scrolling behavior for your project’s existing heading aliases and in-page targets.

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

• The project style files that are supported for project-specific SCSS customization
• Advanced style customization for projects that occasionally need to deviate substantially from Docsy’s base styles

Actions: required and optional

Applies if your project has any of the files in assets/scss/ listed next, because you are overriding Docsy’s internal SCSS files.²

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

Two changes to blocks/cover, the first of which is a breaking change:

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

2. New td-below-navbar helper class lets you position the cover below the fixed navbar on desktop, instead of behind it.

Actions: required and optional

• Applies if you use blocks/cover in .html content files with Markdown in the body.

  Use Hugo’s shortcode Markdown call syntax: {{% %}}. Otherwise, Markdown content might not render correctly.

• Recommended for most projects.³ If you want to position your blocks/cover below the navbar (instead of behind it), add the td-below-navbar helper class to your blocks/cover call. For example: height="auto td-below-navbar". 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-0.155.x upgrade guide. 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): applies 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:

• Navbar color contrast fixes (#2413, #2477)
• <details> margin fixes
• TOC h1 entries made slightly bolder so they are more visually distinct
• Google-search modal support for dark mode (#2524)
• RTL: code blocks and foldable-nav icons (#2533)

Experimental extra styles:

• CTA buttons group style: use the td-cta-buttons class
• Navbar link decoration for active and hover states
• Nested-list margin fix for the last child
• No-left-sidebar layout: use the td-no-left-sidebar class
• Navbar helper class td-navbar-links-all-active for homepage

For details, see Extra styles.

Shortcodes

• New experimental td/site-build-info/netlify shortcode for Netlify build info. See an example.

Clarified public vs internal theme features

Docsy 0.14.0 adds 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:

• Public customization surface
• Private/internal features
• Experimental features
• Breaking change
• Official support limits

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:⁴

• Docsy: 0.13.0 → 0.14.0
• Hugo: 0.152.2 → 0.155.0 or later, see Hugo 0.152.0-0.155.x upgrade guide
• Node: LTS 24 (unchanged)

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:

• 0.14.0 changelog entry
• 0.14.0 release page
• Release 0.14.0 preparation issue (#2404)

Other references:

• Companion Hugo 0.152.0-0.155.x upgrade guide
• 0.13.0 upgrade guide
• Hugo release notes

• ←Previous
• Next→