# Release 0.14.0 report and upgrade guide > [!INFO] Patch updates 0.14.1 to 0.14.3 > > For the key fixes of these patch updates, see [0.14.1][CL@0.14.1], > [0.14.2][CL@0.14.2], and [0.14.3][CL@0.14.3]. For other changes to 0.14.2, see > [Patch update 0.14.2](#0.14.2). If you are upgrading now, follow this guide > and use 0.14.3 where it references 0.14.0.
Highlights

- [**Styles and customization**](#styles-customization): navbar improvements, reorganized SCSS files - **Content and localization**: new Markdown [alert syntax](#alerts) and [internationalization](#other-notable-changes) improvements - **[Hugo 0.155.0 requirement](#hugo)**, and 0.153+ breaking and notable changes

## Release summary - **[Styles and customization](#styles-customization)**: - [Navbar improvements](#navbar), including configurable light/dark theme and adjustable height - [Heading aliases and in-page targets](#heading-aliases) - [Reorganized internal SCSS files](#improved-scss-soc) > [!NB] :warning: If you [customize **Swagger UI**][], this impacts you! - **Content and shortcodes**: - New Markdown [alert syntax](#alerts) - [`blocks/cover`](#blocks-cover) shortcode changes - New [shortcode](#shortcodes) for Netlify build info - [Internationalization](#other-notable-changes) updates - **[Hugo 0.155.0 or later](#hugo)** required; discussion of breaking changes and new features such as [sites.matrix][] - **[Public vs internal features](#clarified-public-vs-internal-theme-features)**: added definitions for customization surface, private/internal, and support limits [customize **Swagger UI**]: #swagger-scss [sites.matrix]: https://gohugo.io/quick-reference/glossary/#sites-matrix ## Ready to upgrade? {#ready-to-upgrade} - Review BREAKING changes: - [Styles and customization](#styles-customization) - [Heading aliases and in-page targets](#heading-aliases) - [blocks/cover shortcode](#blocks-cover) content processing - [Hugo 0.155.0 requirement and 0.153+ breaking changes](#hugo) - (style-only) [Docsy 0.14.2 code-style update](#0.14.2) for light/dark mode - Optionally skim: - New features (look for the green checkmark icon) - Cleanup / improvement opportunities (look for this icon) - [Other notable changes](#other-notable-changes) - Jump to [Upgrade to 0.14.0](#upgrade) once you are ready ## Markdown alert syntax {#alerts} Docsy 0.14.0 adds support for Hugo's Markdown alert syntax that looks like this: ```markdown > [!NOTE] :star: Markdown alert syntax > > This syntax is more author, tooling, and AI friendly. ``` Which renders as: > [!NOTE] :star: Markdown alert syntax > > This syntax is more author, tooling, and AI friendly. 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) {#alerts-actions} **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. > [!TIP] > > Using a script like [docsy-alerts-to-md/convert.pl][] can help with the > conversion process. [alert shortcode]: /docs/content/shortcodes/#alert [Alerts]: /docs/content/adding-content/#alerts [docsy-alerts-to-md/convert.pl]: https://github.com/open-telemetry/opentelemetry.io/blob/main/scripts/docsy-alerts-to-md/convert.pl ## Styles and customization {#styles-customization} This section covers breaking changes (marked :warning:) and new features for the navbar, [internal] SCSS file reorganization and its impact on Swagger UI customization. [internal]: /project/about/changelog/#private ### Navbar style improvements {#navbar} **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-bg-color] 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][]. [^navbar-bg-color]: Before 0.14.0, the navbar background was set to the primary color. #### Actions: required and optional {#navbar-actions} 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-lightdark-theme]). - **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.
[_nav.html]: https://github.com/google/docsy/blob/main/layouts/_partials/navbar.html [Customizing the navbar]: /docs/content/lookandfeel/#navbar-customization [Light/dark color theme]: /docs/content/lookandfeel/#navbar-lightdark-theme [navbar]: /docs/content/lookandfeel/#navbar [navbar-lightdark-theme]: /docs/content/lookandfeel/#navbar-lightdark-theme [navbar cover-image translucency]: /docs/content/lookandfeel/#customize-over-cover ### Heading aliases and in-page targets {#heading-aliases} 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][heading-aliases+] and PR [#2505] changes. [#2505]: https://github.com/google/docsy/pull/2505/changes #### Actions: required and optional {#heading-aliases-actions} - **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][heading-aliases-impl-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 [``][heading-aliases+], if not already. - In particular, replace non-anchor targets such as `` elements with `` for more reliable scrolling. - Replace legacy targets like `` with `id`-based targets. [fragment]: https://gohugo.io/quick-reference/glossary/#fragment [heading-aliases+]: /docs/content/navigation/#heading-aliases [heading-aliases-impl-notes]: /docs/content/navigation/#heading-aliases-implementation-notes ### Improved separation of project and internal SCSS files {#improved-scss-soc} 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 {#scss-actions} **Applies if** your project has any of the files in `assets/scss/` listed next, because you are overriding Docsy's internal SCSS files.[^scss-action-note] [^scss-action-note]: Except for [Swagger UI style customization](#swagger-scss), this is not a breaking change since it only affects internal files.
List of internal assets/scss/ files moved into the td/ subdirectory ```text 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: ```scss @import 'table'; ``` Alternatively, you can copy the styles directly into `_styles_project.scss`. #### Swagger UI style customization {#swagger-scss} **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](#scss-actions). [breaking change]: /project/about/changelog/#breaking-change [Swagger UI]: /docs/content/shortcodes/#swaggerui ## blocks/cover shortcode changes {#blocks-cover} 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 {#blocks-cover-actions} - **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.[^below-navbar-default] 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][]. [^below-navbar-default]: We expect `td-below-navbar` to be the best design option for most projects, and it may become the default in a future release. [below-navbar height adjustment]: /docs/content/shortcodes/#td-below-navbar [blocks/cover]: /docs/content/shortcodes/#blocks-cover [Markdown call syntax]: https://gohugo.io/content-management/shortcodes/#notation ## Hugo requirement and breaking changes {#hugo} Docsy 0.14.0 [officially supports][] **Hugo 0.155.0 or later**, up from 0.152.2 in [Docsy 0.13.0][Upgrade to 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][hugo-0.152.0+]. For a comprehensive list of issues and considerations when moving to Hugo 0.153+, see [Hugo 0.153+ breaking changes & issues (#2431)][#2431]. ## / Patch update 0.14.2 {#0.14.2} Docsy 0.14.2 adds the following changes: - For sites using `td/code-dark`, default code styles changed from `tango`/`onedark` to `friendly`/`native` ([#2548]). - Console block selection and copy-code now include commands only, not output ([#2548]). For details, see [Selecting console block content][]. - Search form now includes a `name` attribute for better semantics and autofill behavior ([#2549]). ### Actions: required and optional {#0.14.2-actions} - **Applies if** you use `td/code-dark` and you want to revert to the `tango`/`onedark` styles. Follow the steps in [Light/dark code styles and more][]. - Verify that copy-code behavior in console examples (commands only) matches your expectations. To use the old behavior, see [Selecting console block content][]. [Light/dark code styles and more]: /docs/content/lookandfeel/#lightdark-code-styles [Selecting console block content]: /docs/content/lookandfeel/#selecting-console-block-content ## Other notable Docsy changes {#other-notable-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]) - `
` 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][]. [Extra styles]: /docs/content/lookandfeel/#extra-styles ### Shortcodes - New [experimental] `td/site-build-info/netlify` shortcode for Netlify build info. See an [example](/project/#site-build-information). ### Clarified public vs internal theme features Docsy 0.14.0 adds [definitions](/project/about/changelog/#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](/project/about/changelog/#public) - [Private/internal features](/project/about/changelog/#private) - [Experimental features][experimental] - [Breaking change](/project/about/changelog/#breaking-change) - [Official support limits](/project/about/changelog/#official-support) ## Upgrade to 0.14.0 {#upgrade} > [!NB] First [upgrade to Docsy 0.13.0][] if you haven't already. ### 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.3** where the guide refers to 0.12.0. For this release, use:[^vers-note] - **Docsy**: [0.13.0] → [0.14.3] - **Hugo**: 0.152.2 → 0.155.0 or later, see [Hugo 0.152.0-0.155.x upgrade guide][hugo-0.152.0+] - **Node**: LTS 24 (unchanged) [^vers-note]: 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.
Checks
### Sanity checks After upgrading, review the following: - [ ] **Build output**: ensure that your site builds without errors, warnings, and deprecation notices. - [ ] **[Styles and customization](#styles-customization)**: ensure that your site's look and feel is as expected. See [UI/UX spot-checks](#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-0.155.x upgrade guide][hugo-0.152.0+] 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](#breaking-changes). For your convenience, we link to required and optional actions for each section. #### Required actions (as applicable) {#required-actions} - [ ] [Navbar required actions](#navbar-actions) - [ ] [`blocks/cover` required actions](#blocks-cover-actions) - [ ] [Internal SCSS required actions](#scss-actions), including [Swagger UI](#swagger-scss) - [ ] [Heading aliases and in-page targets required actions](#heading-aliases-actions) #### Cleanup and site improvements (optional) {#cleanup-opportunities} 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][]. - [ ] Switch to [Markdown alert syntax](#alerts-actions) - [ ] Review [navbar theme and styling](#navbar-actions), and drop any navbar overrides you added only to force a dark theme - [ ] Adjust [`blocks/cover` position](#blocks-cover-actions) relative to the navbar - [ ] Remove redundant [i18n entries](#internationalization) #### UI/UX spot-checks (optional) {#ui-ux-spot-checks} 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](#heading-aliases)). - [ ] `
` spacing in content pages. - [ ] TOC h1 weight/contrast in the right sidebar. - [ ] If you use `td/code-dark`, code block styles in light and dark mode match your expectations. - [ ] Console copy-code behavior copies commands (not output) where intended. - [ ] If you enable experimental extra styles, check nav link decoration and nested list spacing. #### Advanced review {#advanced-overrides} **Applies if** your project overrides Docsy templates, shortcodes, assets, or i18n files. Review these updated files and port changes as needed: - [ ] [assets/js/base.js][] - [ ] [assets/scss files](#scss-actions) - [ ] [i18n files](#internationalization) - [ ] [layouts/\_markup/render-blockquote-alert.html][render-blockquote-alert.html] - [ ] [layouts/\_partials/navbar.html](#navbar-actions) - [ ] [layouts/\_partials/sidebar-tree.html][sidebar-tree.html] - [ ] [layouts/\_partials/sidebar.html][sidebar.html] - [ ] [layouts/\_shortcodes/blocks/cover.html][blocks/cover.html] - [ ] [layouts/\_shortcodes/blocks/lead.html][blocks/lead.html] - [ ] [layouts/\_shortcodes/blocks/section.html][blocks/section.html] - [ ] [layouts/\_shortcodes/pageinfo.html][pageinfo.html] - [ ] [layouts/\_shortcodes/td/site-build-info/netlify.md][site-build-info-netlify.md] - [ ] [layouts/blog/baseof.html][blog/baseof.html] - [ ] [layouts/community/list.html][community/list.html] - [ ] [layouts/docs/baseof.html][docs/baseof.html] - [ ] [layouts/swagger/baseof.html][swagger/baseof.html] [assets/js/base.js]: [render-blockquote-alert.html]: [sidebar.html]: [sidebar-tree.html]: [blocks/cover.html]: [blocks/lead.html]: [blocks/section.html]: [pageinfo.html]: [site-build-info-netlify.md]: [blog/baseof.html]: [community/list.html]: [docs/baseof.html]: [swagger/baseof.html]:
## What's next? For general work items _tentatively_ planned for the next release, see [Release 0.15.0 preparation (#2501)][#2501]. > [!INFO]- Your opinion counts! > > - If you'd like a feature or fix to be > considered for inclusion in an upcoming release, **upvote** (with a thumbs up) > the associated issue or PR. > > - If you find Docsy useful, consider [starring > the repository][star-the-repo] to show your support. {._list-unstyled} [star-the-repo]: https://github.com/google/docsy [#2404]: https://github.com/google/docsy/issues/2404 ## 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]. [issue]: https://github.com/google/docsy/issues [discussion]: https://github.com/google/docsy/discussions ## References About this release: - Changelog entries from [0.14.0][CL@0.14.0] to [0.14.3][CL@0.14.3] - Release pages for [0.14.3][], [0.14.2][], [0.14.1][], and [0.14.0][] - [Release 0.14.0 preparation **issue** (#2404)][#2404] Other references: - Companion [Hugo 0.152.0-0.155.x upgrade guide][hugo-0.152.0+] - [0.13.0 upgrade guide](/blog/2025/0.13.0/) - [Hugo release notes](https://github.com/gohugoio/hugo/releases) [#2390]: https://github.com/google/docsy/issues/2390 [#2413]: https://github.com/google/docsy/issues/2413 [#2431]: https://github.com/google/docsy/issues/2431 [#2447]: https://github.com/google/docsy/pull/2447 [#2477]: https://github.com/google/docsy/pull/2477 [#2480]: https://github.com/google/docsy/pull/2480 [#2501]: https://github.com/google/docsy/issues/2501 [#2524]: https://github.com/google/docsy/pull/2524 [#2533]: https://github.com/google/docsy/pull/2533 [#2548]: https://github.com/google/docsy/pull/2548 [#2549]: https://github.com/google/docsy/pull/2549 [#939]: https://github.com/google/docsy/issues/939 [0.13.0]: /project/about/changelog/#v0.13.0 [0.14.0]: https://github.com/google/docsy/releases/v0.14.0 [0.14.1]: https://github.com/google/docsy/releases/v0.14.1 [0.14.2]: https://github.com/google/docsy/releases/v0.14.2 [0.14.3]: https://github.com/google/docsy/releases/v0.14.3 [Advanced style customization]: /docs/content/lookandfeel/#advanced-style-customization [CL@0.14.0]: /project/about/changelog/#v0.14.0 [CL@0.14.1]: /project/about/changelog/#v0.14.1 [CL@0.14.2]: /project/about/changelog/#v0.14.2 [CL@0.14.3]: /project/about/changelog/#v0.14.3 [experimental]: /project/about/changelog/#experimental [hugo-0.152.0+]: /blog/2026/hugo-0.152.0+/ [officially supports]: /project/about/changelog/#official-support [Project style files]: /docs/content/lookandfeel/#project-style-files [Project styles]: /docs/content/lookandfeel/#project-styles [technical debt]: https://martinfowler.com/bliki/TechnicalDebt.html [Testing checklist]: /blog/2025/0.12.0/#testing-checklist [Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/ [Upgrade to Docsy 0.13.0]: /blog/2025/0.13.0/