Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[blog] Docsy 0.9.0 release report (#1854)
- Loading branch information
Showing
4 changed files
with
230 additions
and
59 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" — 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 — | ||
| 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 | ||
| [CL@0.9.0]: 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters