Release 0.13.0 report and upgrade guide

Release summary

Docsy 0.13.0 comes with the following notable features and fixes:

• Navigation and UX improvements including the most upvoted enhancement request of 2025: Active TOC entry tracking (#349, #2289)
• Alert shortcode rewrite for better Markdown support
• Accessibility enhancements for better color contrast and dark mode support

Ready to upgrade?

• Review BREAKING changes:
  • Alert shortcode body content processing changes
  • Language menu visibility changes
• Optionally skim:
  • New features
  • Other notable changes
• When you’re ready, jump to Upgrade to 0.13.0.

Navigation and UX improvements

Active TOC entry tracking

Docsy 0.13.0 introduces active table of contents (TOC) entry tracking, the most upvoted enhancement request of 2025. This feature highlights the TOC entry corresponding to the page’s section that is currently in view. The feature is implemented using (a patched version of) Bootstrap’s ScrollSpy. The new default TOC labels “On this page” and “Top of page” are localizable. For details, see Active TOC entry tracking with ScrollSpy.

Section sidebar root

Docsy 0.13.0 introduces the sidebar_root_for configuration option, which allows you to scope sidebar navigation to specific sections. This is particularly useful for large sites where you want different navigation trees for different sections, and docs-only sites that also have non-docs sections.

To enable this feature, add sidebar_root_for to your page front matter. Supported parameter values are children and self. For details and examples, see the Section sidebar root documentation; for implementation details, see #2328 and PR #2364.

Language menu visibility

Prior to Docsy 0.13.0, the language selector menu was shown for multilingual sites in both the navbar and the sidebar, depending on the viewport width according to the following table:

The change in visibility was triggered by the Bootstrap lg breakpoint (the point where layouts switch between wide and narrow).

The new visibility under 0.13.0 is as follows for all viewport widths:

This is a BREAKING UX change. You can recover legacy behavior as follows:

• Navbar: add the following SCSS (or equivalent) to your project’s styles to restore the previous d-none d-lg-block behavior:

  .td-navbar__lang-menu {
    @extend .d-none;
    @extend .d-lg-block;
  }
  

• Sidebar: set the optional parameter .ui.sidebar_lang_menu to true in your site configuration.

To learn more about the language menu, see Adding a language menu. For implementation details, see #2035, #2001, and PR #2303.

Mobile navbar scroll indicators

The navbar now shows left/right scroll indicators when the navigation menu overflows (mainly for narrow viewports), making it easier for users to discover additional navigation items (#2406).

Alert shortcode improvements

As of Docsy 0.13.0, alert shortcode content is processed differently when called as Markdown ({{% alert %}}): the inner Markdown is now passed through to the page’s Markdown renderer and processed along with the rest of the page content. Previously, the shortcode used Hugo’s markdownify function internally.

This change means that your alerts can now:

• Contain calls to other shortcodes, that is, nested shortcode calls
• Contain and share link definitions from or with other parts of the page
• Be used in lists and other indented contexts
• Include headings that appear in the page TOC (for docs pages)

For details and examples, including important formatting requirements, see alert. For implementation details, see PR #941.

Accessibility improvements

• Color contrast has been improved throughout the theme, and Docsy now falls back to Bootstrap defaults for typography and color. This ensures better accessibility compliance out of the box. For details, see #2285 and Site colors.

• Color contrast improvements for dark mode:

  • TOC entry color contrast has been fixed when user preferences differ from system settings (#2379).

  • Early experimental support for customizable color-contrast adjustments for projects using Bootstrap’s theme variables (#2384). For details, see How to pick colors with good color-contrast. EXPERIMENTAL

• Dark mode:

  • Flash Of Unstyled Content (FOUC) has been fixed (#2332).
  • Google search results page now supports dark-mode (#2387). EXPERIMENTAL
  Dark mode quick reference

  To opt into all dark mode features (including experimental ones), add the following imports to your _styles_project.scss. For details, see Light/dark color modes.

  // Dark mode enhancements
  @import 'td/color-adjustments-dark';
  @import 'td/code-dark';
  @import 'td/gcs-search-dark';
  

Other notable changes

• Better NPM support: Projects using Docsy via NPM will no longer face optional and peer dependency issues (#2115).

• Translations (i18n): Occitan locale has been added (#2173), and Simplified Chinese (#2313) and Ukrainian (#2331) translation files have been refreshed.

• New _param shortcode: A new experimental shortcode for parameter substitution in templates, useful for dynamic content generation. See PR #2371 for details.

• Mathematical and chemical formulae: Docsy now uses Hugo’s embedded KaTeX engine for build-time rendering. The mhchem extension is now built-in. For details, see LaTeX support with KaTeX (#2276, #2394, #2395).

  The KaTeX engine auto-activates when formulae are encountered; no configuration needed, so projects can remove the following obsolete site configuration: params.katex.*. Subfields include enable, html_dom_element, options, and mhchem.

Upgrade to 0.13.0

Prerequisites

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

Upgrade procedure and AI help

Have you used AI to help you upgrade Docsy? It can be a big help!

The 0.12.0 upgrade guide was written with both human project maintainers and AI assistants in mind. In fact, I’ve successfully used it to upgrade projects like The Update Framework website. That is, using only the upgrade guide as input, an AI assistant created TUF PR #126 fully autonomously. All I had to do was review it.

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

• Docsy: 0.12.0 → 0.13.0
  Includes Bootstrap: 5.3.6 → 5.3.8
• Hugo: 0.147.5 → 0.152.2 ²
• Node: LTS 22 → LTS 24 ²

After upgrading, review the breaking changes and test your site thoroughly. For a testing checklist, see the Upgrade to Docsy 0.12.0 guide.

What’s next?

There are exciting enhancements planned for 2026³!

For general work items tentatively planned for the next release, or to track our progress, see Release 0.14.0 preparation (#2404). Some of the currently most upvoted enhancement requests include:

• Repository / page-meta link fixes and improvements (#1841), particularly for GitLab support (#375)
• Drop jQuery (#1436)

References

About this release:

• 0.13.0 changelog entry
• 0.13.0 release page
• Release 0.13.0 preparation issue (#2266)

Other references:

• 0.12.0 upgrade guide
• For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see the Hugo release notes.

• ←Previous
• Next→