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)
• 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 TOC entry tracking, the most upvoted enhancement request of 2025. This feature highlights the TOC entry for the section heading that is currently in view. The current implementation uses Bootstrap (a patched version of) ScrollSpy. 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 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 CSS to your project’s styles:

  .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 PR #2303.

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.
• Dark mode:
  • Flash Of Unstyled Content (FOUC) has been fixed (#2332).
  • Google search results page now supports dark-mode (#2387). EXPERIMENTAL
• 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. For details, see How to pick colors with good color-contrast. EXPERIMENTAL

Other notable changes

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

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

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.

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→