git: eb5adff461 - main - website: Add navigation between the documents of a release

The branch main has been updated by dbaio:

URL: https://cgit.FreeBSD.org/doc/commit/?id=eb5adff4614958eb5f33180363843f06cdc3293c

commit eb5adff4614958eb5f33180363843f06cdc3293c
Author:     Danilo G. Baio <[email protected]>
AuthorDate: 2026-08-09 03:41:26 +0000
Commit:     Danilo G. Baio <[email protected]>
CommitDate: 2026-08-10 23:42:55 +0000

    website: Add navigation between the documents of a release
    
    Every release publishes a set of sibling documents (announcement, signed
    checksums, upgrading or installation instructions, hardware notes, release
    notes, errata, readme and schedule), but they are only listed together on
    the release index page.  Once inside one of them there is no way to reach
    the others without editing the URL, which is inconvenient for the documents
    most often read before an update, such as the errata and the upgrading
    instructions.
    
    Add a discreet list of the other documents of the same release under the
    page title.  The list holds the documents the release index page links to,
    so releases shipping a different set of documents are handled without any
    per-release maintenance, and the documents of an upcoming release stay
    hidden until the index publishes them.
    
    Only releases whose directory has its own _index.adoc are covered, which is
    10.2R and newer.
    
    The new i18n keys are added to ru.toml and es.toml in English, for the
    translators to pick up.
    
    Reviewed by:    cperciva
    Pull Request:   https://ron-dev.freebsd.org/FreeBSD/doc/pulls/3
---
 website/themes/beastie/assets/styles/main.css      | 32 +++++++++
 website/themes/beastie/i18n/en.toml                | 34 ++++++++++
 website/themes/beastie/i18n/es.toml                | 34 ++++++++++
 website/themes/beastie/i18n/ru.toml                | 34 ++++++++++
 .../beastie/layouts/_partials/release-docs.html    | 75 ++++++++++++++++++++++
 website/themes/beastie/layouts/single.html         |  1 +
 6 files changed, 210 insertions(+)

diff --git a/website/themes/beastie/assets/styles/main.css b/website/themes/beastie/assets/styles/main.css
index ee09ce3361..ae8d1b9e7a 100644
--- a/website/themes/beastie/assets/styles/main.css
+++ b/website/themes/beastie/assets/styles/main.css
@@ -1025,6 +1025,38 @@ input[type='checkbox'] {
   padding-bottom: 1.2rem;
 }
 
+/* Release documents navigation */
+#contentwrap h1:has(+ .release-docs) {
+  padding-bottom: .5rem;
+}
+
+.release-docs {
+  margin-bottom: 1.5rem;
+  padding-bottom: .6rem;
+  border-bottom: 1px solid var(--lines-color);
+  font-size: var(--size-300);
+  line-height: 1.8;
+}
+
+.release-docs ul {
+  display: inline;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.release-docs li {
+  display: inline;
+}
+
+.release-docs li:not(:last-child)::after {
+  content: " \00B7 ";
+}
+
+.release-docs [aria-current="page"] {
+  font-weight: 600;
+}
+
 @media (max-width: 768px) {
   #sidewrap {
     display: none;
diff --git a/website/themes/beastie/i18n/en.toml b/website/themes/beastie/i18n/en.toml
index b433526892..368ad2fb53 100644
--- a/website/themes/beastie/i18n/en.toml
+++ b/website/themes/beastie/i18n/en.toml
@@ -708,3 +708,37 @@ other = "Submit a Problem Report"
 
 [webresources]
 other = "Web Resources"
+
+# ---------------------------------------------------
+# Release documents navigation
+# ---------------------------------------------------
+
+[rel-doc-nav]
+other = "Release documents"
+
+[rel-doc-announce]
+other = "announcement"
+
+[rel-doc-signatures]
+other = "signed checksum files"
+
+[rel-doc-upgrading]
+other = "upgrading instructions"
+
+[rel-doc-installation]
+other = "installation instructions"
+
+[rel-doc-hardware]
+other = "hardware information"
+
+[rel-doc-relnotes]
+other = "release notes"
+
+[rel-doc-errata]
+other = "errata"
+
+[rel-doc-readme]
+other = "readme"
+
+[rel-doc-schedule]
+other = "schedule"
diff --git a/website/themes/beastie/i18n/es.toml b/website/themes/beastie/i18n/es.toml
index 266ac93f1a..020ba69484 100644
--- a/website/themes/beastie/i18n/es.toml
+++ b/website/themes/beastie/i18n/es.toml
@@ -708,3 +708,37 @@ other = "Enviar un informe de problema"
 
 [webresources]
 other = "Recursos web"
+
+# ---------------------------------------------------
+# Release documents navigation
+# ---------------------------------------------------
+
+[rel-doc-nav]
+other = "Release documents"
+
+[rel-doc-announce]
+other = "announcement"
+
+[rel-doc-signatures]
+other = "signed checksum files"
+
+[rel-doc-upgrading]
+other = "upgrading instructions"
+
+[rel-doc-installation]
+other = "installation instructions"
+
+[rel-doc-hardware]
+other = "hardware information"
+
+[rel-doc-relnotes]
+other = "release notes"
+
+[rel-doc-errata]
+other = "errata"
+
+[rel-doc-readme]
+other = "readme"
+
+[rel-doc-schedule]
+other = "schedule"
diff --git a/website/themes/beastie/i18n/ru.toml b/website/themes/beastie/i18n/ru.toml
index 1c8d1ce64e..002c96fad8 100644
--- a/website/themes/beastie/i18n/ru.toml
+++ b/website/themes/beastie/i18n/ru.toml
@@ -709,6 +709,40 @@ other = "Отправить сообщение о проблеме"
 [webresources]
 other = "Веб-ресурсы"
 
+# ---------------------------------------------------
+# Release documents navigation
+# ---------------------------------------------------
+
+[rel-doc-nav]
+other = "Release documents"
+
+[rel-doc-announce]
+other = "announcement"
+
+[rel-doc-signatures]
+other = "signed checksum files"
+
+[rel-doc-upgrading]
+other = "upgrading instructions"
+
+[rel-doc-installation]
+other = "installation instructions"
+
+[rel-doc-hardware]
+other = "hardware information"
+
+[rel-doc-relnotes]
+other = "release notes"
+
+[rel-doc-errata]
+other = "errata"
+
+[rel-doc-readme]
+other = "readme"
+
+[rel-doc-schedule]
+other = "schedule"
+
 #
 # The FreeBSD Russian Documentation Project
 #
diff --git a/website/themes/beastie/layouts/_partials/release-docs.html b/website/themes/beastie/layouts/_partials/release-docs.html
new file mode 100644
index 0000000000..c880d00735
--- /dev/null
+++ b/website/themes/beastie/layouts/_partials/release-docs.html
@@ -0,0 +1,75 @@
+{{/*
+  Discreet navigation between the documents of a single release.
+
+  Every release ships a different set of documents, so the list is not
+  hardcoded: it holds the documents the release index page links to.  Following
+  the index keeps this in step with the documents of an upcoming release, which
+  are committed well before they are announced and are deliberately left out of
+  the index until then.
+
+  Only the documents of the modern release layout are listed; the
+  per-architecture pages of the old releases (hardware-i386, relnotes-alpha,
+  ...) and one-off pages (todo, qa, approvals, ...) are ignored.
+
+  The partial renders nothing unless the page is a document of a release
+  directory holding its own _index.adoc, which is the case from 10.2R on, and
+  the index links at least one other document.
+*/}}
+
+{{- $ordered := slice "announce" "signatures" "upgrading" "installation" "hardware" "relnotes" "errata" "readme" "schedule" -}}
+
+{{- $page := . -}}
+{{- with $page.File -}}
+  {{- $dir := .Dir -}}
+  {{- if findRE `^releases/[^/]+/?$` $dir -}}
+    {{- $section := $page.CurrentSection -}}
+    {{- with $section.File -}}
+      {{- if eq .Dir $dir -}}
+
+        {{- /* The documents the release index page links to, by base name. */ -}}
+        {{- $linked := slice -}}
+        {{- range findRE `href="[^"]+"` $section.Content -}}
+          {{- $href := . | strings.TrimPrefix `href="` | strings.TrimSuffix `"` | strings.TrimSuffix "/" -}}
+          {{- $linked = $linked | append (path.Base $href) -}}
+        {{- end -}}
+
+        {{- $documents := slice -}}
+        {{- $others := false -}}
+        {{- range $name := $ordered -}}
+          {{- if in $linked $name -}}
+            {{- range $sibling := $section.RegularPages -}}
+              {{- with $sibling.File -}}
+                {{- if eq .TranslationBaseName $name -}}
+                  {{- $documents = $documents | append (dict "key" $name "page" $sibling) -}}
+                  {{- if ne $sibling.RelPermalink $page.RelPermalink -}}
+                    {{- $others = true -}}
+                  {{- end -}}
+                {{- end -}}
+              {{- end -}}
+            {{- end -}}
+          {{- end -}}
+        {{- end -}}
+
+        {{- $release := $dir | strings.TrimPrefix "releases/" | strings.TrimSuffix "/" | strings.TrimSuffix "R" -}}
+
+        {{- if $others -}}
+          <nav class="release-docs" aria-label="{{ i18n "rel-doc-nav" }}">
+            <a href="{{ $section.RelPermalink }}">{{ i18n "freebsd" }} {{ $release }}</a>:
+            <ul>
+              {{- range $documents }}
+              <li>
+                {{- if eq .page.RelPermalink $page.RelPermalink -}}
+                  <span aria-current="page">{{ i18n (printf "rel-doc-%s" .key) }}</span>
+                {{- else -}}
+                  <a href="{{ .page.RelPermalink }}">{{ i18n (printf "rel-doc-%s" .key) }}</a>
+                {{- end -}}
+              </li>
+              {{- end }}
+            </ul>
+          </nav>
+        {{- end -}}
+
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
diff --git a/website/themes/beastie/layouts/single.html b/website/themes/beastie/layouts/single.html
index e93e915cac..45d75e4312 100644
--- a/website/themes/beastie/layouts/single.html
+++ b/website/themes/beastie/layouts/single.html
@@ -8,6 +8,7 @@
 
   <div id="contentwrap">
     <h1>{{ .Title }}</h1>
+    {{ partial "release-docs.html" . }}
     {{- .Content -}}
     {{ if .GitInfo }}
     <hr />