diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 3e4a324385..58df6480f3 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -2,5 +2,5 @@ { "version": "0.2", "caseSensitive": true, - "words": ["Docsy", "hugo", "shortcode", "shortcodes", "warnf"] + "words": ["Docsy", "hugo", "shortcode", "shortcodes", "upvote", "warnf"] } diff --git a/CHANGELOG.md b/CHANGELOG.md index e751b5c6e3..7f78bf201b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ Useful links: [releases]: https://github.com/google/docsy/releases [tags]: https://github.com/google/docsy/tags -## 0.9.2 or 0.10.0 +## 0.10.1 or 0.11.0 > ### UNRELEASED: this planned version is still under development @@ -26,15 +26,25 @@ For the full list of changes, see the [0.x.y] release notes. **Breaking changes**: -- Removed shortcode `card-code` that was [deprecated in 0.7.0](#070); use - shortcode `card` with named parameter `code=true` instead. - **New**: **Other changes**: [0.x.y]: https://github.com/google/docsy/releases/latest?FIXME=v0.X.Y +## 0.10.0 + +For an introduction to this release, see the [0.10.0 release report]. For the +full list of changes, see the [0.10.0] release notes. + +**Breaking changes**: + +- Removed shortcode `card-code` that was [deprecated in 0.7.0](#070); use + shortcode `card` with named parameter `code=true` instead. + +[0.10.0]: https://github.com/google/docsy/releases/latest?FIXME=v0.10.0 +[0.10.0 release report]: https://www.docsy.dev/blog/?FIXME=2024/0.10.0/ + ## 0.9.1 Patch release. For details, see [0.9.1]. diff --git a/userguide/content/en/blog/2024/0.10.0.md b/userguide/content/en/blog/2024/0.10.0.md new file mode 100644 index 0000000000..6141e4afd8 --- /dev/null +++ b/userguide/content/en/blog/2024/0.10.0.md @@ -0,0 +1,108 @@ +--- +title: Docsy 0.10.0 release report +linkTitle: Release 0.10.0 +author: > + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), + for the [Docsy Steering + Committee](/blog/2022/hello/#introducing-the-psc) +date: 2024-04-30 +# prettier-ignore +cSpell:ignore: CNCF Chalin subdir +--- + +The big news with Docsy [0.10.0] is color themes and dark mode! + +## Hugo: breaking changes and deprecation notices + +In this release, Docsy's Hugo dependency is upgraded to **0.125.4** from +0.122.0. An important thing to note here is that Hugo [0.123.0] was a +significant upgrade that included some **breaking changes**. Before upgrading to +this Docsy version, review Hugo's deprecation notices and breaking changes since +0.122.0. + +[0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 + +{{% alert title="Hugo version support reminder" color="primary" %}} + +Each Docsy version officially **only** supports the Hugo version specified in +the project's [package.json] entry for [hugo-extended]. Any other compatibility +is on a best effort basis. + +[hugo-extended]: https://github.com/jakejarvis/hugo-extended +[package.json]: https://github.com/google/docsy/blob/main/package.json + +{{% /alert %}} + +A number of updates to this release were to address Hugo's deprecation notices. +For the complete list, search for [0.10.0] release changes with "deprecat" in +the title. + +## Color themes and dark-mode support + +The main feature of this release is the [Upgrade to Bootstrap 5.3 #1528][#1528] +from 5.2. This minor Bootstrap release introduces support [color modes], also +called color themes. + +As a validation of this upgrade, Docsy has been enhanced to support [dark mode], +the _most upvoted_ Docsy enhancement request ([#331]) prior to this release. + +To learn how to enable a **light/dark mode dropdown menu** for your project, see +[Light/dark mode menu]. We have enabled this menu for the Docsy [User Guide], so +if you're reading this post online, give dark mode a try! + +[#331]: https://github.com/google/docsy/issues/331 +[#1528]: https://github.com/google/docsy/issues/1528 +[color modes]: https://getbootstrap.com/docs/5.3/customize/color-modes/ +[dark mode]: https://getbootstrap.com/docs/5.3/customize/color-modes/#dark-mode +[Light/dark mode menu]: /docs/adding-content/lookandfeel/#lightdark-mode-menu +[User Guide]: http://localhost:1313/docs/ + +{{% alert title="Important style changes" %}} + +The styling of the following shortcodes and page elements have been adjusted to +ensure that they are compatible with light and dark modes. + +You'll needs to **revisit your styles if you customized the SCSS** associated +with these shortcodes and elements. + +- [`alert`] ([#1908]) +- [`card`] ([#1922]) +- [`pageinfo`] ([#1915]) +- [Tabbed-pane] shortcodes ([#1920]) + +The [search box styling][#1896] as well as the [doc-page left-nav][#1908] have +had their styles adjusted as well. + +[#1896]: https://github.com/google/docsy/pull/1896 +[#1908]: https://github.com/google/docsy/pull/1908 +[#1915]: https://github.com/google/docsy/pull/1915 +[#1920]: https://github.com/google/docsy/pull/1920 +[#1922]: https://github.com/google/docsy/pull/1922 +[`alert`]: /docs/adding-content/shortcodes/#alert +[`card`]: /docs/adding-content/shortcodes/#shortcode-card-programming-code +[`pageinfo`]: /docs/adding-content/shortcodes/#pageinfo +[tabbed-pane]: /docs/adding-content/shortcodes/#tabbed-panes + +{{% /alert %}} + +## Release details + +For the complete list of changes in this release, see the [0.10.0] release entry +and issue +[Release 0.10.0 preparation #1759](https://github.com/google/docsy/issues/1759). + +## What's next? + +Which Docsy improvements are on the horizon? For work items _tentatively_ planed +for the next release, see +[Release 0.11.0 preparation #1944](https://github.com/google/docsy/issues/1944). + +{{% alert title="Vote" color="primary" %}} + +If you'd like a feature or fix to be considered for inclusion in an upcoming +release, remember to upvote (with a thumbs up) the associated issue or PR. + +{{% /alert %}} + +[CL@0.10.0]: https://github.com/google/docsy/blob/main/CHANGELOG.md/#0100 +[0.10.0]: https://github.com/google/docsy/releases/tag/v0.10.0 diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index 21ad83a401..080ec0ad9f 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -274,14 +274,14 @@ of the following: [wordmark]: https://en.wikipedia.org/wiki/Wordmark [your logo]: /docs/adding-content/iconsimages/#add-your-logo -### Light/Dark mode menu +### Light/dark mode menu If you enable this feature, Docsy adds a menu to your navbar that lets users switch your site's documentation page display between a default "light" mode, and a "dark" mode where the text is displayed in a light color on a dark background. -To enable the display of a Light/[Dark mode] menu in the navbar, set +To enable the display of a light/[dark mode] menu in the navbar, set `params.ui.showLightDarkModeMenu` to `true` in your project's configuration file. The dropdown menu appears at the right, immediately before the [search box], if present.