Posted on August 4, 2023

Originally published on the Docsy blog by Patrice Chalin, CNCF and Docsy Steering Committee 

A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples

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

If you’re here, you probably want to upgrade your Docsy-based project—so, let’s jump in!

Upgrading your project

As was mentioned in the first post, each project uses its own specific set of Bootstrap and Docsy features, so in all likelihood, your upgrade journey will be unique. This section offers some general guidance.

Upgrade Docsy

If you haven’t already, upgrade your project all the way up to Docsy 0.6 first. Each release of Docsy can bring its own set of upgrade challenges that will vary in size and effort depending on your project and the features it uses, as well as how long it’s been since your version of Docsy has been upgraded. You’ll want to get all pre-0.7 upgrade issues out of the way so that you can focus on Bootstrap 5 issues. Once you are done, upgrade to the latest Docsy 0.7.x release.

Address Bootstrap changes

I recommend that you first walk through the Bootstrap 5.2 migration page to get an appreciation of the scope of the changes made to Bootstrap 5 relative to 4. Identify the breaking changes to those Bootstrap features used by your project, and address each individually. I mention a few breaking changes next and close the section with a comment about what to do about the rest.

Some Bootstrap changes will break your website’s layout or functionality in obvious ways. This is the case for the rename of utility classes, like ml-1 and pr-2. Using regular-expression based search-and-replace over your project’s custom layouts or doc-page inline HTML is a good way to tackle this. I’ve used regex like these:

If your project uses Bootstrap JavaScript plugins such as dropdowns, popovers, and tooltips, these will stop working until you adjust data attribute names, which are now “namespaced” using the data-bs prefix. For example, use data-bs-toggle instead of data-toggle.

Other Bootstrap breaking changes will require more work to address, such as the following that were mentioned in the TL;DR of the first post:

The Docsy blog layout used the .media class, which was dropped from Bootstrap 5. This, and the .row and .col style changes, required a couple of iterated changes to the blog layouts, such as PR #1566. If your project customizes blog layouts, then you’ll want to walk through the updates carefully. Otherwise, your project will get these updates automatically, without any further required changes.

Should you encounter a Bootstrap-5 breaking change affecting your project that hasn’t been mentioned above, you might find the opening comment of Docsy issue #470 · Upgrade to Bootstrap 5.2 useful: it lists 50 tasks, each addressing a distinct migration problem, accompanied by notes or cross-referenced PRs that illustrate how each problem was resolved.

Address Docsy-specific changes

It is worth mentioning in passing some of the main Docsy 0.7 changes that aren’t related to Bootstrap, such as:

For the complete list of changes, see the CHANGELOG at 0.7.0.

Case studies

Our two case study projects to illustrate the Docsy upgrade process are the OpenTelemetry project and the Docsy example template repository.

opentelemetry.io

Several CNCF projects use the Docsy theme, including opentelemetry.io, which I used as a Docsy pre-release test site. As suggested earlier, I first upgraded Docsy from 0.4 to 0.6 (opentelemetry.io issue #2419).

The upgrade to Docsy 0.7 went fairly smoothly. In addition to addressing the “obvious changes” related to utility class renames and data-attribute namespacing, the OTel website required these project-specific changes:

That’s it! To see how both of the above were resolved, see OTel PR #2490.

Docsy-example

The docsy-example repository is a GitHub template that we suggest as a possible starting point for users looking to adopt Docsy for a new website. The example site features multi-language support, which had an impact on the required upgrades.

The example-site upgrade was even simpler than for the OTel website. The key changes (PR #221) were mainly confined to the landing page of each natural language:

That was it.

What next?

If your project doesn’t override any Docsy layouts, then your upgrade experience should be relatively straightforward. Reviewing layout file changes, on the other hand, always warrants special attention.

With the tips shared here, I hope that your journey to Docsy 0.7 will be more streamlined. Consider sharing your experiences by adding a comment to the discussion of 0.7.0 or any later 0.7.x release. Wishing you a successful upgrade journey!

A special thanks to Erin McKean for detailed and valuable feedback on this post, and to all who contributed to the 0.7.x releases of Docsy and the Docsy example!