Add docs for 'Get AlmaLinux' page (#913)

* add docs and some more functionality for generate get-almalinux 

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: alexiri

.devcontainer/devcontainer.json

@@ -32,5 +32,5 @@
   },
   "forwardPorts": [1313],
   "remoteUser": "alma_www_user",
-  "postCreateCommand": "echo 'function git_branch() { local branch; branch=\"$(git symbolic-ref --short HEAD 2> /dev/null)\"; if [[ -n \"$branch\" ]]; then echo -n \"$branch\"; return 0; fi; return 1; } && function git_has_changes() { git diff --quiet HEAD 2> /dev/null || echo -n \"✗\"; } && export WHITE=\"\\[\\033[1;37m\\]\" && export GREEN=\"\\[\\033[0;32m\\]\" && export BLUE=\"\\[\\033[0;94m\\]\" && export RED=\"\\[\\033[1;31m\\]\" && export YELLOW=\"\\[\\033[1;33m\\]\" && export RESET=\"\\[\\033[0m\\]\" && function prompt_command() { PS1=\"${GREEN}\\u${WHITE} ➜ ${BLUE}\\w ${BLUE}(${RED}\\$(git_branch)${YELLOW}\\$(git_has_changes)${BLUE})${RESET}$ \"; } && export PROMPT_COMMAND=\"prompt_command\"' >> ~/.bashrc"
+  "postCreateCommand": ".devcontainer/post-create.sh"
 }

.devcontainer/post-create.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Idempotent append of nice git prompt functions to ~/.bashrc
+if ! grep -q "function git_branch()" "$HOME/.bashrc" 2>/dev/null; then
+  cat >> "$HOME/.bashrc" <<'BASHRC_APPEND'
+function git_branch() { local branch; branch="$(git symbolic-ref --short HEAD 2> /dev/null)"; if [[ -n "$branch" ]]; then echo -n "$branch"; return 0; fi; return 1; }
+function git_has_changes() { git diff --quiet HEAD 2> /dev/null || echo -n "✗"; }
+export WHITE="\[\033[1;37m\]"
+export GREEN="\[\033[0;32m\]"
+export BLUE="\[\033[0;94m\]"
+export RED="\[\033[1;31m\]"
+export YELLOW="\[\033[1;33m\]"
+export RESET="\[\033[0m\]"
+function prompt_command() { PS1="${GREEN}\u${WHITE} ➜ ${BLUE}\w ${BLUE}(${RED}\$(git_branch)${YELLOW}\$(git_has_changes)${BLUE})${RESET}$ "; }
+export PROMPT_COMMAND="prompt_command"
+BASHRC_APPEND
+fi
+
+# Run generator only if output file is missing. This keeps rebuilds fast and avoids overwriting
+if [ ! -f data/get_almalinux.yaml ]; then
+  echo 'Generating data/get_almalinux.yaml (first-run)...'
+  if command -v python3 >/dev/null 2>&1; then
+    python3 tools/generate_get_almalinux_yaml.py || echo 'Warning: generator failed'
+  else
+    echo 'python3 not found; skipping generator. You can run: python3 tools/generate_get_almalinux_yaml.py'
+  fi
+else
+  echo 'data/get_almalinux.yaml already present; skipping generation.'
+fi
+
+exit 0

.github/workflows/publish-preview.yml

@@ -1,4 +1,4 @@
-on: pull_request
+on: pull_request_target
 
 jobs:
   authorize:

README.md

@@ -46,9 +46,9 @@ For smaller contributions, follow this workflow:
 
 After review and approval, the changes will be merged into the `main` branch and deployed to the live site.
 
-#### For Developers
+### For Developers
 
-##### Local Development
+#### Local Development
 
 To set up a local development environment, you need the following installed:
 
@@ -58,7 +58,7 @@ Run `hugo server` to start a near-production local development instance.
 
 Localization is important! Please include proper localization formatting in your PR. After formatting, run `find_missing_i18n_strings.py` and `setup-pages-for-supported-languages.py`, then commit the changes. If you encounter issues with these scripts, please open an [issue](https://github.com/AlmaLinux/almalinux.org/issues) with details.
 
-##### Container Development
+#### Container Development
 
 To use a container-based development environment, install Docker and use an editor supporting the devcontainer standard. Details can be found in the [README](.devcontainer/README.md).
 
@@ -69,10 +69,89 @@ To use a container-based development environment, install Docker and use an edit
 - `/i18n/` — Localization and translation files
 - `/static/` — Static files
 - `/content/` — Markdown content for site pages
+- `/data/` — Source data, currently only for the "Get AlmaLinux" page
 - `config.yaml` — Hugo configuration
 - `find_missing_i18n_strings.py` — Detects untranslated strings in `i18n/en.json`
 - `setup-pages-for-supported-languages.py` — Creates placeholder markdown pages for missing languages
 
+#### Updating 'Get AlmaLinux' page
+
+The "Get AlmaLinux" page is dynamically generated using structured data and Hugo partial templates. This section explains how the data flows, which files are involved, and how to update the page for new releases or changes.
+
+**How it works:**
+
+- **Data sources:**
+  - `data/get_almalinux_spec.yaml`: Defines available AlmaLinux versions, supported architectures, and the configuration for
+    each section (e.g., ISO, Cloud, Container).
+  - `data/get_almalinux_checksums.yaml`: Contains, for each version, the current highest point release (`fullVersion`) and the
+    checksums for all artifacts (ISOs and cloud images) per architecture. This file can (and probably will) be generated.
+
+- **Generation script:**
+  - The script `tools/generate_get_almalinux_checksums.py` reads `data/get_almalinux_spec.yaml`, queries
+    the CHECKSUM URLs defined for ISO and Cloud images, extracts the checksums and the current minor release
+    and produces `data/get_almalinux_checksums.yaml`.
+  - The script `tools/generate_get_almalinux_yaml.py` reads both YAML files, merges their data, and produces `data/get_almalinux.yaml`. This merged file is used by the Hugo partials to render the page.
+  - `data/get_almalinux.yaml` is **not** tracked in git. It is generated automatically by the GitHub CI workflow during site builds, but you must run the script manually for local development if you change the source YAML files.
+
+- **Templates:**
+  - Hugo partials in `layouts/partials/get-almalinux/` render the page:
+    - `tabs.html`: Renders version tabs and architecture dropdowns.
+    - `tab-content.html`: Generates the content for each tab panel.
+    - `arch-sections.html`: Generates the page for each version+architecture combination.
+    - `section-*.html`: Renders each section (ISO, Cloud, Container, etc.) that makes up a full page.
+
+##### Editing for a New Point Release
+
+**In most cases, you only need to update `get_almalinux_checksums.yaml` when a new point release is available.**
+
+1. Run the checksum generation script to update `get_almalinux_checksums.yaml` by looking at the source repos:
+   ```bash
+   python3 tools/generate_get_almalinux_checksums.py
+   ```
+2. Optionally, run the generation script to see your changes locally:
+   ```bash
+   python3 tools/generate_get_almalinux_yaml.py
+   ```
+   This updates `data/get_almalinux.yaml` for use by Hugo.
+   This will be done automatically by the Gitlab CI scripts during deployment.
+3. Commit the resulting changes to `data/get_almalinux_checksums.yaml` and open a PR.
+
+##### Editing Sections, Architectures, or URL Patterns
+
+If you need to change which sections or architectures are shown, or adjust how URLs are generated, edit `data/get_almalinux_spec.yaml`:
+
+- The YAML file contains a `common` block, which sets default configuration for each section. These defaults are merged with per-version overrides in the `versions` array.
+- Each version entry includes:
+  - `id`: The major version (e.g., `10`, `10-kitten`).
+  - `label`: The tab title.
+  - `arches`: List of supported architectures (becomes dropdowns in the page).
+  - `sections`: List of sections to configure for that version.
+- Each section (such as `iso` or `cloud`) can inherit from `common` but may be overridden per version or architecture.
+  - A section may have its own `arches` array to restrict it to certain architectures. For example, if cloud images for AlmaLinux 10 on `ppc64le` are not supported, the `cloud` section's `arches` array should exclude `ppc64le`.
+  - To remove a section entirely for a version, omit it from the version's `sections` list.
+  - To remove a specific cloud image within the `cloud` section, define it with no content (see the `oci` section in 10-kitten as an example).
+
+##### URL Patterns and Variables
+
+Most sections define URL templates for artifacts, using variables such as:
+
+- `major`: The major version, from `id` (e.g., `10`, `10-kitten`).
+- `full`: The full version, from `fullVersion` in `get_almalinux_checksums.yaml` (e.g., `10.1`). If `fullVersion` is not set, it falls back to `id`.
+- `arch`: The architecture (e.g., `x86_64`, `x86_64_v2`).
+
+Some URLs may allow other variables (like `variant`), or require different patterns per architecture (e.g., `vagrant`'s `registryUrls`). For advanced options, consult the code in `tools/generate_get_almalinux_yaml.py`.
+
+##### Summary of Workflow
+
+1. Edit `get_almalinux_checksums.yaml` for new point releases, or `get_almalinux_spec.yaml` for section/architecture changes.
+2. Run the generation script to update the merged YAML:
+   ```bash
+   python3 tools/generate_get_almalinux_yaml.py
+   ```
+3. Start or restart the Hugo server to see your changes locally.
+
+If you have questions about advanced configuration or variable support, refer to the script or open an issue for help.
+
 ### Localization and Translation
 
 AlmaLinux.org translations are managed on [Weblate](https://hosted.weblate.org/engage/almalinux/). To contribute, join the [AlmaLinux project](https://hosted.weblate.org/projects/almalinux/) on Weblate. Submissions through Weblate generate automated PRs to this repo, which are reviewed and merged by the Marketing SIG or another team lead.
@@ -83,7 +162,7 @@ To request a new language, open an issue in [GitHub issues](https://github.com/A
 
 [![Translation status](https://hosted.weblate.org/widget/almalinux/website-backend/multi-auto.svg)](https://hosted.weblate.org/engage/almalinux/)
 
-## Change Approval Process
+### Change Approval Process
 
 - Minor or cosmetic changes (typos, small style tweaks) can be reviewed and approved by any contributor with merge rights.
 - Non-cosmetic changes require approval from the Marketing Lead.