Skip to content

Commit 7a0e89e

Browse files
Merge branch 'main' into fix-broken-doc-anchors
2 parents eab8ed4 + 5899a50 commit 7a0e89e

173 files changed

Lines changed: 8870 additions & 1973 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/hugo.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ jobs:
7171
--gc \
7272
--minify \
7373
--baseURL "${{ steps.pages.outputs.base_url }}/"
74+
- name: Mirror latest docs under /docs/ and /docs/v<major>/
75+
# GitHub Pages cannot redirect, so the stable aliases are real copies.
76+
run: ./hack/mirror_latest.sh public
7477
- name: Patch robots.txt
7578
# if built in a contributor's repo and deployed to personal pages, disallow search indexing
7679
if: github.repository_owner != 'cozystack'

‎.github/workflows/i18n-lint.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ on:
66
- 'i18n/**'
77
- 'content/**'
88
- 'hack/check-i18n.sh'
9+
- 'hack/i18n/**'
910
- '.github/workflows/i18n-lint.yml'
1011
push:
1112
branches:
@@ -14,6 +15,7 @@ on:
1415
- 'i18n/**'
1516
- 'content/**'
1617
- 'hack/check-i18n.sh'
18+
- 'hack/i18n/**'
1719
- '.github/workflows/i18n-lint.yml'
1820
workflow_dispatch:
1921

@@ -32,5 +34,23 @@ jobs:
3234
uses: actions/checkout@v4
3335
with:
3436
persist-credentials: false
37+
- name: Set up Python
38+
uses: actions/setup-python@v5
39+
with:
40+
python-version: '3.x'
41+
- name: Install pyyaml
42+
# check-i18n.sh reads `l10n` through lib.l10n_mode, and the unit tests
43+
# need it too. The Claude SDK is imported lazily at runtime, not here.
44+
run: python3 -m pip install --quiet pyyaml
3545
- name: Check i18n key parity and translation freshness
3646
run: ./hack/check-i18n.sh
47+
- name: Run i18n pipeline unit tests
48+
# Guards the pure functions of the translation pipeline — including the
49+
# ref/relref deref that keeps a partially-translated page from breaking
50+
# the Hugo build.
51+
run: python3 hack/i18n/test_i18n.py
52+
- name: Typography lint on published translations
53+
# Advisory: reports per-language typography drift (hand edits, pages
54+
# translated before a rule existed) without failing the build. Flip to
55+
# --strict per language once its backlog is clean.
56+
run: python3 hack/i18n/lint_translations.py
Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: i18n translate
2+
3+
# Daily translation run, one weekly PR — the same contract as hack/i18n/run-daily.sh,
4+
# moved off a maintainer's clone and personal Max subscription onto CI and an
5+
# ORG-OWNED Anthropic API key (auth: api-key). Nothing reaches production
6+
# automatically: the run pushes to a weekly branch and opens a PR a maintainer
7+
# merges. No auto-merge, CODEOWNERS/branch protection untouched.
8+
#
9+
# Required secret:
10+
# I18N_ANTHROPIC_API_KEY — an organization-owned Anthropic API key (metered).
11+
# Optional secret:
12+
# I18N_GH_TOKEN — a PAT/app token used to push the branch and open the
13+
# PR so its checks (i18n-lint, DCO) actually run; the
14+
# default GITHUB_TOKEN cannot trigger them. Without it
15+
# the run still works, but the PR opens with no checks.
16+
#
17+
# Until I18N_ANTHROPIC_API_KEY exists the job is a green no-op (see the guard step),
18+
# so enabling the schedule before provisioning the key does not spam failures.
19+
#
20+
# Spend is bounded twice per run: a page limit (DEFAULT_PAGE_LIMIT on the schedule)
21+
# and a wall-clock budget well inside timeout-minutes, so translate.py stops taking
22+
# new pages while there is still time to commit and push what it has. A run killed
23+
# by the timeout would lose every page it translated. Set a spend limit on the
24+
# key's Anthropic workspace as the outer guard.
25+
26+
on:
27+
schedule:
28+
- cron: '17 3 * * *' # daily, 03:17 UTC
29+
workflow_dispatch:
30+
inputs:
31+
lang:
32+
description: 'Limit to one language code (e.g. ru); empty = all'
33+
required: false
34+
default: ''
35+
limit:
36+
description: 'Max pages this run; empty = the scheduled default (40)'
37+
required: false
38+
default: ''
39+
40+
concurrency:
41+
group: i18n-translate
42+
cancel-in-progress: false
43+
44+
permissions:
45+
contents: write
46+
pull-requests: write
47+
48+
jobs:
49+
translate:
50+
runs-on: ubuntu-latest
51+
timeout-minutes: 300
52+
env:
53+
I18N_AUTH: api-key
54+
DEFAULT_PAGE_LIMIT: '40'
55+
# Leaves an hour of the 300-minute timeout for the page in flight and the
56+
# commit/push/PR steps.
57+
I18N_TIME_BUDGET_MIN: '240'
58+
CLAUDE_CODE_VERSION: '2.1.287'
59+
steps:
60+
- name: Guard — org API key provisioned
61+
id: guard
62+
env:
63+
ANTHROPIC_API_KEY: ${{ secrets.I18N_ANTHROPIC_API_KEY }}
64+
run: |
65+
if [ -z "${ANTHROPIC_API_KEY}" ]; then
66+
echo "::notice::secret I18N_ANTHROPIC_API_KEY is not set yet — skipping this run."
67+
echo "skip=true" >> "$GITHUB_OUTPUT"
68+
fi
69+
70+
- name: Checkout
71+
if: steps.guard.outputs.skip != 'true'
72+
uses: actions/checkout@v4
73+
with:
74+
fetch-depth: 0
75+
token: ${{ secrets.I18N_GH_TOKEN || github.token }}
76+
77+
- name: Fetch all branches (weekly-branch bookkeeping needs origin/i18n/week-*)
78+
if: steps.guard.outputs.skip != 'true'
79+
run: |
80+
git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
81+
git fetch --prune origin
82+
83+
- name: Set up Python
84+
if: steps.guard.outputs.skip != 'true'
85+
uses: actions/setup-python@v5
86+
with:
87+
python-version: '3.12'
88+
89+
- name: Set up Node
90+
if: steps.guard.outputs.skip != 'true'
91+
uses: actions/setup-node@v4
92+
with:
93+
node-version: '22'
94+
95+
- name: Install Claude CLI (driven by the Agent SDK)
96+
if: steps.guard.outputs.skip != 'true'
97+
run: npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
98+
99+
- name: Run translation pipeline
100+
if: steps.guard.outputs.skip != 'true'
101+
env:
102+
# Secrets only reach the step that needs them, not the npm/pip installs.
103+
ANTHROPIC_API_KEY: ${{ secrets.I18N_ANTHROPIC_API_KEY }}
104+
GH_TOKEN: ${{ secrets.I18N_GH_TOKEN || github.token }}
105+
# Dispatch inputs go through env, never interpolated into the script.
106+
INPUT_LANG: ${{ github.event.inputs.lang }}
107+
INPUT_LIMIT: ${{ github.event.inputs.limit }}
108+
run: |
109+
args=(--limit "${INPUT_LIMIT:-$DEFAULT_PAGE_LIMIT}")
110+
if [ -n "${INPUT_LANG}" ]; then args+=(--lang "${INPUT_LANG}"); fi
111+
hack/i18n/run-daily.sh "${args[@]}"

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@ static/docs/*/cozystack-api/
2727

2828
# Claude Code local settings
2929
.claude/
30+
31+
# i18n pipeline venv (bootstrapped by hack/i18n/run-daily.sh)
32+
.venv-i18n/
33+
34+
# i18n pipeline: per-run artifacts, not content
35+
hack/i18n/last-run-findings.md
36+
3037
.demo-build-uidir
3138

3239
# demo overlay ships a public/ with the MSW worker — keep it despite the public/ ignore

‎CLAUDE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
Hugo documentation website for Cozystack (Kubernetes-based cloud platform) using the Google Docsy theme. **Production is served by GitHub Pages** — Netlify is only used for deploy previews on PRs. Do not rely on Netlify-specific features (`netlify.toml` redirects, headers, edge functions) for production behavior; they only work in deploy previews. For redirects, use Hugo aliases (per-page) or the JS fallback in `layouts/404.html`.
7+
Hugo documentation website for Cozystack (Kubernetes-based cloud platform) using the Google Docsy theme. **Production is served by GitHub Pages**. Netlify is only used for deploy previews on PRs. Do not rely on Netlify-specific redirects or headers for production behavior. The stable `/docs/` and `/docs/v<major>/` paths are real copies of the latest version, produced after `hugo` by `hack/mirror_latest.sh` (Python 3 standard library). Current numbered docs and both copies use canonical URLs under `/docs/`. Older numbered docs remain noindex and are excluded from sitemaps. Preview builds are noindex. The version-selection landing is copied to `/docs/versions/`; mirroring preserves numbered versions and unrelated legacy aliases. The `.docs-mirror.json` file tracks root and major copies for cleanup on repeat builds. Under `hugo server`, version-selection links use the existing `/docs/` landing.
88

99
## Build & Development Commands
1010

@@ -16,7 +16,7 @@ npm install
1616
make serve
1717

1818
# Production build
19-
./hack/download_openapi.sh && hugo --gc --minify
19+
./hack/download_openapi.sh && hugo --gc --minify && ./hack/mirror_latest.sh
2020

2121
# Sync app docs from cozystack/cozystack repo.
2222
# By default targets content/en/docs/next/ (the version-agnostic trunk).
@@ -66,7 +66,7 @@ Docs are versioned per Cozystack minor release. Each version is an independent c
6666
- One directory per minor version: `content/en/docs/v0/`, `v1.0/`, `v1.1/`, `v1.2/`
6767
- Version name derivation: major `0` → `v0` (legacy, covers all 0.x); major ≥ 1 → `v<major>.<minor>` (e.g., `v1.2`). Patch level is not reflected in the directory name
6868
- Each version directory is self-contained: all pages under `applications/`, `virtualization/`, `networking/`, `operations/`, `storage/`, `install/`, `guides/`, etc. live once per version
69-
- `content/en/docs/_index.md` is the single version-agnostic landing page
69+
- `content/en/docs/_index.md` is the version-selection landing, published at `/docs/versions/` after mirroring
7070
- `content/en/docs/next/` is the permanent trunk for upcoming/unreleased docs. Internal links use `/docs/next/`; these are rewritten at release time by `hack/release_next.sh`. Excluded from production builds via the `hidden: true` entry in `hugo.yaml` and the content mount exclusion `- '! docs/next/**'`
7171

7272
**Version registration (`hugo.yaml`)**

‎CONTRIBUTING.md‎

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ make init-version DOC_VERSION=v1.3 # low-level init of any version dir
225225
make show-target RELEASE_TAG=v1.3.0 # prints resolved DOC_VERSION / BRANCH
226226
```
227227

228-
Required tools: Hugo extended 0.164.0, Go 1.23+, Node 22+, `yq` v4+ (for the
228+
Required tools: Hugo extended 0.164.0, Go 1.23+, Node 22+, Python 3, `yq` v4+ (for
229229
version lifecycle targets and Makefile routing), `jq` (for
230230
`hack/download_openapi.sh` in the production build and `make update-all`
231231
without `RELEASE_TAG`).
@@ -250,10 +250,46 @@ If you need to understand or change the versioning machinery itself:
250250
cozystack/cozystack.
251251
- `hack/download_openapi.sh` — fetches `openapi.json` per version at build
252252
time (v1.1+; v0 and v1.0 ship their `api.json` in-tree).
253-
- `layouts/docs/docs-landing.html` — the `/docs/` landing template; builds the
254-
version table from `params.versions[]`, filtering out hidden entries.
253+
- `layouts/docs/docs-landing.html` — the version-selection landing template,
254+
published at `/docs/versions/`; builds the version table from `params.versions[]`,
255+
filtering out hidden entries.
255256
- `layouts/partials/version-switcher.html` — top-navbar version dropdown;
256257
filters out hidden entries.
257-
- `layouts/404.html` — client-side fallback redirect for `/docs/v1/…` short
258-
paths.
258+
- `hack/mirror_latest.sh` calls `hack/mirror_latest.py` after Hugo to copy current
259+
docs to `/docs/` and `/docs/v<major>/`. It also copies translated docs
260+
when they exist. The original landing is published at `/docs/versions/`, with a
261+
link in the version dropdown. Pages and Netlify builds run it; `make serve` does
262+
not. Local `make serve` keeps the version-selection landing and its navigation
263+
links at `/docs/`. The landing template carries `data-docs-version-landing` so
264+
repeat mirror runs can identify it independently of Open Graph metadata.
265+
- `layouts/partials/docs-seo.html` supplies canonical and robots rules to the
266+
document head and sitemap. Current numbered docs and their copies canonicalize
267+
to `/docs/`. Older versions remain noindex and stay out of sitemaps.
268+
Preview builds and print output are noindex. No archive content is removed.
269+
- `layouts/partials/head.html` overrides the Docsy v0.12.0 head to emit one robots
270+
tag. `navbar-lang-selector.html` keeps the version-selection page at its new
271+
path when changing language. Compare both with upstream when updating Docsy.
272+
273+
The mirrors add two copies of the current docs to the published artifact.
274+
Mirroring preserves numbered versions, `next/` and unrelated legacy aliases. The
275+
`.docs-mirror.json` build file tracks root and major copies and their hashes so
276+
minor and major rollover remove stale copies without deleting aliases restored
277+
by Hugo. Only tracked, unchanged files are removed. Keep the manifest when
278+
rebuilding in the same output directory. Mirrored Open Graph URLs match the
279+
stable canonical; absolute feed and print links follow the served copy.
280+
After a release, run Hugo and the mirror step together. Publishing just Hugo's
281+
output would leave the stable canonical and sitemap URLs without their pages.
282+
283+
Check the production output and release rollover with the CI-pinned Hugo:
284+
285+
```sh
286+
hugo --gc --minify --baseURL https://cozystack.io/
287+
./hack/mirror_latest.sh public
288+
python3 hack/test_docs_seo.py public --latest v1.6 # use latest_version_id
289+
HUGO=hugo python3 hack/test_docs_seo_fixtures.py
290+
```
291+
292+
The fixture suite builds small sites to check minor-release rollover, translated
293+
copies, baseURL subpaths, previews, print output, HTTP responses without JavaScript,
294+
and invalid configuration. The output check also scans the full site's sitemaps.
259295

‎Makefile‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,13 +72,16 @@ else
7272
endif
7373

7474
# App lists (override on the command line: `make update-apps APPS="tenant redis"`)
75-
APPS ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant
75+
APPS ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant valkey opensearch bucket
7676
K8S ?= kubernetes
77+
K8S_NODES ?= kubernetes-nodes
7778
VMS ?= vm-disk vm-instance
78-
NETWORKING ?= vpc vpn http-cache tcp-balancer
79+
NETWORKING ?= vpc vpn tcp-balancer
7980
SERVICES ?= bootbox etcd ingress monitoring seaweedfs
81+
SERVICES += computeplane gateway
8082
APPS_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/applications
8183
K8S_DEST_DIR ?= content/en/docs/$(DOC_VERSION)
84+
K8S_NODES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/kubernetes
8285
VMS_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/virtualization
8386
NETWORKING_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/networking
8487
SERVICES_DEST_DIR ?= content/en/docs/$(DOC_VERSION)/operations/services
@@ -99,6 +102,7 @@ update-networking:
99102

100103
update-k8s:
101104
./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
105+
./hack/update_apps.sh --apps "$(K8S_NODES)" --dest "$(K8S_NODES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)"
102106

103107
update-services:
104108
./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(FETCH_REF)" --source-ref "$(SOURCE_REF)" --pkgdir extra
@@ -186,6 +190,7 @@ template-networking:
186190
./hack/fill_templates.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)"
187191
template-k8s:
188192
./hack/fill_templates.sh --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)"
193+
./hack/fill_templates.sh --apps "$(K8S_NODES)" --dest "$(K8S_NODES_DEST_DIR)" --branch "$(BRANCH)"
189194

190195
template-services:
191196
./hack/fill_templates.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --pkgdir extra

‎assets/icons/home/api-first.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎assets/icons/home/collaborate.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎assets/icons/home/extend.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)