# Release 0.15.0 report and upgrade guide

> Release report and upgrade guide for Docsy 0.15.0, covering agent support, doc-rooted sites, version menus, community and footer links, and card shortcode rendering.

---

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

---

<!-- markdownlint-disable no-space-in-emphasis -->

<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-robot text-info fa-lg"></i> <span>**[Agent support](#agent-support)**:
  `llms.txt`, Markdown page output, and a "View Markdown" page-meta link</span>
- <i class="fa-solid fa-diagram-project text-success fa-lg"></i>
  <span>**[Doc-rooted sites](#doc-rooted-sites)**: improved support for
  publishing docs at the site root</span>
- <i class="fa-solid fa-code-branch text-primary fa-lg"></i>
  <span>**[Version menus](#version-menu)**: richer entries and updated navbar
  rendering</span>

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


## Release summary

- **[Agent support](#agent-support)** (experimental):
  - Generated `llms.txt`
  - Markdown page output
  - "View Markdown" page-meta link
- **[Doc-rooted sites](#doc-rooted-sites)** (experimental): documented pattern
  and example variant for sites whose `docs` section is published at the site
  root
- **[Version menu entries](#version-menu)**: headings, separators, per-entry
  page-link behavior, and kind-specific styling
- **Content, shortcodes, and internationalization**:
  - [Community and footer links](#community-footer-links)
  - [`card` shortcode rendering](#card-shortcode)
  - [Internationalization](#internationalization) additions and updates

## 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>
    [Community and footer links](#community-footer-links)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Version menu entries](#version-menu)
  - <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> [Card shortcode rendering](#card-shortcode) (low
    risk)
- Optionally skim:
  - <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> New features (look for the green checkmark icon)
  - <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Cleanup / improvement opportunities (look for this
    icon)
  - [Other notable changes](#other-notable-changes)
- <i class="fa-solid fa-rocket text-primary px-1"></i> Jump to [Upgrade to 0.15.0](#upgrade) once
  you are ready

## <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Agent support {#agent-support}

Release 0.15.0 includes the [phase 1][#2614] implementation of agent support,
which provides opt-in features that help AI agents and automated tools discover
and use your site content, including:

- `llms.txt`
- Markdown alternate outputs for home, section, and page content.
- A _View Markdown_ page-meta link when a Markdown page alternative exists.

To learn more, including configuration details on how to enable agent support
for your site, see [Agent support][]. This feature is [experimental][].

> To track the phased evolution of the agent-support feature, see [Improve
> support for AI-agent doc consumption #2614][#2614].

[#2614]: https://github.com/google/docsy/issues/2614
[Agent support]: /docs/content/agent-support/

## <i class="fa-regular fa-wand-magic-sparkles fa-lg text-info px-1"></i> Doc-rooted sites {#doc-rooted-sites}

Docsy provides new and improved support for _doc-rooted_ sites. That is, sites
whose `docs` section is published at the site root instead of under `/docs/`.
This is useful when your site is primarily documentation and you want shorter
URLs such as `/get-started/` instead of `/docs/get-started/`.

Doc-rooted sites also support having non-docs sections at the site root, such as
a blog or community page. For details, see [Doc-rooted sites][] and visit the
[Doc-rooted example][] variant of this site. This feature is [experimental][].

### Actions {#doc-rooted-sites-actions}

**Applies if** your project uses an older docs-only configuration based on front
matter `cascade` or `type` changes.

- Remove the [older docs-only cascade configuration][old-docs-only-config].
- Use Hugo `permalinks` configuration for the `docs` section as described in
  [Doc-rooted sites][].
- Check for path conflicts with `hugo --printPathWarnings`. With the proper
  setup, there should be no conflicts.

[old-docs-only-config]:
  https://web.archive.org/web/20260216125700/https://www.docsy.dev/docs/content/adding-content/#alternative-site-structure

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Version menu entries {#version-menu}

Docsy's navbar [version menu][] now has richer entry handling so your site can
use text headings, separators, per-entry page-link behavior, and kind-specific
styling for menu entries. For configuration details, see [Adding a version
drop-down menu][].

Existing simple `version` and `url` entries continue to work. The change is
potentially breaking if your project customizes the version menu partial, CSS,
or mobile navbar layout: the menu uses updated markup and classes, and it is no
longer hidden on smaller viewports.

### Actions {#version-menu-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your project configures `params.versions`
and customizes the version menu or navbar.

- Review custom CSS that targets the version menu dropdown.
- If you maintain a local `layouts/_partials/navbar-version-selector.html` or
  `layouts/_partials/navbar.html` override, diff it against the [v0.15.0 navbar
  partials][].
- Recheck the navbar on both desktop and mobile viewports.

For configuration and styling details, see the [Version menu][] and [Adding a
version drop-down menu][].

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Community and footer links {#community-footer-links}

New behavior and fixes:

- Footer links support `rel` attributes, see [Adding a community page][]
  ([#2576][]).
- Community and footer links now open in a new browser target only for external
  links, fixing [#2133][] ([#2576][]).
- Site-local community and footer links resolve under any [permalinks][] scheme
  ([#2580][]).

[permalinks]: https://gohugo.io/configuration/permalinks/

Breaking change:

- For multilingual sites, link paths are now interpreted as site-relative paths.
  ([#2580][]).

### Actions {#community-footer-links-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your multilingual site configures
community or footer links with site-local paths.

- Review `params.links.user` and `params.links.developer` path values. For each,
  determine whether the path should target the default language or be site
  (locale) relative.
- If the path should be site-relative, leave the path as is.
- If the path should target the default-language site (paths that live under the
  default language prefix), add that prefix -- for example `/en/community/`
  instead of `/community/`.

  > [!NOTE]
  >
  > If your default language is served at the site root, for example with
  > `defaultContentLanguageInSubdir: false` or a site-matrix/default-language
  > fallback setup, a path like `/community/` may already point at the default
  > language. Only add the language prefix when the prefixed URL exists and is
  > the canonical target you want.

- Recheck generated community and footer links in each language to ensure they
  target the desired site.

## <i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> / <i class="fa-regular fa-square-check fa-lg text-success px-1"></i> Card shortcode rendering {#card-shortcode}

> [!NOTE] **TL;DR** - low-risk of breaking
>
> Technically, `card` arguments are now rendered using [.Page.RenderString][]
> instead of [markdownify][]. We do not expect this change to be breaking, but
> if something breaks, please let us know by [opening an issue][new-issue].

While the [card shortcode][] has always supported Markdown content in its
arguments, the arguments are now rendered in the context of the page that
includes the `card`. This means that argument values (Markdown) resolve in the
page context, which allows:

- Relative link paths can be used in `card` argument Markdown
- Markdown render hooks will fire in the page context

Relative link paths are an important capability to have in [multilingual
sites][]. Executing render hooks in a page context allows for more flexible hook
behavior.

For example, the following `card` footer argument illustrates the use of a
relative path to an image page-bundle resource:

```go-html-template
{{< card
  header="**Imagine**" ...
  footer="![John's signature](card-pane/john-lennon-signature.png)"
>}}
...
{{< /card >}}
```

For the complete example, see [card shortcode][].

### Actions {#card-shortcode-actions}

<i class="fa-solid fa-triangle-exclamation fa-lg text-warning px-1"></i> **Applies if** your project uses the [card.html][]
shortcode or maintains a custom override.

- Ensure that cards still render as expected.
- Update your site's `card` override if you want to take advantage of new
  capabilities.

## Other notable changes {#other-notable-changes}

### <i class="fa-solid fa-globe text- px-1"></i> Internationalization {#internationalization}

Summary of changes:

- Translation files for the following locales have been created or updated:
  - Azerbaijan: new ([#2082][], [#2604][]).
  - Romanian: new ([#2583][], [#2603][]).
  - German: added alert-label translations ([#2591][]).
- Baseline translations for the new "View Markdown" label ([#2602][]).

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

> <i class="fa-solid fa-robot text-info px-1"></i> **Upgrading with AI?** 0.15.0 ships an
> experimental machine-readable [upgrade manifest](/upgrades/0.15.0.yaml) with
> upgrade-detection rules, applies-if gates, sanity checks, and per-item
> references. Use this release report and the manifest as context for your AI
> assistant.

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.15.0** where the guide refers to
0.12.0. For this release, use:[^vers-note]

- **Docsy**: [0.14.3][] → [0.15.0][]
- **Hugo**: [0.155.3][] → [0.157.0][]
- **Node**: LTS 24 (unchanged)

[^vers-note]:
    Matches `docsy.dev` declared `params.hugoMinVersion` and `hugo-extended`.
    Later Hugo or Node versions may work but are not officially supported.

> [!NOTE]
>
> **Need to roll back?** Re-pin Docsy to [0.14.3][] (with Hugo 0.155.3) using
> the standard package-update procedure from [Upgrade to Docsy 0.12.0][],
> applied in reverse.

<section class="td-checkbox-list-wrapper">

### <i class="fa-solid fa-square-check text-primary px-1"></i> Sanity checks

- [ ] **Build your site** locally:
  - Run `hugo` with `--printPathWarnings` if your site is a
    [doc-rooted site](#doc-rooted-sites).
- [ ] [Check community and footer links](#community-footer-links) for
      multilingual sites.
- [ ] [Check the version menu](#version-menu-actions) on desktop and mobile, if
      your site has one.
- [ ] [Check pages that use the `card` shortcode](#card-shortcode-actions).
- [ ] Inspect generated `*.md` and `/llms.txt` pages, if you
      [enabled agent support](#agent-support).

</section>

## What's next?

For general work items _tentatively_ planned for the next release, see [Release
0.16.0 preparation (#2615)][#2615].

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

## References

About this release:

- Changelog entry for [0.15.0][CL@0.15.0]
- Release page for [0.15.0][]
- [Release 0.15.0 preparation issue (#2501)][#2501]

<!-- prettier-ignore-start -->
[.Page.RenderString]: https://gohugo.io/methods/page/renderstring/
[#2082]: https://github.com/google/docsy/pull/2082
[#2133]: https://github.com/google/docsy/issues/2133
[#2501]: https://github.com/google/docsy/issues/2501
[#2576]: https://github.com/google/docsy/pull/2576
[#2580]: https://github.com/google/docsy/pull/2580
[#2583]: https://github.com/google/docsy/pull/2583
[#2591]: https://github.com/google/docsy/pull/2591
[#2602]: https://github.com/google/docsy/pull/2602
[#2603]: https://github.com/google/docsy/pull/2603
[#2604]: https://github.com/google/docsy/pull/2604
[#2615]: https://github.com/google/docsy/issues/2615
[0.14.3]: https://github.com/google/docsy/releases/v0.14.3
[0.15.0]: https://github.com/google/docsy/releases/v0.15.0
[0.155.3]: https://github.com/gohugoio/hugo/releases/tag/v0.155.3
[0.157.0]: https://github.com/gohugoio/hugo/releases/tag/v0.157.0
[Adding a community page]: /docs/content/adding-content/#adding-a-community-page
[Adding a version drop-down menu]: /docs/content/versioning/#adding-a-version-drop-down-menu
[card shortcode]: /docs/content/shortcodes/#shortcode-card-textual-content
[card.html]: https://github.com/google/docsy/blob/v0.15.0/layouts/_shortcodes/card.html
[CL@0.15.0]: /project/about/changelog/#v0.15.0
[Doc-rooted example]: https://doc-rooted--docsydocs.netlify.app
[Doc-rooted sites]: /docs/content/adding-content/#doc-rooted-sites
[experimental]: /project/about/changelog/#experimental
[markdownify]: https://gohugo.io/functions/transform/markdownify/
[multilingual sites]: /docs/language/
[new-issue]: https://github.com/google/docsy/issues/new/choose
[Upgrade to Docsy 0.12.0]: /blog/2025/0.12.0/
[v0.15.0 navbar partials]: https://github.com/google/docsy/tree/v0.15.0/layouts/_partials
[Version menu]: /docs/content/navigation/#version-menu
<!-- prettier-ignore-end -->