# 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 docsy.dev `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.
