Blog 2024 year in review (#2145)

Author: chalin

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

@@ -3,8 +3,7 @@ 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)
+  for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
 date: 2024-05-01
 # prettier-ignore
 cSpell:ignore: CNCF Chalin subdir deprecat upvoted pageinfo lookandfeel lightdark
@@ -39,9 +38,9 @@ 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.
+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.
@@ -87,14 +86,15 @@ had their styles adjusted as well.
 
 ## Release details
 
-For the complete list of changes in this release, see the [0.10.0] release entry
-and issue
+For the complete list of changes in this release, including updates to
+FontAwesome, Mermaid, Algolia, and KaTex, 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
+Which Docsy improvements are on the horizon? For work items _tentatively_
+planned for the next release, see
 [Release 0.11.0 preparation (#1944)](https://github.com/google/docsy/issues/1944).
 
 {{% alert title="Vote" color="primary" %}}

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

@@ -3,11 +3,11 @@ 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](/blog/2022/hello/#introducing-the-psc)
+  for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
 date: 2024-02-09
+updated: 2024-12-12
 # prettier-ignore
-cSpell:ignore: CNCF Chalin subdir
+cSpell:ignore: CNCF Chalin subdir sarahmaddox jmooring
 ---
 
 Docsy [0.9.0] is a sizable[^1] release ([containing 65+ PRs][v0.8.0...v0.9.0])
@@ -17,6 +17,7 @@ related to:
 - [Footer improvements](#footer)
 - [Repository links and other page info](#page-meta)
 - [Look and feel](#look-and-feel)
+- [Continuous integration testing](#ci)
 
 Thank you to all [contributors][0.9.0]!
 
@@ -64,8 +65,8 @@ fallback:
   `.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] (optionally
-  with a `!important` modifier — not shown):
+  following to your `_styles_project.scss` [project style file] (optionally with
+  a `!important` modifier — not shown):
   ```scss
   .td-footer__all_rights_reserved {
     display: inline;
@@ -144,6 +145,30 @@ 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]).
 
+## Continuous integration testing {#ci}
+
+To ensure the quality and stability of Docsy, this release introduces a highly
+anticipated developer feature: **continuous integration (CI) testing** support
+through GitHub Actions.
+
+Each PR and main-branch commit triggers ([workflows]):
+
+- Cross-platform tests on Linux and Windows.
+- Build tests to ensure that Docsy and its User Guide build successfully and
+  pass checks, such as link validation.
+- Smoke tests that build a Docsy site from scratch. These tests validate Docsy's
+  use as both a Hugo module and an NPM module.
+
+While Windows support is maintained on a best-effort basis due to limited access
+to Windows environments, running cross-platform tests helps identify potential
+build issues sooner.
+
+This initiative is an important step forward in ensuring the reliability of the
+theme. We plan to [expand test coverage (#726)][#726] in the future.
+
+[#726]: https://github.com/google/docsy/issues/726
+[workflows]: https://github.com/google/docsy/blob/main/.github/workflows
+
 ## References and future releases
 
 For the complete list of changes in this release, see the [0.9.0] release entry

userguide/content/en/blog/2024/year-in-review.md

@@ -0,0 +1,167 @@
+---
+title: 'Docsy 2024 Review: Adoptions and Enhancements'
+linkTitle: '2024 Review: Adoptions and Enhancements'
+date: 2024-12-12
+author: >-
+  [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)),
+  for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc)
+description: >-
+  Celebrating Docsy's 2024 growth in features and adoption, including a 57%
+  usage increase, new features like dark mode, and improved internationalization
+  support.
+# prettier-ignore
+cSpell:ignore: Chalin jaegertracing mentees opentelemetry toto upvoted kubernetes theupdateframework
+---
+
+As we reflect on 2024, it’s exciting to see steady progress toward the goals
+outlined in our [2024 priorities]. This year, we focused on enhancing stability,
+improving internationalization, and delivering long-anticipated features like
+dark mode and continuous integration (CI) testing.
+
+> <i class="fa-solid fa-chart-line"></i> Docsy’s use **increased by 57%** in
+> 2024, from 1.4K to 2.2K projects! [^1]
+
+Let’s dive into the development highlights from 2024 and take a peek at what
+lies ahead.
+
+[2024 priorities]: ../2023/priorities-for-2024/
+[GitHub dependents data]: https://github.com/google/docsy/network/dependents
+
+## Release highlights
+
+We published three releases this year, each focusing on stability while
+introducing at least one major feature enhancement. Highlights include:
+
+- **[0.9.0](https://www.docsy.dev/blog/2024/0.9.0/)** added _long-awaited_:
+  - **CI testing** via GitHub Actions to ensure quality and reliability across
+    Linux and Windows.
+  - **Footer customization** &mdash; Docsy's [longest-standing issue (#2)][#2]!
+    &mdash; as well as improved repository links, and enhanced accessibility and
+    look-and-feel.
+- **[0.10.0](https://www.docsy.dev/blog/2024/0.10.0/):**
+  - Enabled [color themes and **dark mode**][dark mode] via Bootstrap 5.3
+    upgrade, marking the completion of the [Bootstrap 5 migration] started
+    in 2021. Also made adjustments to shortcodes and styles for dark-mode
+    compatibility.
+  - Addressed breaking changes resulting from the major core upgrade to Hugo
+    0.123.0.
+- **[0.11.0](https://github.com/google/docsy/releases/tag/v0.11.0):**
+  - Enhanced internationalization by reintroducing **Right-To-Left (RTL)
+    language support** using Bootstrap's RTL capabilities.
+
+[#2]: https://github.com/google/docsy/issues/2
+[Bootstrap 5 migration]: https://github.com/google/docsy/issues/470
+
+## Major feature enhancements {#enhancements}
+
+In addition to CI testing, a key development feature contributing to Docsy's
+stability, here are the major user-facing enhancements introduced in 2024.
+
+### Dark mode support
+
+[Dark mode] support was the **_most upvoted_ Docsy enhancement** prior to its
+debut in v0.10.0. Powered by Bootstrap 5.3 color themes, this Docsy feature
+includes a built-in light/dark mode menu selector for easy implementation.
+
+We plan on [enabling dark mode] in the [Docsy example], for even easier
+adoption. Dark mode has already been adopted in notable projects like
+OpenTelemetry ([opentelemetry.io#4023]).
+
+[enabling dark mode]: https://github.com/google/docsy-example/issues/285
+[Docsy example]: https://github.com/google/docsy-example
+[opentelemetry.io#4023]:
+  https://github.com/open-telemetry/opentelemetry.io/issues/4023
+
+### Right-To-Left (RTL) language support
+
+[RTL language support (#1933)][#1933], reintroduced through Bootstrap's use of
+the mature and well-vetted [RTLCSS] framework, replaced Docsy's deprecated
+custom RTL solution from 2023.
+
+This enhancement meets longstanding multilingual documentation needs. Notably,
+RTL support has been requested by major Docsy-based sites, including the two
+2024 [top-velocity projects] of the [CNCF]:
+
+- [Kubernetes]:
+  [right-to-left language support #22730](https://github.com/kubernetes/website/issues/22730)
+  - [Localize website into Arabic (ar) #22726](https://github.com/kubernetes/website/issues/22726)
+  - [Localize website into Persian (fa) #22727](https://github.com/kubernetes/website/issues/22727)
+- [OpenTelemetry]:
+  - [Add Persian version of website pages #4990](https://github.com/open-telemetry/opentelemetry.io/issues/4990)
+
+[#1933]: https://github.com/google/docsy/pull/1933
+[CNCF]: https://www.cncf.io
+[dark mode]: 0.10.0/#color-themes-and-dark-mode-support
+[Kubernetes]: https://kubernetes.io
+[OpenTelemetry]: https://opentelemetry.io
+[top-velocity projects]:
+  https://www.cncf.io/blog/2024/07/11/as-we-reach-mid-year-2024-a-look-at-cncf-linux-foundation-and-top-30-open-source-project-velocity/
+[RTLCSS]: https://rtlcss.com/
+
+## Adoptions and the Docsy Starter
+
+One of the most exciting developments in 2024 has been Docsy's growing adoption.
+GitHub analytics show a **57% increase in usage**, reaching **2.2K projects** as
+of this writing.
+
+Adoption among CNCF projects has also grown since our [2023 report]. This year,
+two [Linux Foundation mentees][LFX] used the [CNCF Docsy starter] to migrate the
+following sites to Docsy:
+
+- **[The Update Framework](https://theupdateframework.io)**
+  ([theupdateframework.io#105])
+- **[in-toto](https://in-toto.io)** ([in-toto.io#76])
+
+Additionally, the [Kubernetes website] is undergoing a significant Docsy upgrade
+from v0.2, to align with the latest version and reduce technical debt:
+
+- [Align with upstream Docsy kubernetes.io#41171](https://github.com/kubernetes/website/issues/41171)
+- [Update Docsy step by step to the latest Docsy kubernetes.io#44002](https://github.com/kubernetes/website/issues/44002)
+
+The upgrade is progressing well, as shown in the ongoing efforts documented in
+the [0.3.x upgrade] and [0.5.x upgrade].
+
+[0.3.x upgrade]: https://github.com/kubernetes/website/pull/48721
+[0.5.x upgrade]: https://github.com/kubernetes/website/issues/48807
+[theupdateframework.io#105]:
+  https://github.com/theupdateframework/theupdateframework.io/pull/105
+[CNCF Docsy starter]: https://github.com/chalin/docsy-starter
+[LFX]:
+  https://www.cncf.io/blog/2024/09/27/congratulations-to-45-cncf-term-1-2024-lfx-program-mentees/
+[2023 report]:
+  https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/
+[in-toto.io#76]: https://github.com/in-toto/in-toto.io/issues/76
+[Kubernetes website]: https://github.com/kubernetes/website
+
+## What's ahead?
+
+Looking ahead, we’re excited to continue supporting the Docsy upgrade and
+adoption efforts by projects such as [gRPC (grpc.io#1389)] and [Jaeger
+(jaegertracing#746)].
+
+For features tentatively planned for the first release of 2025, see [Release
+0.12.0 preparation #2108]. The most upvoted enhancement requests are currently:
+[^2]
+
+- [Navigation indication on the right TOC #349](https://github.com/google/docsy/issues/349)
+- [Repository / page-meta link fixes and improvements #1841](https://github.com/google/docsy/issues/1841),
+  particularly for [GitLab](https://github.com/google/docsy/issues/375)
+- [Drop jQuery #1436](https://github.com/google/docsy/issues/1436)
+
+Thank you to all contributors and users who made 2024 a meaningful year for
+Docsy. Wishing you a fantastic end to 2024 and a great start to 2025! Let’s
+continue creating exceptional documentation together.
+
+[^1]: Based on GitHub analytics [Docsy dependents] as of the time of writing.
+
+[^2]:
+    Remember to
+    [vote for your most-desired feature](https://github.com/google/docsy/issues).
+
+[Docsy dependents]: https://github.com/google/docsy/network/dependents
+[cncf-top]:
+  https://www.cncf.io/blog/2024/07/11/as-we-reach-mid-year-2024-a-look-at-cncf-linux-foundation-and-top-30-open-source-project-velocity/
+[gRPC (grpc.io#1389)]: https://github.com/grpc/grpc.io/issues/1389
+[Jaeger (jaegertracing#746)]:
+  https://github.com/jaegertracing/documentation/issues/746
+[Release 0.12.0 preparation #2108]: https://github.com/google/docsy/issues/2108