Release 0.15.0 report and upgrade guide

Release summary

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

Ready to Upgrade?

• Review BREAKING changes:
  • Community and footer links
  • Version menu entries
  • Card shortcode rendering (low risk)
• Optionally skim:
  • New features (look for the green checkmark icon)
  • Cleanup / improvement opportunities (look for this icon)
  • Other notable changes
• Jump to Upgrade to 0.15.0 once you are ready

Agent support

Release 0.15.0 includes the phase 1 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.

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

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

/ Version menu entries

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

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.

/ Community and 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).

Breaking change:

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

Actions

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.

/ Card shortcode rendering

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:

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

For the complete example, see card shortcode.

Actions

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

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

Upgrade to 0.15.0

Upgrading with AI? 0.15.0 ships an experimental machine-readable upgrade manifest 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:¹

• Docsy: 0.14.3 → 0.15.0
• Hugo: 0.155.3 → 0.157.0
• Node: LTS 24 (unchanged)

What’s next?

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

References

About this release:

• Changelog entry for 0.15.0
• Release page for 0.15.0
• Release 0.15.0 preparation issue (#2501)

• ←Previous
• Next→