# Release 0.13.0 report and upgrade guide

LLMS index: [llms.txt](/llms.txt)

---

<div class="td-card card border me-4">
<div class="card-header">
      Highlights
    </div>
<div class="card-body">
    <p class="card-text">
        

- <i class="fa-solid fa-fire text-warning fa-lg"></i> <span>Docsy [0.13.0] includes the **_[most
  upvoted][]_ enhancement** [request of 2025][], and more.</span>
- <i class="fa-solid fa-check text-success fa-lg"></i> <span>This release has new features and
  only
  [minor breaking changes](#breaking-changes).[^explain-report-format]</span>
- <i class="fa-solid fa-robot text-info fa-lg"></i> <span>Read about
  [our experiences](#upgrading-and-ai) using AI to
  [upgrade Docsy projects](#upgrade).</span>

</p>
      </div>
  </div>


[^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:

- <i class="fa-solid fa-compass text- px-1"></i> [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])
- <i class="fa-solid fa-code text- px-1"></i> [Alert shortcode](#alert-shortcode) rewrite for
  better Markdown support
- <i class="fa-solid fa-universal-access text- px-1"></i> [Accessibility](#accessibility)
  enhancements for better color contrast and dark mode support

## Ready to upgrade? <a id="breaking-changes"></a> {#ready-to-upgrade}

- Review <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span> changes:
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Alert shortcode](#alert-shortcode) body content
    processing changes
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Language menu](#language-menu-visibility)
    visibility changes
- Optionally skim:
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> New features
  - [Other notable changes](#other-notable-changes)
- <i class="fa-solid fa-rocket text-primary px-1"></i> Jump to
  [Upgrade to 0.13.0](#upgrading-and-ai) once you are ready.

## <i class="fa-solid fa-compass text- px-1"></i> Navigation and UX improvements {#navigation-and-ux}

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 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]: /project/implementation/scrollspy-patch/

> [!INFO] Want to hide the TOC?
>
> 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

[TOC customization]: /docs/content/navigation/#toc-customization

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> 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

### <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 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 <span class="badge text-bg-warning rounded-pill text-small">BREAKING</span> 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

### <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Mobile navbar scroll indicators {#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

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> 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].

**Action required**: Applies if you use the `alert` in `.html` content files
with Markdown in the body.

Use Hugo's shortcode [Markdown call syntax][]: `{{% %}}`. Otherwise,
Markdown content might not render correctly.

**Sanity check**: sample the rendering of pages that contain `alert` shortcodes,
whether in Markdown or HTML content files. Ensure that the alert renders as
expected.

[Markdown call syntax]:
  https://gohugo.io/content-management/shortcodes/#notation

## <i class="fa-solid fa-universal-access text-info px-1"></i> Accessibility improvements {#accessibility}

- <i class="fa-solid fa-palette fa-lg text-info px-1"></i> **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][].

- <i class="fa-solid fa-palette text-info px-1"></i> **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][].
    <span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>

- <i class="fa-solid fa-moon text-info px-1"></i> **[Dark mode][]**:
  - <i class="fa-solid fa-bolt text-warning px-1"></i> [Flash Of Unstyled Content][] (FOUC) has
    been fixed ([#2332]).
  - <i class="fa-solid fa-search text-info px-1"></i> **Google search** results page now supports
    dark-mode ([#2387]). <span class="badge text-bg-info rounded-pill text-small">EXPERIMENTAL</span>

  > [!SECONDARY] Dark mode quick reference
  >
  > 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';
  > ```

[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

- **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.

- **New `_param` shortcode**: A new experimental shortcode for parameter
  substitution in templates, useful for dynamic content generation. See PR
  [#2371] for details.

- **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

## <i class="fa-solid fa-rocket text-primary px-1"></i> Upgrade to 0.13.0 {#upgrade}

### Prerequisites

> <i class="fa-solid fa-triangle-exclamation text-warning px-1"></i> **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}

> <i class="fa-solid fa-robot text-info px-1"></i> 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.

[TUF PR #126]:
  https://github.com/theupdateframework/theupdateframework.io/pull/126

Some upgrade steps are the same for each Docsy release (for example, updating
your Docsy NPM package or Hugo module). Those steps are described in [Upgrade to
Docsy 0.12.0][]: follow them, using version **0.13.0** where the guide refers to
0.12.0. For this release, use:

- **Docsy**: [0.12.0] → [0.13.0]<br> Includes **Bootstrap**: 5.3.6 → 5.3.8
- **Hugo**: 0.147.5 → 0.152.2&nbsp;[^vers-note]
  > [!NB] See [Hugo 0.152.0 **breaking changes**][hugo-0.152.0].
- **Node**: LTS 22 → LTS 24&nbsp;[^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][]
guide.

> [!WARNING] Hugo 0.152.0 and 0.152.1 are not supported
>
> Hugo 0.152.0 or 0.152.1 are not compatible with Docsy 0.13.0 ([#2347]); use
> Hugo 0.152.2 or later.

[#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].

<!-- prettier-ignore -->
> [!INFO] Your opinion counts!
>
> - <i class="fa-solid fa-thumbs-up text-success px-1"></i> 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.
> - <i class="fa-solid fa-star text-warning px-1"></i> If you find Docsy useful, consider [starring
>   the repository][star-the-repo] to show your support.
{._list-unstyled}

[star-the-repo]: 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][]
- For Hugo upgrade considerations when moving from 0.147.5 to 0.152.2, see:
  - [Hugo 0.152.0 breaking changes][hugo-0.152.0], our companion post
  - The official [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]: /project/about/changelog/#v0.12.0
[0.13.0]: https://github.com/google/docsy/releases/v0.13.0
[alert]: /docs/content/shortcodes/#alert
[CL@0.13.0]: /project/about/changelog/#v0.13.0
[Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/
[0.12.0 upgrade guide]: /blog/2025/0.12.0/
[hugo-0.152.0]: /blog/2026/hugo-0.152.0+/#0.152.0

> [!NB] **Last updated** 2026-02-07