Blog on OINK

Introducing the OINK implementation preview

Sat, 08 Aug 2026 00:00:00 +0000

Today we are publishing the OINK implementation preview: a directly evolved Docsy theme with one canonical product shell, a Hugo-only consumer build, local-first browser dependencies, a general multilingual framework, and a set of reusable content components drawn from PGSTY documentation sites.

This is an implementation and documentation milestone, not a public versioned release. The final public brand, module and package identities, first version, and production Cloudflare Pages deployment remain explicit release gates.

OINK implementation diary: from copied shells to one theme

Sat, 08 Aug 2026 00:00:00 +0000

OINK began with an awkward observation: several production documentation sites looked related because they were related, but their common implementation lived as copied files. The visible result was consistent enough; the maintenance model was not.

This diary records how the project moved from repeated site overrides to one directly evolved theme. It focuses on decisions and evidence rather than a commit-by-commit transcript.

Locking the contract

The first useful work was subtraction. We wrote down what the product must be before choosing how to implement it:

Release 0.16.0 report and upgrade guide

Wed, 29 Jul 2026 00:00:00 +0000

Highlights

First-class npm support: install Docsy from the registry, and more
Favicons: drop your icons into static/ and Docsy does the rest
Shared chrome (experimental): a build mode for much faster link checking of large sites
Agent-ready upgrade guide: hand this post to your AI assistant

Release summary

Packaging modernization:
- Theme folder move: a one-line path update per install mode
- Hugo modules now source Bootstrap and Font Awesome via npm
- PostCSS now opt-in for non-RTL sites
- Docsy on the npm registry: the new @docsy/theme package
Minimum Hugo raised to 0.160.1: was 0.146.0
New features:
- Favicon discovery from static/
- Shared chrome build mode (experimental)
Other notable changes, and for maintainers: repository package layout, and build and test guards

Ready to upgrade?

⚠️ Respect the order of steps to avoid breaking your build.
Review BREAKING changes:
Review the companion Hugo 0.158+ upgrade guide if your site is not already building cleanly with Hugo 0.164.0.
Optionally skim:
- Docsy on the npm registry
- Favicon discovery
- Experimental shared chrome build mode
- PostCSS is opt-in for non-RTL sites
- Other notable changes, and for maintainers
Jump to Upgrade to 0.16.0 yourself, or ask an AI agent.

/ Theme folder move

Docsy’s canonical theme tree has moved from the repository root to theme/. This is the main structural change in 0.16.0.

Hugo 0.158.0-0.164.x upgrade guide

Tue, 28 Jul 2026 00:00:00 +0000

This post is a companion to the Docsy 0.16.0 release post, which specifies the Hugo versions that 0.16.0 requires and validates.

Upgrade summary

This guide is for you if you’re:
- Upgrading to Docsy 0.16.0
- Upgrading only Hugo
Review BREAKING changes:
- Node 22+ is required for Hugo-managed Node tools
- HTML content and symlink security changed
Review deprecations:
- Language config and template APIs
- Imaging config and template APIs
Optionally skim:
Jump to Upgrade to Hugo 0.164.0 once you’re ready.

Language API deprecations (0.158.0)

Hugo 0.158.0 renamed several language configuration keys and template methods. The old names log deprecation notices first, then move toward warnings and eventual errors on Hugo’s deprecation timeline.

Release 0.15.0 report and upgrade guide

Fri, 01 May 2026 00:00:00 +0000

Highlights

Agent support: llms.txt, Markdown page output, and a “View Markdown” page-meta link
Doc-rooted sites: improved support for publishing docs at the site root
Version menus: richer entries and updated navbar rendering

Release summary

Agent support (experimental):
- Generated llms.txt
- Markdown page output
- “View Markdown” page-meta link
Doc-rooted sites (experimental): documented pattern and example variant for sites whose docs section is published at the site root
Version menu entries: headings, separators, per-entry page-link behavior, and kind-specific styling
Content, shortcodes, and internationalization:
- Community and footer links
- card shortcode rendering
- Internationalization additions and updates

Ready to Upgrade?

Review BREAKING changes:
- Community and footer links
- Version menu entries
- Card shortcode rendering (low risk)
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.15.0 once you are ready

Agent support

Release 0.15.0 includes the phase 1 implementation of agent support, which provides opt-in features that help AI agents and automated tools discover and use your site content, including:

Release 0.14.0 report and upgrade guide

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

Patch updates 0.14.1 to 0.14.3

For the key fixes of these patch updates, see 0.14.1, 0.14.2, and 0.14.3. For other changes to 0.14.2, see Patch update 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: 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!

Blog on OINK

Introducing the OINK implementation preview

OINK implementation diary: from copied shells to one theme

Locking the contract

Release 0.16.0 report and upgrade guide

Release summary

Ready to upgrade?

/ Theme folder move

Hugo 0.158.0-0.164.x upgrade guide

Upgrade summary

Language API deprecations (0.158.0)

Release 0.15.0 report and upgrade guide

Release summary

Ready to Upgrade?

Agent support

Release 0.14.0 report and upgrade guide

Hugo 0.152.0-0.155.x upgrade guide

Upgrade summary

YAML yes/no tokens are strings (0.152.0)

Release 0.13.0 report and upgrade guide

Release summary

Ready to upgrade?

Navigation and UX improvements

Active TOC entry tracking

Upgrade to Docsy 0.12.0 from 0.11.0

Docsy 2024 Review: Adoptions and Enhancements

Release highlights

Docsy 0.10.0 release report

Hugo: breaking changes and deprecation notices

Docsy 0.9.0 release report

Footer improvements

Docsy priorities for 2024

Docsy is a popular theme

Upgrade to Docsy 0.7 & Bootstrap 5

Migrating to Bootstrap 5.2

Hello Docsy!

Hello

Discuss amongst yourselves