[blog] Docsy 0.9.0 release report

.markdown-link-check.json

@@ -8,6 +8,9 @@
     },
     {
       "pattern": "https://docs.npmjs.com/cli/v10/using-npm/scripts#prepare-and-prepublish"
+    },
+    {
+      "pattern": "https://www.docsy.dev/blog/2024/0.9.0/"
     }
   ],
   "timeout": "3s",

CHANGELOG.md

@@ -13,17 +13,18 @@ Useful links:
 - [Releases] & [tags]. Jump to the [latest] release.
 - [Milestones]
 
-[24Q1]: https://github.com/google/docsy/milestone/10
 [latest]: https://github.com/google/docsy/releases/latest
 [milestones]: https://github.com/google/docsy/milestones
 [releases]: https://github.com/google/docsy/releases
 [tags]: https://github.com/google/docsy/tags
 
 ## 0.9.0
 
-> ### UNRELEASED: this planned version is still under development.
+> ### UNRELEASED: this planned version is still under development
 
-For the full list of changes, see the [0.9.0] release notes.
+For an introduction and commentary, see the [0.9.0 release report]. For the full
+list of commits, see the [0.9.0] release notes. The most significant changes of
+this release are listed next.
 
 **Breaking changes**:
 
@@ -44,80 +45,40 @@ For the full list of changes, see the [0.9.0] release notes.
 - **Heading self-link** support has been reimplemented and projects must now
   explicitly enable the feature. For details, see [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]).
-
 **Footer changes**: refactoring, for easier customization, and simplification.
 For details concerning all footer changes, see [#1818].
 
 - **Footer layout** has been factored into parts: _left_, _right_, and _center_,
-  with _copyright_ a subpart of center. Each part has its own style tag, for
-  example: `td-footer__left`. Note that the style `td-footer__copyright-etc` has
-  been renamed to `td-footer__center`.
-
-- **Footer copyright**, supports date-range, and site copyright fallback.
-
-  - 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`] option will be
-    used and rendered as markdown, "as is" &mdash; with no year is added.
-
-- **Footer simplification**
-  - 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:
-    ```scss
-    .td-footer__all_rights_reserved {
-      display: inline;
-    }
-    ```
-
-**Look and feel**:
-
-- Docsy follows recommended accessibility practice: page-body **links are
-  underlined**. For details, see [#1814] and [#1815].
-- **[blocks/feature] shortcode** no longer adds ellipsis (`...`) after the
-  read-more text. If you would like to recover the ellipsis, then add them to
-  the `"ui_read_more"` [language parameter] for your site's languages ([#1820]).
+  with _copyright_ a subpart of center. For details see [Footer layout]
+- **Footer copyright**, supports date-range, and site copyright fallback. For
+  details, see [Footer copyright].
+- **Footer streamlined**: the About-page footer link and All-rights-reserved
+  text are now hidden by default. For details, see [Footer streamlined].
 
 **Other changes**:
 
 - The latest release of **[Mermaid] resources** are now fetched at build time
   ([#1410]).
+- [Look and feel] updates.
 
 [0.9.0]: https://github.com/google/docsy/releases/latest?FIXME=v0.9.0
+[0.9.0 release report]: https://www.docsy.dev/blog/2024/0.9.0/
 [#1410]: https://github.com/google/docsy/pull/1410
-[#1460]: https://github.com/google/docsy/issues/1460
 [#1744]: https://github.com/google/docsy/pull/1744
-[#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
-[blocks/feature]:
-  https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature
 [disabling links]:
   https://www.docsy.dev/docs/adding-content/repository-links/#disabling-links
-[Heading self links]:
-  https://www.docsy.dev/docs/adding-content/navigation/#heading-self-links
+[Footer layout]: https://www.docsy.dev/blog/2024/0.9.0/#footer-layout
+[Footer copyright]: https://www.docsy.dev/blog/2024/0.9.0/#footer-copyright
+[Footer streamlined]: https://www.docsy.dev/blog/2024/0.9.0/#footer-streamlined
+[Heading self links]: https://www.docsy.dev/blog/2024/0.9.0/#heading-self-links
+[look and feel]: https://www.docsy.dev/blog/2024/0.9.0/#look-and-feel
 [mermaid]:
   https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#diagrams-with-mermaid
 [multi-language]: https://www.docsy.dev/docs/language/
 [path_base_for_github_subdir]:
   https://www.docsy.dev/docs/adding-content/repository-links/#path_base_for_github_subdir-optional
-[project style file]:
-  https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files
-[hook]: https://gohugo.io/templates/render-hooks/
-[language parameter]:
-  https://www.docsy.dev/docs/language/#internationalization-bundles
 [Repository Links]: https://www.docsy.dev/docs/adding-content/repository-links/
-[site `copyright`]: https://gohugo.io/methods/site/copyright/
 [union file system]:
   https://gohugo.io/getting-started/directory-structure/#union-file-system
 
@@ -226,7 +187,7 @@ For the full list of changes, see the [0.7.0] release notes.
     extension testing. ([#906])
   - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939])
   - `blocks/section`: **default** and accepted values of the `type` argument
-    have changed! For details see [blocks/section] ([#1472]).
+    have changed! For details, see [blocks/section] ([#1472]).
   - **Card shortcodes** ([#1376])]:
     - Renamed CSS class `td-card-deck` to `td-card-group`.
     - `card`, `card-code`: markup of inner content (HTML/markdown) now depends
@@ -439,7 +400,7 @@ For the full list of changes, see the [0.2.0] release notes.
 
 ## 0.X.Y
 
-> ### UNRELEASED: this planned version is still under development.
+> ### UNRELEASED: this planned version is still under development
 
 For the full list of changes, see the [0.x.y] release notes.
 

userguide/content/en/blog/2024/0.9.0.md

@@ -0,0 +1,205 @@
+---
+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[^1] release ([containing 65+ PRs][v0.8.0...v0.9.0])
+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)
+
+Thank you to all [contributors][0.9.0]!
+
+## 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][#1812] ([#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][#2]!
+
+This release has resolves **_the_ longest standing and first ever issue
+created** in Docsy!
+
+- [The footer should allow a more flexible copyright statement #2][#2] by
+  [@sarahmaddox]
+
+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" &mdash; with no date(s)
+  added.
+
+[site `copyright`]: https://gohugo.io/methods/site/copyright/
+
+### 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] from all your site's
+  [internationalization bundles][language parameter].
+  ```scss
+  .td-footer__all_rights_reserved {
+    display: inline;
+  }
+  ```
+
+[project style file]:
+  https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files
+
+## 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 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:
+
+- [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 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][#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].
+
+[Last-modified page metadata]:
+  /docs/adding-content/repository-links/#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 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)
+
+[Heading self links]: /docs/adding-content/navigation/#heading-self-links
+
+### 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 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](https://github.com/google/docsy/issues/1759).
+
+Which Docsy improvements are on the horizon? For work items _tentatively_ planed
+for the next release, see
+[Release 0.10.0 preparation #1812](https://github.com/google/docsy/issues/1812).
+
+Feature and fix candidates for 0.10.0 and beyond currently include more
+Bootstrap work, in preparation for the reintroduction of RTL support &mdash;
+specifically:
+
+- [BSv5.2 upgrade followup](https://github.com/google/docsy/issues/1510)
+- [Upgrade to Bootstrap 5.3 #1528](https://github.com/google/docsy/issues/1528)
+- [[BSv5] Reintroduce RTL support using RTLCSS bootstrap](https://github.com/google/docsy/issues/1442)
+- [Support adding theme colors](https://github.com/google/docsy/issues/1845)
+
+[.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
+[#1817]: https://github.com/google/docsy/pull/1817
+[#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
+[blocks/feature]:
+  https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature
+[[email protected]]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#090
+[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
+[0.9.0]: https://github.com/google/docsy/releases/tag/v0.9.0
+[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
+[v0.8.0...v0.9.0]: https://github.com/google/docsy/compare/v0.8.0...v0.9.0
+
+[^1]: Sizable by Docsy-release standards

userguide/content/en/docs/adding-content/repository-links.md

@@ -360,8 +360,10 @@ Class names using the `--KIND` suffix were deprecated as of [v0.9.0].
 ## Last-modified page metadata
 
 To have page-source metadata displayed at the bottom of documentation pages and
-blog posts, set the following configuration parameter to `true`. A
-last-modified page note looks something like this:
+blog posts, set the `GitInfo` configuration parameter to `true`, and ensure that
+`params.github_repo` is defined.
+
+A last-modified page note looks something like this:
 
 > <div class="td-page-meta__lastmod"
 >      style="margin-top: 0 !important; display: block !important;">