-
Notifications
You must be signed in to change notification settings - Fork 916
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Rework and completion of 0.9.0 release report
- Loading branch information
Showing
1 changed file
with
74 additions
and
21 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,42 +10,83 @@ date: 2024-02-09 | |
| 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: | ||
| Docsy [0.9.0] is a sizable[^1] release ([containing 50+ 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 style | ||
| `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 resolved **_the_ longest standing and first ever issue | ||
| created** over Docsy! | ||
| created** in 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]. | ||
| 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`] option will be | ||
| used and rendered as markdown, "as is" — with no year is 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] for all your site's | ||
| languages: | ||
| ```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 the presence of a homepage or not. | ||
| support, or if 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 the [Hugo 0.112.0] release in May 2023 | ||
| 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] | ||
|
|
@@ -59,18 +100,25 @@ 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. | ||
| addressed in a future release through further layout refactoring and extension. | ||
|
|
||
| ### Last-modified page info | ||
|
|
||
| Repository links grant access to page meta information. Page last-modified ... | ||
| XXXXXXXX | ||
| 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], in favor of client-side rendering via | ||
| `assets/js/anchor.js` — which has been dropped ([#1460]). | ||
| `render-heading.html` [hook], replacing client-side rendering via | ||
| `assets/js/anchor.js` (dropped in [#1460]). Projects must now explicitly enable | ||
| the feature. | ||
|
|
||
| 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 | ||
|
|
@@ -80,14 +128,14 @@ now: | |
| - Always visible on mobile and touch devices | ||
| - Otherwise the link is invisible until the user hovers over the heading | ||
|
|
||
| ### Links are underlined | ||
| ### 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 | ||
|
|
||
| Finally, the [blocks/feature] shortcode no longer includes ellipsis after the | ||
| 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]). | ||
|
|
||
|
|
@@ -123,14 +171,15 @@ specifically: | |
| [#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 | ||
| [0.9.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#090 | ||
| [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 | ||
|
|
@@ -141,6 +190,10 @@ specifically: | |
| 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 | ||