|
| 1 | +--- |
| 2 | +title: Docsy 0.9.0 release report |
| 3 | +linkTitle: Release 0.9.0 |
| 4 | +author: > |
| 5 | + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), |
| 6 | + for the [Docsy Steering |
| 7 | + Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc) |
| 8 | +date: 2024-02-09 |
| 9 | +# prettier-ignore |
| 10 | +cSpell:ignore: CNCF Chalin subdir |
| 11 | +--- |
| 12 | + |
| 13 | +Docsy [0.9.0] is a sizable[^1] release ([containing 65+ PRs][v0.8.0...v0.9.0]) |
| 14 | +that has some breaking and notable changes worth calling out, namely those |
| 15 | +related to: |
| 16 | + |
| 17 | +- [Footer improvements](#footer) |
| 18 | +- [Repository links and other page info](#page-meta) |
| 19 | +- [Look and feel](#look-and-feel) |
| 20 | + |
| 21 | +Thank you to all [contributors][0.9.0]! |
| 22 | + |
| 23 | +## Footer improvements {#footer} |
| 24 | + |
| 25 | +For a list of all footer improvements and fixes included in this release, see |
| 26 | +[#1818]. We mention a few in this section. More footer improvements, for even |
| 27 | +easier customization, are planned for the next [major release][#1812] ([#1852]). |
| 28 | + |
| 29 | +### Footer layout changes {#footer-layout} |
| 30 | + |
| 31 | +In support of easier footer customization, the footer layout has been factored |
| 32 | +into parts: _left_, _right_, and _center_ ([#1500]), with _copyright_ as a |
| 33 | +subpart of center ([#1817]). Each part has its own class, such as |
| 34 | +`td-footer__left`, for easy style customization. Note that the class |
| 35 | +`td-footer__copyright-etc` has been renamed to `td-footer__center`. |
| 36 | + |
| 37 | +### Footer copyright date-range and more {#footer-copyright} |
| 38 | + |
| 39 | +> Oh my! We've closed [issue #2][#2]! |
| 40 | +
|
| 41 | +This release has resolves **_the_ longest standing and first ever issue |
| 42 | +created** in Docsy! |
| 43 | + |
| 44 | +- [The footer should allow a more flexible copyright statement #2][#2] by |
| 45 | + [@sarahmaddox] |
| 46 | + |
| 47 | +The footer copyright now supports a date-range and the site-copyright as a |
| 48 | +fallback: |
| 49 | + |
| 50 | +- The Hugo config option `params.copyright`, previously a string, can now also |
| 51 | + be a map with the following optional fields: `authors`, `from_year`, |
| 52 | + `to_year`. When unset, `to_year` defaults to the year that the site built. The |
| 53 | + default `authors` is "<Site.Title> Authors" and this field is rendered as |
| 54 | + markdown. |
| 55 | +- If `params.copyright` is unset, then the [site `copyright`] configuration |
| 56 | + option will be used and rendered as markdown "as is" — with no date(s) |
| 57 | + added. |
| 58 | + |
| 59 | +[site `copyright`]: https://gohugo.io/methods/site/copyright/ |
| 60 | + |
| 61 | +### Footer streamlined |
| 62 | + |
| 63 | +- The About-page footer link is now hidden by default. To enable this link, set |
| 64 | + `.params.ui.footer_about_enable` to true in your project's configuration file. |
| 65 | + Parameter `.params.ui.footer_about_disable` is deprecated. |
| 66 | +- The All-rights-reserved text is hidden by default. To make it visible, add the |
| 67 | + following to your `_styles_project.scss` [project style file], or delete the |
| 68 | + `"footer_all_rights_reserved"` [language parameter] from all your site's |
| 69 | + [internationalization bundles][language parameter]. |
| 70 | + ```scss |
| 71 | + .td-footer__all_rights_reserved { |
| 72 | + display: inline; |
| 73 | + } |
| 74 | + ``` |
| 75 | + |
| 76 | +[project style file]: |
| 77 | + https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files |
| 78 | + |
| 79 | +## Repository links and other page info {#page-meta} |
| 80 | + |
| 81 | +### Repository links |
| 82 | + |
| 83 | +Getting [repository links] right has eluded Docsy maintainers and contributors |
| 84 | +since 2019 ([#138]). The challenge is ensuring that repository links work for |
| 85 | +all Docsy-based projects regardless of their setup for single- or multi-language |
| 86 | +support, or whether they have a homepage. |
| 87 | + |
| 88 | +At last, steering committee member [Lisa]'s determination has payed off. |
| 89 | +Half-jokingly, Lisa commented: _All we needed was several years and a few Hugo |
| 90 | +improvements_. That is, it wasn't until [Hugo 0.112.0], released in May 2023, |
| 91 | +that the necessary [functions] became available. For details, see: |
| 92 | + |
| 93 | +- [Fix links for single language sites #1744][#1744] |
| 94 | +- [Hugo v0.112.0 - New template functions][tmpl-func], by [@jmooring] |
| 95 | + |
| 96 | +We're convinced that Lisa's fix has squashed repo-link bugs for good! |
| 97 | + |
| 98 | +As mentioned in the [CHANGELOG][0.9.0], this is a **breaking change** for sites |
| 99 | +that use mounts and that have pages configured with |
| 100 | +[path_base_for_github_subdir]. |
| 101 | + |
| 102 | +As can be seen from [Repository / page-meta link fixes and improvements |
| 103 | +#1841][#1841], several issues remain, but resolving [#1744] establishes the |
| 104 | +necessary foundation for future work. The issues listed in [#1841] will be |
| 105 | +addressed in a future release through further layout refactoring and extension. |
| 106 | + |
| 107 | +### Last-modified page info |
| 108 | + |
| 109 | +You can configure your site to display page-source last-modified metadata at the |
| 110 | +bottom of documentation and blog pages. For details, see the newly added User |
| 111 | +Guide section [Last-modified page metadata]. |
| 112 | + |
| 113 | +[Last-modified page metadata]: |
| 114 | + /docs/adding-content/repository-links/#last-modified-page-metadata |
| 115 | + |
| 116 | +## Look and feel |
| 117 | + |
| 118 | +### Heading self links |
| 119 | + |
| 120 | +Docsy has switched to build-time generation of heading self links using Hugo's |
| 121 | +`render-heading.html` [hook], replacing client-side rendering via |
| 122 | +`assets/js/anchor.js` (dropped in [#1460]). Projects must now explicitly enable |
| 123 | +the feature. For details, see [Heading self links]. |
| 124 | + |
| 125 | +Formerly an embedded SVG, the default self-link symbol is now CSS-defined to be |
| 126 | +`#`, a common choice for websites. Projects can customize the appearance of the |
| 127 | +heading self link through the [.td-heading-self-link] class. |
| 128 | + |
| 129 | +Heading self links are now: |
| 130 | + |
| 131 | +- Always visible on mobile and touch devices |
| 132 | +- For other devices and screens, the link is invisible until the user hovers |
| 133 | + over the heading (as before) |
| 134 | + |
| 135 | +[Heading self links]: /docs/adding-content/navigation/#heading-self-links |
| 136 | + |
| 137 | +### Accessibility: Links are underlined |
| 138 | + |
| 139 | +Docsy now follows recommended **accessibility practice**: page-body **links are |
| 140 | +underlined** by default. For details, see [#1814] and [#1815]. |
| 141 | + |
| 142 | +### Bye bye ellipsis |
| 143 | + |
| 144 | +The [blocks/feature] shortcode no longer includes ellipsis ("...") after the |
| 145 | +"Read more" link text. Projects wanting to recover the ellipsis can add it to |
| 146 | +the `"ui_read_more"` [language parameter] for your site's languages ([#1820]). |
| 147 | + |
| 148 | +## References and future releases |
| 149 | + |
| 150 | +For the complete list of changes in this release, see the [0.9.0] release entry |
| 151 | +and issue |
| 152 | +[Release 0.9.0 preparation #1759](https://github.com/google/docsy/issues/1759). |
| 153 | + |
| 154 | +Which Docsy improvements are on the horizon? For work items _tentatively_ planed |
| 155 | +for the next release, see |
| 156 | +[Release 0.10.0 preparation #1812](https://github.com/google/docsy/issues/1812). |
| 157 | + |
| 158 | +Feature and fix candidates for 0.10.0 and beyond currently include more |
| 159 | +Bootstrap work, in preparation for the reintroduction of RTL support — |
| 160 | +specifically: |
| 161 | + |
| 162 | +- [BSv5.2 upgrade followup](https://github.com/google/docsy/issues/1510) |
| 163 | +- [Upgrade to Bootstrap 5.3 #1528](https://github.com/google/docsy/issues/1528) |
| 164 | +- [[BSv5] Reintroduce RTL support using RTLCSS bootstrap](https://github.com/google/docsy/issues/1442) |
| 165 | +- [Support adding theme colors](https://github.com/google/docsy/issues/1845) |
| 166 | + |
| 167 | +[.td-heading-self-link]: |
| 168 | + https://github.com/chalin/docsy/blob/849dea0790bbaef5f4f71659824f44045afcd65e/assets/scss/_content.scss#L98 |
| 169 | +[@deining]: https://github.com/deining |
| 170 | +[@jmooring]: https://github.com/jmooring |
| 171 | +[@sarahmaddox]: https://github.com/sarahmaddox |
| 172 | +[@yann-soubeyrand]: https://github.com/yann-soubeyrand |
| 173 | +[#138]: https://github.com/google/docsy/issues/138 |
| 174 | +[#1460]: https://github.com/google/docsy/issues/1460 |
| 175 | +[#1500]: https://github.com/google/docsy/pull/1500 |
| 176 | +[#1744]: https://github.com/google/docsy/pull/1744 |
| 177 | +[#1812]: https://github.com/google/docsy/issues/1812 |
| 178 | +[#1814]: https://github.com/google/docsy/issues/1814 |
| 179 | +[#1815]: https://github.com/google/docsy/pull/1815 |
| 180 | +[#1817]: https://github.com/google/docsy/pull/1817 |
| 181 | +[#1818]: https://github.com/google/docsy/pull/1818 |
| 182 | +[#1820]: https://github.com/google/docsy/issues/1820 |
| 183 | +[#1841]: https://github.com/google/docsy/issues/1841 |
| 184 | +[#1852]: https://github.com/google/docsy/issues/1852 |
| 185 | +[#2]: https://github.com/google/docsy/issues/2 |
| 186 | +[blocks/feature]: |
| 187 | + https://www.docsy.dev/docs/adding-content/shortcodes/#blocksfeature |
| 188 | +[[email protected]]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#090 |
| 189 | +[functions]: https://gohugo.io/functions/ |
| 190 | +[hook]: https://gohugo.io/templates/render-hooks/ |
| 191 | +[Hugo 0.112.0]: https://github.com/gohugoio/hugo/releases/tag/v0.112.0 |
| 192 | +[language parameter]: |
| 193 | + https://www.docsy.dev/docs/language/#internationalization-bundles |
| 194 | +[Lisa]: https://github.com/LisaFC |
| 195 | +[mounts]: |
| 196 | + https://gohugo.io/hugo-modules/configuration/#module-configuration-mounts |
| 197 | +[path_base_for_github_subdir]: |
| 198 | + https://www.docsy.dev/docs/adding-content/repository-links/#path_base_for_github_subdir-optional |
| 199 | +[0.9.0]: https://github.com/google/docsy/releases/tag/v0.9.0 |
| 200 | +[repository links]: https://www.docsy.dev/docs/adding-content/repository-links/ |
| 201 | +[tmpl-func]: |
| 202 | + https://discourse.gohugo.io/t/hugo-v0-112-0-new-template-functions/44512 |
| 203 | +[v0.8.0...v0.9.0]: https://github.com/google/docsy/compare/v0.8.0...v0.9.0 |
| 204 | + |
| 205 | +[^1]: Sizable by Docsy-release standards |
0 commit comments