From ee04669896977f0324182a57441d1add449c7712 Mon Sep 17 00:00:00 2001
From: Michael Harp <mike@mikeharp.com>
Date: Tue, 4 Aug 2026 07:50:02 -0400
Subject: [PATCH 1/3] Add pinned out-of-date banner and /latest/ canonicals for
 versioned docs

Two follow-ups to the multi-version infrastructure, part of #320:

Banner: every page of a frozen (non-latest) doc version gets a notice
pinned to the bottom of the viewport linking to the product's /latest/
docs. Coverage is derived from _data/products.yml, so nothing renders
today; the moment a product gains a new version and its 'latest' key
moves, all pages of the older collections show the banner automatically.
Like the version picker, the banners persist outside the Turbo content
frame and are re-synced on each frame load.

Canonicals: a small Jekyll hook points each numbered-latest page (e.g.
/openvox/8.x/...) at its byte-identical /latest/ twin via
page.canonical_url, which the theme's head.html already honors, so
search engines index the stable /latest/ URLs instead of splitting
ranking across the duplicate pair. Frozen versions keep their default
self-canonical since their content is unique once 'latest' moves on.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
---
 _includes/jekyll_vitepress/layout_end.html | 12 ++++++
 _includes/version-banner.html              | 33 +++++++++++++++++
 _plugins/canonical_latest.rb               | 43 ++++++++++++++++++++++
 assets/css/custom.css                      | 29 +++++++++++++++
 4 files changed, 117 insertions(+)
 create mode 100644 _includes/version-banner.html
 create mode 100644 _plugins/canonical_latest.rb

diff --git a/_includes/jekyll_vitepress/layout_end.html b/_includes/jekyll_vitepress/layout_end.html
index e10e7bf2d..d226f4176 100644
--- a/_includes/jekyll_vitepress/layout_end.html
+++ b/_includes/jekyll_vitepress/layout_end.html
@@ -1,3 +1,4 @@
+{% include version-banner.html %}
 <script>
   (function () {
     function syncSidebarNavGroups() {
@@ -37,10 +38,21 @@
         });
       });
     }
+    // Show the outdated-version banner matching the current collection, if any.
+    // Banners exist only for frozen (non-latest) versions; see version-banner.html.
+    function syncOutdatedBanner() {
+      var frameState = document.getElementById('vp-page-state');
+      if (!frameState) return;
+      var currentCollection = frameState.getAttribute('data-collection') || '';
+      document.querySelectorAll('.VPOutdatedBanner').forEach(function (banner) {
+        banner.hidden = banner.getAttribute('data-collection') !== currentCollection;
+      });
+    }
     document.addEventListener('turbo:frame-load', function (event) {
       if (!event.target || event.target.id !== 'vp-content-frame') return;
       syncSidebarNavGroups();
       syncVersionPicker();
+      syncOutdatedBanner();
     });
   })();
 
diff --git a/_includes/version-banner.html b/_includes/version-banner.html
new file mode 100644
index 000000000..4c7838687
--- /dev/null
+++ b/_includes/version-banner.html
@@ -0,0 +1,33 @@
+{%- comment -%}
+  Viewport-pinned notice shown on every page of a frozen (non-latest) doc
+  version, so readers landing on old bookmarks or search results always see
+  a way to the current docs (#320).
+
+  One banner is emitted per numbered version that is NOT what the product's
+  `latest` alias points at, so coverage is automatic: the moment
+  _data/products.yml gains a new version and `latest` moves, every page of
+  the older collections shows the banner with no per-page front matter.
+  Today every numbered version is its product's latest, so this include
+  renders nothing.
+
+  Like the version picker, the banners live outside the Turbo content frame
+  and persist across navigation: Liquid sets the initial visibility from
+  page.collection, and the layout-end script re-syncs on every frame load.
+  The link targets the product's /latest/ root rather than the same page
+  under /latest/ — there is no redirect mechanism, so a same-page link 404s
+  whenever the page was renamed or removed in the newer version. Revisit
+  once the 404 page can search for the missing page.
+{%- endcomment -%}
+{%- for product_entry in site.data.products -%}
+  {%- assign product_id = product_entry[0] -%}
+  {%- assign product = product_entry[1] -%}
+  {%- if product.single_version == true -%}{%- continue -%}{%- endif -%}
+  {%- for version in product.versions -%}
+    {%- if version.id == product.latest -%}{%- continue -%}{%- endif -%}
+    {%- assign version_collection = version.collection | remove_first: '_' -%}
+    <div class="VPOutdatedBanner" role="region" aria-label="Outdated documentation notice" data-collection="{{ version_collection }}"{% if version_collection != page.collection %} hidden{% endif %}>
+      This documentation is for {{ product.label }} {{ version.label }}, which is no longer actively updated.
+      <a href="/{{ product_id }}/latest/">Switch to the latest {{ product.label }} documentation</a>.
+    </div>
+  {%- endfor -%}
+{%- endfor -%}
diff --git a/_plugins/canonical_latest.rb b/_plugins/canonical_latest.rb
new file mode 100644
index 000000000..6449e0c0d
--- /dev/null
+++ b/_plugins/canonical_latest.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Every numbered collection whose version *is* its product's `latest` alias
+# (e.g. _openvox_8x while `latest: 8x`) publishes byte-identical content twice:
+# once under its own base (/openvox/8.x/) and once under /openvox/latest/ via
+# the _latest symlink. This hook points the numbered copy's canonical at its
+# /latest/ twin so search engines index the stable /latest/ URLs; the theme's
+# head.html (and jekyll-seo-tag, if adopted) emit page.canonical_url when set.
+#
+# Frozen older versions are deliberately left alone with the theme's default
+# self-canonical: once `latest` moves on, their content is unique and the
+# same page may not exist under /latest/.
+#
+# The origin is hardcoded, matching llms.txt, because site.url is unset.
+module OpenvoxDocs
+  module CanonicalLatest
+    ORIGIN = 'https://docs.openvoxproject.org'
+
+    def self.apply(site)
+      (site.data['products'] || {}).each do |product_id, product|
+        version = Array(product['versions']).find { |v| v['id'] == product['latest'] }
+        next unless version
+
+        collection = site.collections[version['collection'].delete_prefix('_')]
+        next if collection.nil? || collection.label.end_with?('_latest')
+
+        canonicalize(collection, version['base'], "/#{product_id}/latest/")
+      end
+    end
+
+    def self.canonicalize(collection, base, latest_base)
+      collection.docs.each do |doc|
+        next unless doc.url.start_with?(base)
+
+        doc.data['canonical_url'] = "#{ORIGIN}#{latest_base}#{doc.url.delete_prefix(base)}"
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :pre_render do |site|
+  OpenvoxDocs::CanonicalLatest.apply(site)
+end
diff --git a/assets/css/custom.css b/assets/css/custom.css
index 71854b6c4..4a012f0f5 100644
--- a/assets/css/custom.css
+++ b/assets/css/custom.css
@@ -75,6 +75,35 @@ table.resolution > tbody > tr:last-child > td:first-child {
   color: var(--vp-c-white);
 }
 
+/* Viewport-pinned notice on pages of frozen (non-latest) doc versions.
+   The soft danger color is layered over the opaque page background so the
+   fixed banner doesn't show content scrolling through behind it. */
+.VPOutdatedBanner {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: var(--vp-z-index-nav);
+  padding: 0.6rem 1.5rem;
+  text-align: center;
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--vp-c-danger-1);
+  background-color: var(--vp-c-bg);
+  background-image: linear-gradient(var(--vp-c-danger-soft), var(--vp-c-danger-soft));
+  border-top: 1px solid var(--vp-c-danger-2);
+}
+
+.VPOutdatedBanner a {
+  color: inherit;
+  font-weight: 600;
+  text-decoration: underline;
+}
+
+.VPOutdatedBanner a:hover {
+  color: var(--vp-c-danger-2);
+}
+
 /* Highlight the active page more visibly */
 .VPSidebarItem.level-0.is-active > .item .link > .text,
 .VPSidebarItem.level-1.is-active > .item .link > .text,

From 1a2154a269972012875fd46471459d60c1775f5e Mon Sep 17 00:00:00 2001
From: Michael Harp <mike@mikeharp.com>
Date: Tue, 4 Aug 2026 09:02:43 -0400
Subject: [PATCH 2/3] Fix out-of-date banner false-positive on unreleased
 preview versions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The banner previously fired for any version that wasn't `latest`,
which is wrong during a Phase 1 major-version cutover (MAINTAINING.md):
a new version can sit ahead of `latest` in the versions list (newest
first) as a beta preview, deliberately not yet promoted. That version
is not "no longer actively updated" — it's the opposite.

Track whether the loop has passed the `latest` entry and only emit the
banner for versions after it, matching the documented newest-first
ordering in _data/products.yml.

Verified: a Liquid-only render against synthetic 9x/8x(latest)/7x data
confirmed 9x renders no banner, 8x renders no banner, 7x renders a
visible one. Also verified live against a merged-in OpenVox 9 cutover
branch (docs/openvox9-cutover) via jekyll serve + Playwright
screenshots: no banner on /openvox/9.x/ or /openvox/8.x/, and a
temporary synthetic older version confirmed the banner still renders
correctly when it should.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
---
 _includes/version-banner.html | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/_includes/version-banner.html b/_includes/version-banner.html
index 4c7838687..4563c4711 100644
--- a/_includes/version-banner.html
+++ b/_includes/version-banner.html
@@ -3,13 +3,23 @@
   version, so readers landing on old bookmarks or search results always see
   a way to the current docs (#320).
 
-  One banner is emitted per numbered version that is NOT what the product's
-  `latest` alias points at, so coverage is automatic: the moment
+  One banner is emitted per numbered version that is OLDER than what the
+  product's `latest` alias points at, so coverage is automatic: the moment
   _data/products.yml gains a new version and `latest` moves, every page of
   the older collections shows the banner with no per-page front matter.
   Today every numbered version is its product's latest, so this include
   renders nothing.
 
+  "Older" is positional, not just "not latest": `versions` is documented in
+  _data/products.yml as newest-first, and a Phase 1 major-version cutover
+  (see MAINTAINING.md) adds a new, newer version at the front of the list
+  while `latest` deliberately stays on the prior version until GA (e.g.
+  OpenVox 9.x sitting ahead of the 8x `latest` entry during its beta). A
+  version listed ahead of `latest` is a preview that hasn't been promoted
+  yet, not something "no longer actively updated" — it must not get this
+  banner. So the loop below tracks whether `latest` has been passed yet and
+  only emits banners after that point.
+
   Like the version picker, the banners live outside the Turbo content frame
   and persist across navigation: Liquid sets the initial visibility from
   page.collection, and the layout-end script re-syncs on every frame load.
@@ -22,8 +32,13 @@
   {%- assign product_id = product_entry[0] -%}
   {%- assign product = product_entry[1] -%}
   {%- if product.single_version == true -%}{%- continue -%}{%- endif -%}
+  {%- assign passed_latest = false -%}
   {%- for version in product.versions -%}
-    {%- if version.id == product.latest -%}{%- continue -%}{%- endif -%}
+    {%- if version.id == product.latest -%}
+      {%- assign passed_latest = true -%}
+      {%- continue -%}
+    {%- endif -%}
+    {%- unless passed_latest -%}{%- continue -%}{%- endunless -%}
     {%- assign version_collection = version.collection | remove_first: '_' -%}
     <div class="VPOutdatedBanner" role="region" aria-label="Outdated documentation notice" data-collection="{{ version_collection }}"{% if version_collection != page.collection %} hidden{% endif %}>
       This documentation is for {{ product.label }} {{ version.label }}, which is no longer actively updated.

From 0918ade84141c1f2b55cad39670a9b83149a1389 Mon Sep 17 00:00:00 2001
From: Michael Harp <mike@mikeharp.com>
Date: Tue, 4 Aug 2026 10:02:35 -0400
Subject: [PATCH 3/3] Validate products.yml latest/ordering in CI

version-banner.html's out-of-date logic (and the version selector)
both rely on an unenforced convention: `versions` listed newest-first,
`latest` naming a real entry. Nothing caught a violation before this
would silently mis-derive version state. Add rake test:products_data,
checking latest resolves, ids are unique, and ids sort newest-first
(by leading version-id number), and wire it into the Rake Checks CI
job alongside rubocop.

Verified locally: passes on current products.yml and on the real
OpenVox 9 cutover branch's data (docs/openvox9-cutover), and correctly
fails on injected bad-ordering, duplicate-id, and unknown-latest cases.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
---
 .github/workflows/test.yml |  2 ++
 Rakefile                   | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 325fc517c..6677b2916 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -27,6 +27,8 @@ jobs:
         run: bundle env
       - name: Run rake rubocop
         run: bundle exec rake rubocop
+      - name: Validate products.yml
+        run: bundle exec rake test:products_data
       - name: Validate code
         run: bundle exec jekyll build
 
diff --git a/Rakefile b/Rakefile
index 07232175b..0e1fbee36 100644
--- a/Rakefile
+++ b/Rakefile
@@ -215,4 +215,36 @@ namespace :test do
       checks: ['Links'],
     ).run
   end
+
+  desc 'Validate _data/products.yml: `latest` must name a real version, and ' \
+       '`versions` must be ordered newest-first (both are relied on by ' \
+       '_includes/version-banner.html and the version selector)'
+  task :products_data do
+    products = YAML.load_file('_data/products.yml')
+    errors = []
+
+    products.each do |product_id, product|
+      next if product['single_version']
+
+      ids = (product['versions'] || []).map { |v| v['id'] }
+
+      errors << "#{product_id}: duplicate version ids (#{ids.join(', ')})" if ids.uniq.length != ids.length
+
+      errors << "#{product_id}: latest '#{product['latest']}' is not one of its versions (#{ids.join(', ')})" unless ids.include?(product['latest'])
+
+      majors = ids.map { |id| id[/\A\d+/] }
+      if majors.any?(&:nil?)
+        errors << "#{product_id}: version id(s) don't start with a number (#{ids.join(', ')}), can't check ordering"
+      elsif majors.map(&:to_i) != majors.map(&:to_i).sort.reverse
+        errors << "#{product_id}: versions must be newest-first by id (got #{ids.join(', ')})"
+      end
+    end
+
+    if errors.any?
+      warn "_data/products.yml failed validation:\n  - #{errors.join("\n  - ")}"
+      exit 1
+    end
+
+    puts '_data/products.yml: latest references and version ordering OK'
+  end
 end