This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Blog

Docsy 0.9.0 release report

By Patrice Chalin (CNCF), for the Docsy Steering Committee |

Docsy 0.9.0 is a sizable1 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).

In support of easier footer customization, the footer layout has been factored into parts: left, right, and center (#1500), with copyright as a subpart of center (#1817). Each part has its own class, such as td-footer__left, for easy style customization. Note that the class td-footer__copyright-etc has been renamed to td-footer__center.

Oh my! We’ve closed issue #2!

This release has resolves the longest standing and first ever issue created in Docsy!

The footer copyright now supports a date-range and the site-copyright as a fallback:

  • The Hugo config option params.copyright, previously a string, can now also be a map with the following optional fields: authors, from_year, to_year. When unset, to_year defaults to the year that the site built. The default authors is “<Site.Title> Authors” and this field is rendered as markdown.
  • If params.copyright is unset, then the site copyright configuration option will be used and rendered as markdown “as is” — with no date(s) added.
  • The About-page footer link is now hidden by default. To enable this link, set .params.ui.footer_about_enable to true in your project’s configuration file. Parameter .params.ui.footer_about_disable is deprecated.
  • The All-rights-reserved text is hidden by default. To make it visible, add the following to your _styles_project.scss project style file (optionally with a !important modifier — not shown):
    .td-footer__all_rights_reserved {
  display: inline;
}

Repository links and other page info

Getting repository links right has eluded Docsy maintainers and contributors since 2019 (#138). The challenge is ensuring that repository links work for all Docsy-based projects regardless of their setup for single- or multi-language support, or whether they have a homepage.

At last, steering committee member Lisa’s determination has payed off. Half-jokingly, Lisa commented: All we needed was several years and a few Hugo improvements. That is, it wasn’t until Hugo 0.112.0, released in May 2023, that the necessary functions became available. For details, see:

We’re convinced that Lisa’s fix has squashed repo-link bugs for good!

As mentioned in the CHANGELOG, this is a breaking change for sites that use mounts and that have pages configured with path_base_for_github_subdir.

As can be seen from Repository / page-meta link fixes and improvements #1841, several issues remain, but resolving #1744 establishes the necessary foundation for future work. The issues listed in #1841 will be addressed in a future release through further layout refactoring and extension.

Last-modified page info

You can configure your site to display page-source last-modified metadata at the bottom of documentation and blog pages. For details, see the newly added User Guide section Last-modified page metadata.

Look and feel

Docsy has switched to build-time generation of heading self links using Hugo’s render-heading.html hook, replacing client-side rendering via assets/js/anchor.js (dropped in #1460). Projects must now explicitly enable the feature. For details, see Heading self links.

Formerly an embedded SVG, the default self-link symbol is now CSS-defined to be #, a common choice for websites. Projects can customize the appearance of the heading self link through the .td-heading-self-link class.

Heading self links are now:

  • Always visible on mobile and touch devices
  • For other devices and screens, the link is invisible until the user hovers over the heading (as before)

Docsy now follows recommended accessibility practice: page-body links are underlined by default. For details, see #1814 and #1815.

Bye bye ellipsis

The blocks/feature shortcode no longer includes ellipsis ("…") after the “Read more” link text. Projects wanting to recover the ellipsis can add it to the "ui_read_more" language parameter for your site’s languages (#1820).

References and future releases

For the complete list of changes in this release, see the 0.9.0 release entry and issue Release 0.9.0 preparation #1759.

Which Docsy improvements are on the horizon? For work items tentatively planed for the next release, see Release 0.10.0 preparation #1812.

Feature and fix candidates for 0.10.0 and beyond currently include more Bootstrap work, in preparation for the reintroduction of RTL support — specifically:

  1. Sizable by Docsy-release standards ↩︎

Docsy priorities for 2024

By Patrice Chalin (CNCF), for the Docsy Steering Committee |

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.

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

User-project focused and long-term vision

Steering committee members, including myself, are actively supporting several projects at the CNCF and Google that rely on Docsy. Both as users and contributors to Docsy, we share a vested interest in ensuring Docsy’s long-term health. Our envisioned priorities for Docsy are:

  1. Stability of Docsy’s core through bug fixes and necessary upgrades — the migration from the end-of-life Bootstrap 4 to version 5 is one example of such an effort.
  2. Reducing technical debt.
  3. Improving usability, customizability, and maintainability by, in particular, working to more clearly separate and document “API surfaces” — or configuration / customization surfaces.
  4. Feature consolidation, which I will explain next.

Google open sourced Docsy a little over five years ago, and thanks to community contributions, it has grown in stability and its feature set. During that time, Docsy also accumulated considerable technical debt, and it now suffers (IMHO) from a mild case of software bloat/feature creep. So, in addition to investing in Docsy’s long-term stability and maintainability, we need to reaffirm Docsy’s core features and deprioritize the rest2 — lest we suffer a fate similar to projects like cross-env. Consider Docsy on a feature diet.

Before tackling 2024 objectives, we plan on setting up a test infrastructure with (a growing) suite of tests to help us ensure Docsy’s integrity as it evolves.

Conclusion

This is a tall order for 2024 and beyond, but I believe that slow and steady wins the day.

We’re eager to hear from you, the Docsy community! Share your thoughts on our focus areas and how we can enhance Docsy. Take a look at our issue triage into quarterly milestones for a rough idea of what is targeted for upcoming releases. Vote for or comment on issues that are important to you, and we’ll do our best to respond and adjust release targets within the boundaries of our set priorities. Better yet, volunteer to work on the current quarter’s tasks. As we start the new year, we’ll be especially interested in getting help with testing and feature consolidation.

  1. According to Docsy’s GitHub analytics. ↩︎

  2. Features outside the identified core could even be moved to a separate community-maintained repo. The steering committee is also considering a “plugin” architecture for some secondary features, such as (to mention just one) Mermaid support. ↩︎

Upgrading to Docsy 0.7 & Bootstrap 5

A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples
By Patrice Chalin (CNCF & Docsy Steering Committee) |

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.

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:

  • Margin and padding: \b([mp])[lr](-([0-5]|auto))\b
  • Left/right classes: \b((float|border|rounded|text)-)(left|right)\b

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:

  • Default and accepted values of the blocks/section’s type argument have changed (#1472)
  • Pre-Hugo-0.54.x behavior of {{% %}} is no longer supported (#939)
  • Hugo release 0.110.0 or later is required

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:

  • Breaking changes to forms required a significant rework of the Registry form
  • While the OTel website has no blog layout overrides, it made use of the .media class (which was dropped) for registry entries. Flex styles were used instead.

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:

  • Utility-class renames, such as .ml-* and .mr-* to .ms-* and .me-*
  • blocks/section changes (PR #1472):
    • Language landing pages had to be renamed from .html to .md in support of using blocks shortcodes to render markdown content
    • Switched to type="row" for blocks/section elements that are rows (also from PR #220)

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!

Migrating to Bootstrap 5.2

An experience report in migrating Docsy from Bootstrap 4 to 5.2, with insights and instructions.
By Patrice Chalin (CNCF & Docsy Steering Committee) |

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.

This post is about Docsy’s migration journey to Bootstrap 5.21: it highlights the most notable steps, with a special attention given to the most surprising aspects of the migration. Our hope is that this post will be useful to others upgrading to Bootstrap 5, in particular, for downstream Docsy projects — though we plan a separate post specifically for downstream projects.

TL;DR

Eager to dive into the Bootstrap migration of your project? Besides carefully stepping through the Bootstrap migration page, watch out for the following:

  • The media-breakpoint-down() mixin’s breakpoint argument needs to be shifted.
  • Grid .row and .col style changes are breaking.
  • Import ordering of Bootstrap Sass files: import functions first.

For details, read on.

Technical details

If you are well accustomed to upgrading Docsy (and its dependencies) by reading changelogs and systematically stepping through commits, then this section provides a summary of some notable changes. In it, I describe technical aspects of the migration that surprised me, either because they required particular care in fixing, were undocumented, and/or insufficiently explained in the Bootstrap migration page.

Mixin media-breakpoint-down() argument shift

The breakpoint argument to the media-breakpoint-down() mixin needs to be bumped up to the next higher breakpoint. Thankfully, a similar change isn’t required of media-breakpoint-up(). This change will be required of Docsy-based projects. If you forget to make this non-obviously breaking layout change, your project’s responsive layouts will likely start misbehaving in apparently strange ways.

For details and an example, see:

Grid .row and .col style changes are breaking

The main issue addressed in this section is not, at the time of writing, documented in the Bootstrap 5 migration page.

There seems to be an assumption, in Bootstrap 5, that the immediate child of a .row should be a .col. I don’t know how strict an assumption this is. While I have searched for an explicit statement of this assumption in the Bootstrap documentation, I haven’t found one yet — if you are aware of such a statement, let us know!

This assumption wasn’t apparent nor was it enforced in Bootstrap 4, consequently, some of Docsy’s layouts failed to respect it. In most cases, fixing violations consisted of simply wrapping a .row’s child element in a .col, but the Docsy footer required a couple of iterations to get right.

My first footer adjustment reset flex-shrink to its default value (PR #1373), but that turned out to be unnecessary once I better understood how to appropriately handle row margins (PR #1523) — rows have negative margins, as I recently learned, which is something to keep in mind.

The following Bootstrap 5 .col style changes influenced Docsy-specific style updates and might impact Docsy-based projects as well:

References:

Import ordering of Bootstrap Sass files: functions first

Projects can import Bootstrap Sass sources all in one go (using bootstrap.scss), or selectively import any one of the 40+ Bootstrap parts, layouts, and components that they need. Regardless of the import strategy chosen, due to a Sass map initialization limitation, Bootstrap-client projects need to perform (emphasis mine):

… variable customizations … after @import "functions", but before > @import "variables" and the rest of [the Bootstrap] import stack.

For details, see New _maps.scss from the migration page, and Importing from Bootstrap’s Sass customization documentation.

Having to maintain a custom list of a few dozen imports (even if it’s relatively stable) feels like a maintenance overhead that we should avoid if we can, so in Docsy’s main.scss, we @import “functions” before Docsy- and project-specific variable overrides, and then we import the full Bootstrap suite of SCSS. This results in _functions.scss being imported twice, but according to the Sass @import documentation:

If the same stylesheet is imported more than once, it will be evaluated again each time. If it just defines functions and mixins, this usually isn’t a big deal, but if it contains style rules they’ll be compiled to CSS more than once.

The _functions.scss file only contains function definitions, so we should be ok. This seems like a small cost to pay in contrast to the alternative strategy of inlining the 40+ imports from bootstrap.scss.

References:

Systematic and stepwise migration

If you’ve glanced at the Bootstrap 5 migration page, you will see that there are a lot of changes to address while migrating. To ensure that we didn’t miss any, we systematically walked through the migration guide, and tracked the status of each change through Docsy issue #470. Each relevant migration page section is represented in the issue’s opening comment: we either noted that a migration-page section is irrelevant for Docsy, or added the section to the tracking issue, and list the PRs containing corresponding Docsy-specific changes. If you’re curious to see how that worked out, see Upgrade to Bootstrap 5.2 · Docsy issue #470.

First Bootstrap 5 release of Docsy

A first Bootstrap 5 release of Docsy is planned for the start of June, since most aspects of the migration have been completed. Some updates have been postponed, most notably support for right-to-left (RTL) text. For the complete list of followup items, see BSv5.2 upgrade followup · Docsy issue #1510.

As was mentioned earlier, this first release will be in support of Bootstrap 5.2. We plan a separate migration effort to bring Docsy up to Bootstrap 5.3, in particular to benefit from new color modes. You can track our progress through Docsy issue #1528.

Migrating Docsy-based projects

This section contains some preliminary and general guidance for downstream projects. We are planning a separate post to cover more migration details.

Bootstrap migration-page walkthrough

Each project uses its own specific set of Bootstrap features, so walking through the Bootstrap 5.2 migration page will be advisable for most projects. Of course, one strategy is just to upgrade and see what breaks or no longer works, but only doing that without a more systematic follow-up would be ill-advised for all but the most trivial projects—consider the challenge in detecting and recovering from a missed change to a ​​media-breakpoint-down() argument, as discussed earlier.

Docsy-specific changes

During the migration effort we seized the opportunity to do some long overdue Docsy house cleaning. For details concerning both breaking and non-breaking Docsy-specific changes, consult the changelog. In particular, one non-breaking but important change to be aware of is: [BSv5] Docsy variables cleanup … PR #1462.

Give it a try!

To get a first and quick impression of the impact of the upgrade on your project, it can be informative to simply upgrade Docsy and see what breaks. This is what the Docsy team did with Bootstrap 5. Only one change actually broke the build of the Docsy User Guide: the rename of the color-yiq() function.

After such a smoke test, we recommend systematically walking through the Bootstrap migration page as described above, and the Docsy changelog. I used this approach for opentelemetry.io, which was the first Docsy-based project to be upgraded with a pre-release of Bootstrap-5-based Docsy. The upgrade went quite smoothly. The main pain point of the OTel website was upgrading to Bootstrap 5 forms; an aspect of the migration that didn’t apply to Docsy since Docsy uses only the most trivial of forms.

We’ll have more to share about the OTel migration effort as well as general project-specific migration advice in a followup blog post. In the meantime, I hope that you have found parts of this technical article helpful for your own migration efforts.

CNCF project websites eager to migrate can send questions to the CNCF #techdocs Slack channel. CNCF and other Docsy-based projects can also start a discussion in the Docsy repository. Happy migrating!

A big thanks to the Docsy Steering Committee and other reviewers who offered feedback on earlier drafts of this post, as well as to all those who contributed to the migration effort.

A version of this article originally appeared as the CNCF blog post Migrating Docsy to Bootstrap 5 .

  1. Bootstrap 5.3 reached GA on May 30. There will be a separate migration effort to bring Docsy up to Bootstrap 5.3. ↩︎

Hello Docsy!

Welcome to the Docsy blog!

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!

Milestones, releases, and roadmaps

We are planning our first official release of Docsy soon—check out the milestones for 0.2.0. Got a suggestion for the roadmap? Open an issue.

Coming soon: project metrics

Starting next month, we’ll publish project metrics here on this blog.

Introducing the PSC

Docsy now has a Project Steering Committee! The PSC members are @chalin, @LisaFC, @geriom, and @emckean. If you’re interested in serving on the PSC, open an issue and nominate yourself!

Contribute to the blog!

Also coming soon: contribution guidelines. Got an idea for a blog post? Open an issue!