From 459098c2bcbaffdc62e2181b7786f7b331cfa054 Mon Sep 17 00:00:00 2001 From: Aleksei Igrychev Date: Thu, 24 Sep 2026 21:41:36 +0100 Subject: [PATCH 1/4] feat(docs): serve werf 3 documentation as the latest version Point the current docs root at v3, so /docs/ and the latest alias resolve to v3 while v2 and v1.2 stay addressable under their own prefixes. Update the Documentation menu link, doc group detection for search and the local dev proxy accordingly. Signed-off-by: Aleksei Igrychev --- .helm/values.yaml | 2 +- .werf/nginx-dev.conf | 4 ++-- _data/en/topnav.yml | 2 +- _data/ru/topnav.yml | 2 +- assets/js/customscripts.js | 13 +++++-------- docker-compose.yml | 2 +- 6 files changed, 11 insertions(+), 14 deletions(-) diff --git a/.helm/values.yaml b/.helm/values.yaml index f8b0b14ef..2e25d29ed 100644 --- a/.helm/values.yaml +++ b/.helm/values.yaml @@ -45,7 +45,7 @@ resources: production: 300M docs: - currentRoot: v2 + currentRoot: v3 supportedRoots: - v3 - v2 diff --git a/.werf/nginx-dev.conf b/.werf/nginx-dev.conf index 229ceb1ef..fd4017caa 100644 --- a/.werf/nginx-dev.conf +++ b/.werf/nginx-dev.conf @@ -87,8 +87,8 @@ http { location /docs/ { rewrite ^/docs/?$ /docs/latest/ redirect; - rewrite ^/docs/(?latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)$ /docs/$ver/ redirect; - rewrite ^/docs/(?latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)/(?.*) /$tail break; + rewrite ^/docs/(?latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)$ /docs/$ver/ redirect; + rewrite ^/docs/(?latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)/(?.*) /$tail break; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; diff --git a/_data/en/topnav.yml b/_data/en/topnav.yml index ef939e2bb..2b574e45d 100644 --- a/_data/en/topnav.yml +++ b/_data/en/topnav.yml @@ -1,7 +1,7 @@ - title: Getting Started url: /getting_started/ - title: Documentation - url: /docs/v2/ + url: /docs/v3/ - title: Kubernetes guide url: /guides.html hot: true diff --git a/_data/ru/topnav.yml b/_data/ru/topnav.yml index e4aa54b1f..200983837 100644 --- a/_data/ru/topnav.yml +++ b/_data/ru/topnav.yml @@ -1,7 +1,7 @@ - title: Быстрый старт url: /getting_started/ - title: Документация - url: /docs/v2/ + url: /docs/v3/ - title: Самоучитель по Kubernetes url: /guides.html hot: true diff --git a/assets/js/customscripts.js b/assets/js/customscripts.js index f3c69c863..0849b5a6a 100644 --- a/assets/js/customscripts.js +++ b/assets/js/customscripts.js @@ -467,18 +467,15 @@ $(document).ready(function () { }); function getDocGroupFromURL() { - let result = window.location.pathname.match(/^\/docs\/(latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)(?:\/|$)/); + let result = window.location.pathname.match(/^\/docs\/(latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)(?:\/|$)/); if (result && result[1]) { - if (result[1] === 'latest') { - return 'v2'; - } - if (result[1].indexOf('pr-') === 0) { - return 'v2'; - } if (result[1].indexOf('v1.2') === 0) { return 'v1.2'; } - return 'v2'; + if (result[1].indexOf('v2') === 0) { + return 'v2'; + } + return 'v3'; } return null; } diff --git a/docker-compose.yml b/docker-compose.yml index 3b8ad4ebb..0598b441f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -47,7 +47,7 @@ services: backend: image: $WERF_BACKEND_DOCKER_IMAGE_NAME environment: - CURRENT_DOCS_MAJOR: "v2" + CURRENT_DOCS_MAJOR: "v3" SUPPORTED_DOCS_MAJOR_VERSIONS: "v3,v2,v1.2" DOCS_LATEST_ALIAS_ENABLED: "true" LOG_LEVEL: info From 3238952184ab990c1c2f2a487991adb4bc17cb8b Mon Sep 17 00:00:00 2001 From: Aleksei Igrychev Date: Thu, 24 Sep 2026 21:41:40 +0100 Subject: [PATCH 2/4] test(docs): check docs roots against the current docs root Render the production chart for both clusters and assert the backend CURRENT_DOCS_MAJOR env, the /docs/ redirect and the latest alias shortcuts, plus doc group detection, the dev proxy and the Documentation menu link. Signed-off-by: Aleksei Igrychev --- Taskfile.yaml | 6 ++++ scripts/docs/check_doc_group.js | 35 ++++++++++++++++++++++ scripts/docs/check_docs_roots.sh | 50 ++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+) create mode 100644 scripts/docs/check_doc_group.js create mode 100755 scripts/docs/check_docs_roots.sh diff --git a/Taskfile.yaml b/Taskfile.yaml index b9bce26b3..6c93da533 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -153,6 +153,12 @@ tasks: - | ./scripts/docs/check_broken_links.sh en + site:check-docs-roots: + desc: "Check that docs roots, the latest alias and doc group detection agree with the current docs root." + cmds: + - | + ./scripts/docs/check_docs_roots.sh + site:run-spell-check: desc: "Run spell check for all pages." deps: diff --git a/scripts/docs/check_doc_group.js b/scripts/docs/check_doc_group.js new file mode 100644 index 000000000..bde29e497 --- /dev/null +++ b/scripts/docs/check_doc_group.js @@ -0,0 +1,35 @@ +const assert = require("assert"); +const fs = require("fs"); +const path = require("path"); + +const src = fs.readFileSync( + path.join(__dirname, "../../assets/js/customscripts.js"), + "utf8", +); +const fnSource = src.match(/function getDocGroupFromURL\(\) \{[\s\S]*?\n\}/); +assert.ok(fnSource, "getDocGroupFromURL is not found in customscripts.js"); + +const call = (pathname) => + new Function("window", `${fnSource[0]}; return getDocGroupFromURL();`)({ + location: { pathname }, + }); + +const cases = [ + ["/docs/latest/usage/build/overview.html", "v3"], + ["/docs/pr-123/index.html", "v3"], + ["/docs/v3/", "v3"], + ["/docs/v3.1.4/reference/werf_yaml.html", "v3"], + ["/docs/v2/", "v2"], + ["/docs/v2.10.3/reference/werf_yaml.html", "v2"], + ["/docs/v1.2/", "v1.2"], + ["/docs/v1.2.4-plus-fix1/reference/werf_yaml.html", "v1.2"], + ["/docs/v9/", null], + ["/guides.html", null], +]; + +for (const [pathname, want] of cases) { + const got = call(pathname); + assert.strictEqual(got, want, `${pathname}: got ${got}, want ${want}`); +} + +console.log(`OK: getDocGroupFromURL, ${cases.length} cases`); diff --git a/scripts/docs/check_docs_roots.sh b/scripts/docs/check_docs_roots.sh new file mode 100755 index 000000000..f07e7873e --- /dev/null +++ b/scripts/docs/check_docs_roots.sh @@ -0,0 +1,50 @@ +#!/bin/bash + +set -e + +cd "$(dirname "$0")/../.." + +current_root="v3" + +chart_dir="$(mktemp -d)" +trap 'rm -rf "$chart_dir"' EXIT +cp -R .helm/. "$chart_dir/" +cat >"$chart_dir/Chart.yaml" <&2 + exit 1 +} + +for cluster in eu ru; do + rendered="$(helm template werfio-production "$chart_dir" \ + --set werf.env=production \ + --set werf.namespace=werfio-production \ + --set "werf.image.web-backend=stub" \ + --set "global.targetCluster=$cluster")" + + echo "$rendered" | grep -q -- "- name: CURRENT_DOCS_MAJOR" || + fail "$cluster: CURRENT_DOCS_MAJOR env is missing" + echo "$rendered" | grep -A1 -- "- name: CURRENT_DOCS_MAJOR" | grep -q "value: \"$current_root\"" || + fail "$cluster: CURRENT_DOCS_MAJOR is not $current_root" + echo "$rendered" | grep -q "rewrite \^/docs/?\$ */docs/$current_root/ " || + fail "$cluster: /docs/ does not redirect to /docs/$current_root/" + echo "$rendered" | grep -q "rewrite \^/docs/(?latest|.*)/?\$ */docs/\$ver/usage/project_configuration/overview.html" || + fail "$cluster: latest alias is missing in docs shortcuts" +done + +grep -q "latest|pr-\[^/\]+|$(echo "$current_root" | sed 's/\./\\\\./')" .werf/nginx-dev.conf || + fail "nginx-dev.conf does not proxy /docs/$current_root/" + +for lang in en ru; do + grep -q "url: /docs/$current_root/" "_data/$lang/topnav.yml" || + fail "$lang topnav does not link to /docs/$current_root/" +done + +node scripts/docs/check_doc_group.js + +echo "OK: docs roots are consistent with currentRoot $current_root" From c38e0499f0455393920789c8ac2e8f1931a625b9 Mon Sep 17 00:00:00 2001 From: Aleksei Igrychev Date: Thu, 24 Sep 2026 21:54:15 +0100 Subject: [PATCH 3/4] fix(docs): allow crawlers to index v3 documentation Signed-off-by: Aleksei Igrychev --- robots.txt | 3 +++ scripts/docs/check_docs_roots.sh | 10 ++++++++++ sitemap.xml | 3 +++ 3 files changed, 16 insertions(+) diff --git a/robots.txt b/robots.txt index 173e1bf40..f5372f29b 100644 --- a/robots.txt +++ b/robots.txt @@ -8,6 +8,9 @@ User-agent: * Disallow: *.js Disallow: *?* Allow: / +Allow: /docs/v3 +Disallow: /docs/v3- +Disallow: /docs/v3. Allow: /docs/v2 Disallow: /docs/v2- Disallow: /docs/v2. diff --git a/scripts/docs/check_docs_roots.sh b/scripts/docs/check_docs_roots.sh index f07e7873e..07796e012 100755 --- a/scripts/docs/check_docs_roots.sh +++ b/scripts/docs/check_docs_roots.sh @@ -31,6 +31,8 @@ for cluster in eu ru; do fail "$cluster: CURRENT_DOCS_MAJOR env is missing" echo "$rendered" | grep -A1 -- "- name: CURRENT_DOCS_MAJOR" | grep -q "value: \"$current_root\"" || fail "$cluster: CURRENT_DOCS_MAJOR is not $current_root" + echo "$rendered" | grep -A1 -- "- name: SUPPORTED_DOCS_MAJOR_VERSIONS" | grep -q 'value: "v3,v2,v1.2"' || + fail "$cluster: supported documentation versions changed" echo "$rendered" | grep -q "rewrite \^/docs/?\$ */docs/$current_root/ " || fail "$cluster: /docs/ does not redirect to /docs/$current_root/" echo "$rendered" | grep -q "rewrite \^/docs/(?latest|.*)/?\$ */docs/\$ver/usage/project_configuration/overview.html" || @@ -45,6 +47,14 @@ for lang in en ru; do fail "$lang topnav does not link to /docs/$current_root/" done +grep -q "CURRENT_DOCS_MAJOR: \"$current_root\"" docker-compose.yml || + fail "local backend does not use $current_root" + +for root in v3 v2; do + grep -qx "Allow: /docs/$root" robots.txt || fail "robots.txt blocks $root" + grep -q "/docs/$root/sitemap.xml" sitemap.xml || fail "sitemap.xml omits $root" +done + node scripts/docs/check_doc_group.js echo "OK: docs roots are consistent with currentRoot $current_root" diff --git a/sitemap.xml b/sitemap.xml index fab9c2895..72123aa79 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -7,6 +7,9 @@ search: exclude + + {{ site.url }}/docs/v3/sitemap.xml + {{ site.url }}/docs/v2/sitemap.xml From 11223bfdf21e28a1bb7c14fb277ef6530cd134d0 Mon Sep 17 00:00:00 2001 From: Aleksei Igrychev Date: Thu, 24 Sep 2026 22:19:33 +0100 Subject: [PATCH 4/4] chore(docs): add Podman and netavark to the spelling dictionary Both are proper names used in the v3 documentation and were rejected by the spell check. Signed-off-by: Aleksei Igrychev --- scripts/docs/spelling/dictionaries/dev_OPS.dic | 4 +++- scripts/docs/spelling/wordlist | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/docs/spelling/dictionaries/dev_OPS.dic b/scripts/docs/spelling/dictionaries/dev_OPS.dic index 1d3c8b2fd..f2ecec8b7 100644 --- a/scripts/docs/spelling/dictionaries/dev_OPS.dic +++ b/scripts/docs/spelling/dictionaries/dev_OPS.dic @@ -1,4 +1,4 @@ -520 +522 1GB 2GB 5XX @@ -160,6 +160,7 @@ MySQL’s namespace namespaces Nelm +netavark nginx NGINX’s Node.js @@ -177,6 +178,7 @@ plugin PNG PodAntiAffinity PodDisruptionBudget +Podman PostgreSQL PowerShell pre diff --git a/scripts/docs/spelling/wordlist b/scripts/docs/spelling/wordlist index bf1296519..59dfa52a1 100644 --- a/scripts/docs/spelling/wordlist +++ b/scripts/docs/spelling/wordlist @@ -158,6 +158,7 @@ MySQL’s namespace namespaces Nelm +netavark nginx NGINX’s Node.js @@ -175,6 +176,7 @@ plugin PNG PodAntiAffinity PodDisruptionBudget +Podman PostgreSQL PowerShell pre