Skip to content

Latest commit

 

History

History
201 lines (156 loc) · 8.41 KB

0.9.0.md

File metadata and controls

201 lines (156 loc) · 8.41 KB
title linkTitle author date cSpell:ignore
Docsy 0.9.0 release report
Release 0.9.0
2024-02-09
CNCF Chalin subdir

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

Thank you to all contributors!

Footer improvements {#footer}

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

Footer layout changes {#footer-layout}

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.

Footer copyright date-range and more {#footer-copyright}

Oh my! We've closed issue #2!

This release has resolved 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".

Footer streamlined

  • 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, or delete the "footer_all_rights_reserved" language parameter for all your site's languages. 
    .td-footer__all_rights_reserved {
  display: inline;
}

Repository Links and other page info {#page-meta}

Repository links

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 if 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 pages of sites that use mounts and path_base_for_github_subdir.

As can be seen from Repository / page-meta link fixes and improvements #1841, several issues remain, but resolving #1744 established 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

Heading self links

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 text is now CSS-defined to be #, a common choice for websites. Projects can customize the appearance of the heading link through the .td-heading-self-link class. Heading self links are now:

  • Always visible on mobile and touch devices
  • Otherwise the link is invisible until the user hovers over the heading

Accessibility: Links are underlined

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. Projects wanting to recover the ellipsis can add them 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 CHANGELOG entry for 0.9.0 and the issue Release 0.9.0 preparation #1759

What is on the horizon for Docsy improvements? 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:

Footnotes

  1. Sizable by Docsy-release standards ↩