diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 51f10656b9..4c09eaef50 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -13,5 +13,6 @@ globs: # - docsy.dev/content/en/docs/content/search.md # - docsy.dev/content/en/docs/content/shortcodes.md # - docsy.dev/content/en/docs/content/versioning.md + - docsy.dev/content/en/blog/2025/0.13.0.md config: extends: .markdownlint.yaml diff --git a/docsy.dev/.htmltest.yml b/docsy.dev/.htmltest.yml index 66fddac18c..109ddc5292 100644 --- a/docsy.dev/.htmltest.yml +++ b/docsy.dev/.htmltest.yml @@ -25,6 +25,3 @@ IgnoreURLs: # list of regexs of paths or URLs to be ignored # Too flaky or unnecessary - ^https://badges.netlify.com/api - ^https://code.jquery.com - # TODO: remove once the 0.130.0 is released - - ^https://www.docsy.dev/blog/2025/0.13.0/.+ - - ^/blog/2025/0.13.0/# diff --git a/docsy.dev/content/en/blog/2025/0.12.0.md b/docsy.dev/content/en/blog/2025/0.12.0.md index b6765f9e7a..40014a4b55 100644 --- a/docsy.dev/content/en/blog/2025/0.12.0.md +++ b/docsy.dev/content/en/blog/2025/0.12.0.md @@ -268,6 +268,8 @@ Other references: - [0.11.0 release highlights](../2024/year-in-review/#release-highlights) - [0.11.0 changelog](/site/changelog/#v0110) - [Docsy issue #2243][#2243], _Adapt to new template system in Hugo v0.146.0_. +- [0.13.0 release report and upgrade guide](/blog/2025/0.13.0/) — for upgrading + from 0.12.0 to 0.13.0 [#2243]: https://github.com/google/docsy/issues/2243 [NTS]: https://gohugo.io/templates/new-templatesystem-overview/ diff --git a/docsy.dev/content/en/blog/2025/0.13.0.md b/docsy.dev/content/en/blog/2025/0.13.0.md index 6afca55748..1548aa88d7 100644 --- a/docsy.dev/content/en/blog/2025/0.13.0.md +++ b/docsy.dev/content/en/blog/2025/0.13.0.md @@ -1,15 +1,445 @@ --- title: Release 0.13.0 report and upgrade guide linkTitle: Release 0.13.0 -date: 2025-11-14 +date: 2025-11-24 author: >- [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), for the [Docsy Steering Committee](/blog/2022/hello/#introducing-the-psc) -message: This is a test message. -cSpell:ignore: Chalin docsy markdownify +message: Hello, world! body_class: published-draft-post release-highlights +params: + # Icon usage: {{% _param FA iconName color %}} + BREAKING: + + NEW: + FA: + FA_LG: + # Badge usage: {{% _param BADGE text color %}} + BADGE: {1} tags: [release] +cSpell:ignore: Chalin docsy markdownify FOUC lookandfeel mhchem katex notoc --- - Coming soon! - + + +{{% card header="Highlights" %}} + +- {{% _param FA_LG fire warning %}} Docsy [0.13.0] includes the **_[most + upvoted][]_ enhancement** [request of 2025][], and more. +- {{% _param FA_LG check success %}} This release has new features and + only + [minor breaking changes](#breaking-changes).[^explain-report-format] +- {{% _param FA_LG robot info %}} Read about + [our experiences](#upgrading-and-ai) using AI to + [upgrade Docsy projects](#upgrade). + +{{% /card %}} + +[^explain-report-format]: + Hence this post is a release report rather than only an upgrade guide. + +[most upvoted]: #active-toc-entry-tracking +[request of 2025]: + https://github.com/google/docsy/issues?q=is%3Aissue%20state%3Aclosed%20sort%3Areactions-%2B1-desc%20closed%3A2025-01-01..2025-12-31 + +## Release summary + +Docsy [0.13.0] comes with the following notable features and fixes: + +- {{% _param FA compass "" %}} [Navigation and UX](#navigation-and-ux) + improvements including the **_most upvoted_ enhancement** [request of 2025][]: + [Active TOC entry tracking](#active-toc-entry-tracking) ([#349], [#2289]) +- {{% _param FA code "" %}} [Alert shortcode](#alert-shortcode) rewrite for + better Markdown support +- {{% _param FA universal-access "" %}} [Accessibility](#accessibility) + enhancements for better color contrast and dark mode support + +## Ready to upgrade? {#ready-to-upgrade} + +- Review {{% _param BADGE BREAKING warning %}} changes: + - {{% _param BREAKING %}} [Alert shortcode](#alert-shortcode) body content + processing changes + - {{% _param BREAKING %}} [Language menu](#language-menu-visibility) + visibility changes +- Optionally skim: + - {{% _param NEW %}} New features + - [Other notable changes](#other-notable-changes) +- {{% _param FA rocket primary %}} When you’re ready, jump to + [Upgrade to 0.13.0](#upgrading-and-ai). + +## {{% _param FA compass "" %}} Navigation and UX improvements {#navigation-and-ux} + +### {{% _param NEW %}} Active TOC entry tracking {#active-toc-entry-tracking} + +Docsy 0.13.0 introduces _active table of contents (TOC) entry tracking_, the +**most upvoted** enhancement [request of 2025][]. This feature highlights the +TOC entry corresponding to the page's section that is currently in view. The +feature is implemented using (a [patched] version of) Bootstrap’s [ScrollSpy][]. +The new default TOC labels “On this page” and “Top of page” are localizable. For +details, see [Active TOC entry tracking with ScrollSpy][]. + +[Active TOC entry tracking with ScrollSpy]: + /docs/content/navigation/#toc-entry-tracking +[ScrollSpy]: https://getbootstrap.com/docs/5.3/components/scrollspy/ +[patched]: /site/implementation/scrollspy-patch/ + +{{% alert title="Want to hide the TOC?" color="info" %}} + +The `notoc` page parameter (available since 2016, [now documented][#2405]) hides +the TOC for specific pages. For details, see [TOC customization][]. + +[#2405]: https://github.com/google/docsy/pull/2405 + +{{% /alert %}} + +[TOC customization]: /docs/content/navigation/#toc-customization + +### {{% _param NEW %}} Section sidebar root {#section-sidebar-root} + +Docsy 0.13.0 introduces the `sidebar_root_for` configuration option, which +allows you to scope sidebar navigation to specific sections. This is +particularly useful for large sites where you want different navigation trees +for different sections, and [docs-only] sites that also have non-docs sections. + +To enable this feature, add `sidebar_root_for` to your page front matter. +Supported parameter values are `children` and `self`. For details and examples, +see the [Section sidebar root][] documentation; for implementation details, see +[#2328] and PR [#2364]. + +[docs-only]: /docs/content/adding-content/#alternative-site-structure +[Section sidebar root]: /docs/content/navigation/#sidebar-root +[#2364]: https://github.com/google/docsy/pull/2364 + +### {{% _param BREAKING %}} Language menu visibility {#language-menu-visibility} + +Prior to Docsy 0.13.0, the [language selector menu][lang-menu] was shown for +multilingual sites in both the navbar and the sidebar, depending on the viewport +width according to the following table: + +| Location | Wide viewport | Narrow viewport | +| ----------- | :-----------: | :-------------: | +| **Navbar** | Visible | Hidden | +| **Sidebar** | Hidden | Visible | + +The change in visibility was triggered by the Bootstrap `lg` breakpoint (the +point where layouts switch between wide and narrow). + +The new visibility under 0.13.0 is as follows for all viewport widths: + +| Location | All viewport widths | +| ----------- | :-----------------: | +| **Navbar** | Visible | +| **Sidebar** | Hidden | + +This is a {{% _param BADGE BREAKING warning %}} UX change. You can recover +legacy behavior as follows: + +- **Navbar**: add the following SCSS (or equivalent) to your project’s styles to + restore the previous `d-none d-lg-block` behavior: + + ```scss + .td-navbar__lang-menu { + @extend .d-none; + @extend .d-lg-block; + } + ``` + +- **Sidebar**: set the optional parameter `.ui.sidebar_lang_menu` to `true` in + your site configuration. + +To learn more about the language menu, see [Adding a language menu][lang-menu]. +For implementation details, see [#2035], [#2001], and PR [#2303]. + +[lang-menu]: /docs/content/navigation/#language-menu +[#2303]: https://github.com/google/docsy/pull/2303 + +### Mobile navbar scroll indicators + +The navbar now shows left/right scroll indicators when the navigation menu +overflows (mainly for narrow viewports), making it easier for users to discover +additional navigation items ([#2406]). + +[#2406]: https://github.com/google/docsy/pull/2406 + +## {{% _param FA code "" %}} Alert shortcode improvements {#alert-shortcode} + +As of Docsy 0.13.0, `alert` shortcode content is processed differently when +called as Markdown (`{{%/* alert */%}}`): the inner Markdown is now passed +through to the page’s Markdown renderer and processed along with the rest of the +page content. Previously, the shortcode used Hugo’s `markdownify` function +internally. + +This change means that your alerts can now: + +- Contain calls to other shortcodes, that is, **nested shortcode** calls +- Contain and share **link definitions** from or with other parts of the page +- Be used in lists and other **indented contexts** +- Include **headings** that appear in the page TOC (for `docs` pages) + +For details and examples, including important formatting requirements, see +[alert]. For implementation details, see PR [#941]. + +## {{% _param FA universal-access info %}} Accessibility improvements {#accessibility} + +- **Color contrast** + has been improved throughout the theme, and Docsy now falls back to Bootstrap + defaults for typography and color. This ensures better accessibility + compliance out of the box. For details, see [#2285] and [Site colors][]. + +- {{% _param FA palette info %}} **Color contrast** improvements for dark mode: + - TOC entry color contrast has been fixed when user preferences differ from + system settings ([#2379]). + + - Early experimental support for customizable color-contrast adjustments for + projects using Bootstrap's theme variables ([#2384]). For details, see [How + to pick colors with good color-contrast][]. + {{% _param BADGE EXPERIMENTAL info %}} + +- {{% _param FA moon info %}} **[Dark mode][]**: + - {{% _param FA bolt warning %}} [Flash Of Unstyled Content][] (FOUC) has been + fixed ([#2332]). + - {{% _param FA search info %}} **Google search** results page now supports + dark-mode ([#2387]). {{%_param BADGE EXPERIMENTAL info %}} + + {{% alert title="Dark mode quick reference" color="secondary" %}} + + To opt into all [dark mode][] features (including experimental ones), add the + following imports to your [\_styles_project.scss][project-style-files]. For + details, see [Light/dark color modes][]. + + ```scss + // Dark mode enhancements + @import 'td/color-adjustments-dark'; + @import 'td/code-dark'; + @import 'td/gcs-search-dark'; + ``` + + {{% /alert %}} + +[dark mode]: /docs/content/lookandfeel/#lightdark-color-modes +[Light/dark color modes]: /docs/content/lookandfeel/#lightdark-color-modes +[#2001]: https://github.com/google/docsy/issues/2001 +[#2035]: https://github.com/google/docsy/issues/2035 +[#2285]: https://github.com/google/docsy/issues/2285 +[#2289]: https://github.com/google/docsy/issues/2289 +[#2328]: https://github.com/google/docsy/issues/2328 +[#2332]: https://github.com/google/docsy/issues/2332 +[#2379]: https://github.com/google/docsy/pull/2379 +[#2384]: https://github.com/google/docsy/pull/2384 +[#2387]: https://github.com/google/docsy/pull/2387 +[#2394]: https://github.com/google/docsy/pull/2394 +[#2395]: https://github.com/google/docsy/pull/2395 +[Flash Of Unstyled Content]: + https://en.wikipedia.org/wiki/Flash_of_unstyled_content +[How to pick colors with good color-contrast]: + /docs/content/lookandfeel/#pick-good-color-contrast +[project-style-files]: /docs/content/lookandfeel/#project-style-files +[Site colors]: /docs/content/lookandfeel/#site-colors + +## Other notable changes + +- **New `_param` shortcode**: A new private shortcode for parameter substitution + in templates, useful for dynamic content generation. See PR [#2371] for + details. + +- **Better NPM support**: Projects using [Docsy via NPM] will no longer face + optional and peer dependency issues ([#2115]). + +- **Translations** (**i18n**): Occitan locale has been added ([#2173]), and + Simplified Chinese ([#2313]) and Ukrainian ([#2331]) [translation files][] + have been refreshed. + +- **Mathematical and chemical formulae**: Docsy now uses Hugo's embedded KaTeX + engine for build-time rendering. The `mhchem` extension is now built-in. For + details, see [LaTeX support with KaTeX][diagrams-formulae] ([#2276], [#2394], + [#2395]). + + The KaTeX engine auto-activates when formulae are encountered; no + configuration needed, so projects can remove the following obsolete site + configuration: `params.katex.*`. Subfields include `enable`, + `html_dom_element`, `options`, and `mhchem`. + +[#2371]: https://github.com/google/docsy/pull/2371 +[#2276]: https://github.com/google/docsy/pull/2276 +[Docsy via NPM]: + /docs/get-started/other-options/#option-3-docsy-as-an-npm-package +[translation files]: /docs/language/#internationalization-bundles +[diagrams-formulae]: + /docs/content/diagrams-and-formulae/#latex-support-with-katex + +## {{% _param FA rocket primary %}} Upgrade to 0.13.0 {#upgrade} + +### Prerequisites + +> {{% _param FA triangle-exclamation warning %}} **We recommend** that you +> [Upgrade to Docsy 0.12.0][] first because it contains significant breaking +> changes. + +### Upgrade procedure and AI help {#upgrading-and-ai} + +> {{% _param FA robot info %}} Have you used AI to help you upgrade Docsy? It +> can be a big help! + +The [0.12.0 upgrade guide][] was written with both human project maintainers and +AI assistants in mind. In fact, I've successfully used it to upgrade projects +like [The Update Framework](https://theupdateframework.io) website. That is, +using only the upgrade guide as input, an AI assistant created [TUF PR #126] +fully autonomously. All I had to do was review it. + +[0.12.0 upgrade guide]: /blog/2025/0.12.0/ +[TUF PR #126]: + https://github.com/theupdateframework/theupdateframework.io/pull/126 + +To upgrade from [0.12.0] to [0.13.0], follow the same steps as described in +[Upgrade to Docsy 0.12.0 from 0.11.0][upgrade-0.12], but use version 0.13.0 +instead: + +- **Docsy**: [0.12.0] → [0.13.0]
Includes **Bootstrap**: 5.3.6 → 5.3.8 +- **Hugo**: 0.147.5 → 0.152.2 [^vers-note] +- **Node**: LTS 22 → LTS 24 [^vers-note] + +[^vers-note]: + These are the officially supported Node.js and Hugo versions associated with + the named Docsy versions. Later versions may work, but are not officially + supported. + +After upgrading, review the [breaking changes](#breaking-changes) and test your +site thoroughly. For a testing checklist, see the [Upgrade to Docsy +0.12.0][upgrade-0.12] guide. + +{{% alert title="Hugo 0.152.0 and 0.152.1 are not supported" color="warning" %}} + +Hugo 0.152.0 or 0.152.1 are not compatible with Docsy 0.13.0 ([#2347]); use Hugo +0.152.2 or later. + +{{% /alert %}} + +[#2347]: https://github.com/google/docsy/issues/2347 + +## What's next? + +There are exciting enhancements planned for 2026[^2026-enhancements]! + +For general work items _tentatively_ planned for the next release, or to track +our progress, see [Release 0.14.0 preparation (#2404)][#2404]. Some of the +currently _most upvoted_ enhancement requests include: + +- [Repository / page-meta link fixes and improvements (#1841)][#1841], + particularly for [GitLab support (#375)][#375] +- [Drop jQuery (#1436)][#1436] + +[^2026-enhancements]: + We will post here when we have more details to share or update [#2404]. + +{{% alert title="Your opinion counts!" color="info _list-unstyled" %}} + +- {{% _param FA thumbs-up success %}} If you'd like a feature or fix to be + considered for inclusion in an upcoming release, **upvote** (with a thumbs up) + the associated issue or PR. + +- {{% _param FA star warning %}} If you find Docsy useful, consider [starring + the repository][] to show your support. + +{{% /alert %}} + +[starring the repository]: https://github.com/google/docsy +[#1436]: https://github.com/google/docsy/issues/1436 +[#1841]: https://github.com/google/docsy/issues/1841 +[#2404]: https://github.com/google/docsy/issues/2404 +[#375]: https://github.com/google/docsy/issues/375 + +## References + +About this release: + +- [0.13.0 **changelog**][CL@0.13.0] entry +- [0.13.0 **release**][0.13.0] page +- [Release 0.13.0 preparation **issue** (#2266)][#2266] + +Other references: + +- [0.12.0 upgrade guide](/blog/2025/0.12.0/) +- For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see the + [Hugo release notes](https://github.com/gohugoio/hugo/releases). + +[#349]: https://github.com/google/docsy/issues/349 +[#941]: https://github.com/google/docsy/pull/941 +[#2115]: https://github.com/google/docsy/issues/2115 +[#2173]: https://github.com/google/docsy/issues/2173 +[#2266]: https://github.com/google/docsy/issues/2266 +[#2313]: https://github.com/google/docsy/issues/2313 +[#2331]: https://github.com/google/docsy/issues/2331 +[0.12.0]: /site/changelog/#v0120 +[0.13.0]: https://github.com/google/docsy/releases/v0.13.0 +[alert]: /docs/content/shortcodes/#alert +[CL@0.13.0]: /site/changelog/#v0130 +[upgrade-0.12]: /blog/2025/0.12.0/ +[Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/ diff --git a/package.json b/package.json index d6773832ef..0bf9a563bf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docsy", - "version": "0.13.0-dev+79-gf59cbb8", + "version": "0.13.0-dev+81-g15a3823", "repository": "github:google/docsy", "homepage": "https://www.docsy.dev", "license": "Apache-2.0",