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 ↩︎

Last modified March 4, 2024: UG: normalize PSC links into local blog page (#1884) (020f860)