[blog] Docsy 0.9.0 release report

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