[release-1.24] feat: add Out-Of-Date Documentation header for archive versions (#16530)

* Added Deprecated Documentation Header

Added a warning header to all docs pages warning user that this version is out-of-date with an option to go to /latest

* Update banner with craig's comments

* created _archive.scss and added archive check for banner

* added i18n en for archive banner

* added uk and zh for archive header

* fix lint

* test new linter to ignore /latest/ on archive sites

* lint the linter

* lint the linter with local testing first

* lint the linter with local testing that I test, first

---------

Co-authored-by: sbegin0 <[email protected]>
Co-authored-by: sbegin0 <[email protected]>
Co-authored-by: Craig Box <[email protected]>

Author: 3 people

assets/sass/_all.scss

@@ -11,6 +11,7 @@
 
 @import "misc/about";
 @import "misc/analysis-message";
+@import "misc/archive";
 @import "misc/article";
 @import "misc/banners";
 @import "misc/blog";

assets/sass/misc/_archive.scss

@@ -0,0 +1,18 @@
+.archive-warning-banner {
+    background-color: #fff3cd;
+    color: #664d03;
+    padding: 1rem;
+    border-bottom: 1px solid #ffecb5;
+    text-align: center;
+
+    p {
+        margin-top: 0;
+        margin-bottom: 0;
+    }
+
+    a {
+        font-weight: bold;
+        text-decoration: underline;
+        color: #413002; // Making link slightly darker than banner text for better contrast/visibility
+    }
+}

i18n/en.toml

@@ -385,3 +385,9 @@ other = "Go to solutions"
 
 [case_study_slogan]
 other = "Read case studies of companies that benefited from implementing Istio"
+
+[archive_banner_text]
+other = "⚠️ This documentation is for an older version (<strong>%s</strong>) and is no longer updated."
+
+[archive_banner_link]
+other = "Read the latest version."

i18n/uk.toml

@@ -377,3 +377,9 @@ other = "Перейти до рішень"
 
 [case_study_slogan]
 other = "Читайте приклади успішних прикладів використання Istio компаніями, які отримали вигоду від його впровадження"
+
+[archive_banner_text]
+other = "⚠️ Це документація для (застарілої) версії (<strong>%s</strong>), яка вже не підтримується."
+
+[archive_banner_link]
+other = "Читати останню версію."

i18n/zh.toml

@@ -375,3 +375,9 @@ other = "转到解决方案"
 
 [case_study_slogan]
 other = "阅读因实施 Istio 而受益的公司案例"
+
+[archive_banner_text]
+other = "⚠️ 此文档针对过时的版本 (<strong>%s</strong>)，将不在维护和更新。"
+
+[archive_banner_link]
+other = "查看最新文档。"

layouts/_default/baseof.html

@@ -156,6 +156,15 @@
 
         {{ partial "events.html" (dict "page" . "kind" "sticker") }}
         {{ partial "header.html" . }}
+
+        <!-- Archived Documentation Header -->
+        {{ if and (eq .Section "docs") .Site.Data.args.archive}}
+        <div class="archive-warning-banner" role="alert">
+            {{ (printf (i18n "archive_banner_text") .Site.Data.args.version) | safeHTML }}
+            <a href="/latest{{ .RelPermalink | safeURL }}">{{ i18n "archive_banner_link" }}</a>
+        </div>
+        {{ end }}
+
         {{ partial "events.html" (dict "page" . "kind" "banner") }}
 
         {{ block "main" . }}{{ end }}

scripts/lint_site.sh

@@ -17,6 +17,14 @@
 set -e
 
 FAILED=0
+ARCHIVE=0
+
+# If the archive flag is set, we allow links to `/latest/` that won't exist
+# at the time of linting, but will exist when the archive is copied to the
+# current serving branch.
+if grep -q "^archive: true" data/args.yml 2>/dev/null; then
+    ARCHIVE=1
+fi
 
 if [[ "$#" -ne 0 ]]; then
     LANGS="$*"
@@ -204,13 +212,18 @@ if [ -d ./public ]; then
             printf -v ignore_files "/^.\/public\/%s/," "${SKIP_LANGS[@]}"; ignore_files="${ignore_files%,}"
         fi
         echo "Running linkinator..."
-        if [[ ${CHECK_EXTERNAL_LINKS:-} == "true" ]]; then
+        if [[ ${ARCHIVE:-} -eq 1 ]]; then
+            echo "Linting archive"
+            if ! linkinator public/ -r -s 'github.com localhost:3000 localhost:5601 localhost:8001 localhost:9080 localhost:9081 en.wikipedia.org my-istio-logs-database.io ^((?!localhost).)*$ /latest/' --silent --concurrency 25; then
+                FAILED=1
+            fi
+        elif [[ ${CHECK_EXTERNAL_LINKS:-} == "true" ]]; then
             if ! linkinator public/ -r -s 'github.com localhost:3000 localhost:5601 localhost:8001 localhost:9080 localhost:9081 en.wikipedia.org my-istio-logs-database.io' --silent --concurrency 25; then
                 FAILED=1
             fi
         else
             #TODO: Remove .../workload-selector/ from ignored links. PRs take a long time to get through istio/api, and a link is broken from there. Once this PR is complete, remove it: https://github.com/istio/api/pull/1405
-            if ! linkinator public/ -r -s 'github.com localhost:3000 localhost:5601 localhost:8001 localhost:9080 localhost:9081 en.wikipedia.org my-istio-logs-database.io ^((?!localhost).)*$ /docs/reference/config/type/v1beta1/workload-selector/' --silent --concurrency 25; then
+            if ! linkinator public/ -r -s 'github.com localhost:3000 localhost:5601 localhost:8001 localhost:9080 localhost:9081 en.wikipedia.org my-istio-logs-database.io ^((?!localhost).)*$' --silent --concurrency 25; then
                 FAILED=1
             fi
         fi