# Docsy upgrade manifest — 0.15.0 # # Machine-readable companion to the 0.15.0 release blog. Lists breaking-style # review items (with detect rules), optional experimental features, and sanity # checks so an agent (or human) can determine applicability and jump back to the # blog, changelog, and user guide. # # Status: experimental. Schema is expected to evolve through 0.16.0+; # see the tracking issue for the planned DRY/data-driven approach. # # Authoritative for: detect predicates, version pins, item ids. # Authoritative narrative remains in the release blog and user guide. schema: docsy-upgrade-manifest/v0 from: 0.14.3 to: 0.15.0 references: blog: /blog/2026/0.15.0/ changelog: /project/about/changelog/#v0.15.0 release: https://github.com/google/docsy/releases/v0.15.0 tag: https://github.com/google/docsy/tree/v0.15.0 peer: hugo: from: '>=0.155.3' to: '>=0.157.0' notes: Matches oink.pgsty.com `params.hugoMinVersion` and `hugo-extended`. node: to: lts/24 notes: Later Node versions may work but are not officially supported. # Breaking changes — items flagged as breaking in the release blog (some also # introduce new behavior; see blog). Low-risk items note that in title or summary. # Each item is gated by a `detect` rule where applicable. breaking: - id: community-footer-multilingual-paths title: community and footer link paths (multilingual) summary: >- For multilingual sites, community and footer link paths (`params.links.user`, `params.links.developer`) are now interpreted as site-relative rather than always resolving under the default language. To force the default-language target, prefix the path with the default language code (e.g. `/en/community/` instead of `/community/`). applies-if: >- Your site is multilingual and configures `params.links.user` or `params.links.developer` with site-local paths. detect: all: - kind: config-multilingual description: Site has more than one language configured. - kind: grep pattern: '^\s*(user|developer)\s*[:=]' paths: [config/, hugo.toml, hugo.yaml, hugo.json] context: under params.links actions: - >- Review each path and decide whether it should be site-relative or target the default language. - >- For default-language targets, prefix with the default-language code (e.g. `/en/community/`). - Recheck generated community/footer links in each language. references: blog: /blog/2026/0.15.0/#community-footer-links user-guide: - /docs/content/adding-content/#adding-a-community-page prs: [2580] - id: version-menu-customization title: version menu markup, classes, and mobile visibility summary: >- The version menu uses updated markup and CSS classes (`.td-navbar__version-menu` wrapper, `.td-version-menu` dropdown, kind-specific classes per entry) and is no longer hidden on smaller viewports. applies-if: >- Your site configures `params.versions` AND customizes the version menu partial, navbar partial, or related CSS. detect: all: - kind: config-key-present path: params.versions - any: - kind: file-exists path: layouts/_partials/navbar-version-selector.html - kind: file-exists path: layouts/partials/navbar-version-selector.html - kind: file-exists path: layouts/_partials/navbar.html - kind: file-exists path: layouts/partials/navbar.html - kind: grep pattern: 'td-(navbar|version-menu)' paths: [assets/] actions: - Review custom CSS that targets the version menu dropdown. - >- Diff local `navbar-version-selector.html` or `navbar.html` overrides against the v0.15.0 partials. - Recheck the navbar on both desktop and mobile viewports. references: blog: /blog/2026/0.15.0/#version-menu user-guide: - /docs/content/versioning/#adding-a-version-drop-down-menu - /docs/content/navigation/#version-menu partials: - https://github.com/google/docsy/tree/v0.15.0/layouts/_partials - https://github.com/google/docsy/blob/v0.15.0/layouts/_partials/navbar-version-selector.html - https://github.com/google/docsy/blob/v0.15.0/layouts/_partials/navbar.html prs: [2557, 2586] - id: card-shortcode-rendering title: Card shortcode rendering (low-risk) summary: >- Markdown in the `header`, `title`, `subtitle`, and `footer` arguments is rendered with `.Page.RenderString` instead of `markdownify`, so it runs in the including page's context. Relative Markdown links (including images) and Markdown render hooks behave like body content—especially useful for multilingual sites. Shortcodes inside those arguments may execute where they previously did not under `markdownify`. Breakage should be rare; see the blog NOTE. applies-if: >- Your project uses the `card` shortcode or maintains a custom `layouts/_shortcodes/card.html` or `layouts/shortcodes/card.html` override. detect: any: - kind: grep pattern: '\{\{[<%][[:space:]]*card\b' paths: [content/, layouts/] - kind: file-exists path: layouts/_shortcodes/card.html - kind: file-exists path: layouts/shortcodes/card.html actions: - Ensure that cards still render as expected. - >- Diff any local `card` override against the v0.15.0 theme partial; update it intentionally if you want page-context resolution, relative paths, or render hooks in those arguments. references: blog: /blog/2026/0.15.0/#card-shortcode user-guide: - /docs/content/shortcodes/#shortcode-card-textual-content partials: - https://github.com/google/docsy/blob/v0.15.0/layouts/_shortcodes/card.html prs: [2565] # Fixes and other user-visible changes that do not require upgrade action. fixes: - id: community-footer-link-target title: community and footer link target attribute summary: >- Community and footer links now open in a new browser target only for external links, fixing site-local links that previously behaved like external links. references: blog: /blog/2026/0.15.0/#community-footer-links user-guide: - /docs/content/adding-content/#adding-a-community-page issues: [2133] prs: [2576] # Experimental features — opt-in; enablement is site-specific. experimental: - id: agent-support-phase-1 title: Agent support (phase 1) summary: >- Opt-in Markdown alternate outputs, a _View Markdown_ page-meta link when a Markdown alternate exists, and generated `llms.txt`. Phased evolution is tracked in https://github.com/google/docsy/issues/2614. references: blog: /blog/2026/0.15.0/#agent-support user-guide: - /docs/content/agent-support/ prs: [2597, 2601, 2605, 2606] # Sanity checks to run after upgrading. These are project-agnostic. sanity: - run: hugo description: >- Build the site locally and surface errors (baseline: release blog sanity checklist). - run: hugo --printPathWarnings description: >- Same as the blog nested bullet under "Build your site locally": use when your site is doc-rooted (see blog Doc-rooted sites section). applies-if: doc-rooted-site - check: For multilingual sites, verify community and footer links (see blog community/footer actions). - check: If `params.versions` is configured, check the version menu on desktop and mobile viewports. - check: Inspect pages that use the `card` shortcode. - check: If agent support is enabled, inspect generated `*.md` pages and `/llms.txt`. # Rollback guidance: pin Docsy to the previous stable release if upgrading # blocks shipping. See: https://github.com/google/docsy/releases/v0.14.3 rollback: docsy: 0.14.3 hugo: '>=0.155.3' notes: >- Re-pin via npm and Hugo module dependencies. See `Upgrade to Docsy 0.12.0` for the standard package-update procedure, applied in reverse.