Blog on Docsy

Release 0.14.0 report and upgrade guide

Tue, 10 Feb 2026 00:00:00 +0000

Patch update: 0.14.1

Docsy 0.14.1 is a patch release with one fix: Fixed ToC sidebar width in xl viewports (#2538). If you are upgrading now, follow this guide and use 0.14.1 where it references 0.14.0.

Highlights

Styles and customization: navbar improvements, reorganized SCSS files
Content and localization: new Markdown alert syntax and internationalization improvements
Hugo 0.155.0 requirement, and 0.153+ breaking and notable changes

Hugo 0.152.0-0.155.x upgrade guide

Mon, 09 Feb 2026 00:00:00 +0000

This post summarizes the breaking and notable changes in Hugo 0.152.0 to 0.155.3. It is a companion post to the Docsy 0.14.0 and 0.13.0 release and upgrade guides.

Upgrade summary

This guide highlights breaking changes in Hugo 0.152.0–0.155.x and the actions you may need to take.

Review BREAKING changes:
- YAML yes/no tokens are strings
- Build order changes for multidimensional sites
Review deprecations (non-breaking, but recommended):
- lang mount option deprecated
- includeFiles/excludeFiles deprecated
Optionally skim:
- Known issues and fixes
- Notable changes
Jump to Upgrade to Hugo 0.155.x once you’re ready

YAML yes/no tokens are strings (0.152.0)

Release 0.152.0 (2025-10-21) upgrades to a more modern YAML library, which introduces a breaking change to the way that YAML interprets certain tokens across configuration files and page front matter.

Release 0.13.0 report and upgrade guide

Mon, 24 Nov 2025 00:00:00 +0000

Highlights

Docsy 0.13.0 includes the most upvoted enhancement request of 2025, and more.
This release has new features and only minor breaking changes.¹
Read about our experiences using AI to upgrade Docsy projects.

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
Jump to Upgrade to 0.13.0 once you are ready.

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.

Upgrade to Docsy 0.12.0 from 0.11.0

Tue, 11 Nov 2025 00:00:00 +0000

Since we didn’t publish a release announcement for 0.12.0, I’m using this opportunity to walk through the upgrade process from 0.11.0 to 0.12.0.

TL;DR: The main breaking changes in Docsy 0.12.0 stem from Hugo’s new template system, which causes layouts subfolder and filename changes.

In this post you’ll walk through the upgrade process for:

Docsy: 0.11.0 → 0.12.0
Hugo: 0.136.2 → 0.147.5 ¹
Node: LTS 20 → LTS 22 ¹

Note

This post covers the common upgrade steps you’re likely to encounter. Your project may include customizations that require additional adjustments. We recommend making these changes in a separate branch and testing thoroughly before deploying to production.

Docsy 2024 Review: Adoptions and Enhancements

Thu, 12 Dec 2024 00:00:00 +0000

As we reflect on 2024, it’s exciting to see steady progress toward the goals outlined in our 2024 priorities. This year, we focused on enhancing stability, improving internationalization, and delivering long-anticipated features like dark mode and continuous integration (CI) testing.

Docsy’s use increased by 57% in 2024, from 1.4K to 2.2K projects! ¹

Let’s dive into the development highlights from 2024 and take a peek at what lies ahead.

Release highlights

We published three releases this year, each focusing on stability while introducing at least one major feature enhancement. Highlights include:

Docsy 0.10.0 release report

Wed, 01 May 2024 00:00:00 +0000

The big news with Docsy 0.10.0 is color themes and dark mode!

Hugo: breaking changes and deprecation notices

In this release, Docsy’s Hugo dependency is upgraded to 0.125.4 from 0.122.0. An important thing to note here is that Hugo 0.123.0 was a significant upgrade that included some breaking changes. Before upgrading to this Docsy version, review Hugo’s deprecation notices and breaking changes since 0.122.0.

Reminder

For the official support limits for Docsy and its peer packages, see Official support limits.

Docsy 0.9.0 release report

Fri, 09 Feb 2024 00:00:00 +0000

Docsy 0.9.0 is a sizable¹ release (containing 65+ PRs) that has some breaking and notable changes worth calling out, namely those related to:

Thank you to all contributors!

For a list of all footer improvements and fixes included in this release, see #1818. We mention a few in this section. More footer improvements, for even easier customization, are planned for the next major release (#1852).

Docsy priorities for 2024

Tue, 28 Nov 2023 00:00:00 +0000

TL;DR 1.4K projects use Docsy! The top user-project focused priorities for 2024 are: improving Docsy’s stability, usability & customizability, and cohesiveness while performing feature consolidation.

Docsy is a popular theme

The Hugo-Docsy tool combo is powerful and effective, as I’ve blogged about elsewhere. It’s maybe no surprise then, to see Docsy used by 1.4K projects¹. Why is Docsy popular? I can’t say for sure, but I use and recommend Docsy because it has the core features — necessary for publishing non-trivial tech-doc sites — that projects seem to want and need, including support for versioning, multiple languages, auto-generated site navigation, and more. It’s quick to set up, and it allows projects to focus on delivering site content rather than writing site template code.

Upgrade to Docsy 0.7 & Bootstrap 5

Thu, 03 Aug 2023 00:00:00 +0000

Last June, Docsy celebrated a significant milestone with the release of version 0.7.0. This major upgrade was the result of six months of meticulous work (#470) focused on the migration to Bootstrap 5.2. For highlights and the rationale behind that journey, see Migrating to Bootstrap 5.2.

This blog post is intended to help those who are upgrading to Docsy 0.7 and Bootstrap 5, based on my Docsy 0.7 upgrade experiences, specifically related to Bootstrap. The post starts with general guidance for Docsy-based projects wishing to upgrade. Every project’s migration experience will be unique, but hopefully this post, and the two included case studies, will make your upgrade process easier and faster.

Migrating to Bootstrap 5.2

Mon, 05 Jun 2023 00:00:00 +0000

Docsy, and Docsy-based project websites (including those at the CNCF), have been happily using the Bootstrap CSS framework from Docsy’s inception. In January of this year, Bootstrap 4 (the version used by Docsy for the past few years) reached its end of life. While we, the Docsy steering committee, have been eager to benefit from the Bootstrap 5 improvements, we were concerned about the magnitude of the migration effort, as well as the impact on downstream projects. Because of this, the migration was delayed for as long as possible. In December of 2022, when Bootstrap 4 stopped receiving critical upgrades, we declared Docsy to be in a feature freeze, and focused our maintenance efforts on the Bootstrap 5 migration.

Hello Docsy!

Thu, 07 Apr 2022 00:00:00 +0000

Hello

It may seem strange to see a “Hello” post from a project that’s several years old, but as Docsy matures as a community-driven project, we thought it was time to (re)introduce ourselves and talk about what’s new with your favorite (we hope) Hugo documentation theme!

Discuss amongst yourselves

Our Discussions are really hopping lately! Don’t miss our notice of the upcoming deprecation of the Font-Awesome and Bootstrap git submodules or our announcement of our new governance model!