From acae624cf441fbc3607b462a2c3a19ff82c1dc28 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 9 Feb 2024 10:13:46 -0500 Subject: [PATCH] [blog] Docsy 0.9.0 release report --- userguide/content/en/blog/2024/0.9.0.md | 136 ++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 userguide/content/en/blog/2024/0.9.0.md diff --git a/userguide/content/en/blog/2024/0.9.0.md b/userguide/content/en/blog/2024/0.9.0.md new file mode 100644 index 0000000000..4acd28f071 --- /dev/null +++ b/userguide/content/en/blog/2024/0.9.0.md @@ -0,0 +1,136 @@ +--- +title: Docsy 0.9.0 release report +linkTitle: Release 0.9.0 +author: > + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), + for the [Docsy Steering + Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc) +date: 2024-02-09 +# prettier-ignore +cSpell:ignore: CNCF Chalin subdir +--- + +Docsy [0.9.0] is a sizable release (containing 50 PRs) that has some breaking +and notable changes worth calling out, namely those related to: + +- [Footer improvements](#footer) +- [Repository Links and other page info](#page-meta) +- [Look and feel](#look-and-feel) + +## Footer improvements {#footer} + +> Oh my! We've closed [issue #2][#2]! + +This release has resolved **_the_ longest standing and first ever issue +created** over Docsy! + +- [The footer should allow a more flexible copyright statement #2][#2] by + [@sarahmaddox] + +Thanks to [@yann-soubeyrand] and [@deining] for your contributions. + +Another notable improvement: the footer partial has been broken into parts for +easier customization ([#1500]). For details concerning all footer improvements +and fixes, see [#1818]. + +A few more footer improvements for even easier customization are planned +([#1852]) for the next [major release][#1812]. + +## Repository Links and other page info {#page-meta} + +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 the presence of a homepage or not. + +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 the [Hugo 0.112.0] release in May 2023 +that the necessary [functions] became available. For details, see: + +- [Fix links for single language sites #1744][#1744] +- [Hugo v0.112.0 - New template functions][tmpl-func], by [@jmooring] + +We're convinced that Lisa's fix has squashed repo-link bugs for good! + +As mentioned in the [CHANGELOG][0.9.0], 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][#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 by further layout refactoring and extension. + +Repository links grant access to page meta information. Page last-modified ... +XXXXXXXX + +## Look and feel + +### Heading self links + +Docsy has switched to build-time generation of heading self links using Hugo's +`render-heading.html` [hook], in favor of client-side rendering via +`assets/js/anchor.js` — which has been dropped ([#1460]). + +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 + +### 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 + +Finally, 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 0.10.0 + +For the complete list of changes in this release, see the [CHANGELOG entry for +0.9.0][0.9.0] and the issue +[Release 0.9.0 preparation #1759](https://github.com/google/docsy/issues/1759) + +To track the preparation of the next release, see +[Release 0.10.0 preparation #1812](https://github.com/google/docsy/issues/1812). + +[.td-heading-self-link]: + https://github.com/chalin/docsy/blob/849dea0790bbaef5f4f71659824f44045afcd65e/assets/scss/_content.scss#L98 +[@deining]: https://github.com/deining +[@jmooring]: https://github.com/jmooring +[@sarahmaddox]: https://github.com/sarahmaddox +[@yann-soubeyrand]: https://github.com/yann-soubeyrand +[#138]: https://github.com/google/docsy/issues/138 +[#1460]: https://github.com/google/docsy/issues/1460 +[#1500]: https://github.com/google/docsy/pull/1500 +[#1744]: https://github.com/google/docsy/pull/1744 +[#1812]: https://github.com/google/docsy/issues/1812 +[#1814]: https://github.com/google/docsy/issues/1814 +[#1815]: https://github.com/google/docsy/pull/1815 +[#1818]: https://github.com/google/docsy/pull/1818 +[#1820]: https://github.com/google/docsy/issues/1820 +[#1841]: https://github.com/google/docsy/issues/1841 +[#1852]: https://github.com/google/docsy/issues/1852 +[#2]: https://github.com/google/docsy/issues/2 +[0.9.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#090 +[blocks/feature]: + https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature +[functions]: https://gohugo.io/functions/ +[hook]: https://gohugo.io/templates/render-hooks/ +[Hugo 0.112.0]: https://github.com/gohugoio/hugo/releases/tag/v0.112.0 +[language parameter]: + https://www.docsy.dev/docs/language/#internationalization-bundles +[Lisa]: https://github.com/LisaFC +[mounts]: + https://gohugo.io/hugo-modules/configuration/#module-configuration-mounts +[path_base_for_github_subdir]: + https://www.docsy.dev/docs/adding-content/repository-links/#path_base_for_github_subdir-optional +[repository links]: https://www.docsy.dev/docs/adding-content/repository-links/ +[tmpl-func]: + https://discourse.gohugo.io/t/hugo-v0-112-0-new-template-functions/44512