refactor(pages): extracted HTML into site/*.tmpl + scoped workflow triggers

Split the landing page out of build_pages.py into two stand-alone templates
(index.html.tmpl + card.html.tmpl) so the HTML can be edited without
touching Python. The renderer is now a thin substitute() + read() helper;
no Jinja or other runtime deps beyond what was already needed.

Trigger filters tightened so cosmetic Pages work never kicks off a 25 min
image build or cuts a release:

  - build.yml paths-ignore: + site/**, + scripts/build_pages.py
  - release.yml paths-ignore: same
  - pages.yml: new `push: paths: [site/**, scripts/build_pages.py,
    .github/workflows/pages.yml]` so edits redeploy the site
    automatically against the latest release.

Author: karlspace

.github/workflows/build.yml

@@ -14,13 +14,18 @@ on:
       - "LICENSE"
       - ".gitignore"
       - ".github/**"
+      # Pages site + its renderer live separately from the image build.
+      - "site/**"
+      - "scripts/build_pages.py"
   pull_request:
     branches: [main]
     paths-ignore:
       - "**.md"
       - "docs/**"
       - "LICENSE"
       - ".github/**"
+      - "site/**"
+      - "scripts/build_pages.py"
   workflow_dispatch:
     inputs:
       variant:

.github/workflows/pages.yml

@@ -22,6 +22,15 @@ name: 🌐 Pages
 on:
   release:
     types: [published, edited, released]
+  # Re-render the landing page whenever its source changes on main. The
+  # catalog still points at the LATEST release (resolved at runtime), so
+  # editing CSS or templates doesn't need a new image build.
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - 'scripts/build_pages.py'
+      - '.github/workflows/pages.yml'
   workflow_dispatch:
     inputs:
       tag:
@@ -182,14 +191,15 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p _site
-          cp site/CNAME     _site/CNAME
+          cp site/CNAME      _site/CNAME
           cp site/styles.css _site/styles.css
           python scripts/build_pages.py \
-            --manifests release-assets \
-            --tag       "$TAG" \
-            --repo      "$REPO" \
+            --manifests   release-assets \
+            --templates   site \
+            --tag         "$TAG" \
+            --repo        "$REPO" \
             --catalog-url "https://$(cat site/CNAME | tr -d '[:space:]')/rpi-imager.json" \
-            --out       _site
+            --out         _site
           echo "--- _site tree ---"
           ls -la _site
 

.github/workflows/release.yml

@@ -25,6 +25,9 @@ on:
       - 'docs/**'
       - 'LICENSE'
       - '.gitignore'
+      # Pages site + its renderer are cosmetic; never cut a release for them.
+      - 'site/**'
+      - 'scripts/build_pages.py'
   workflow_dispatch:
     inputs:
       force-release:

scripts/build_pages.py

@@ -3,21 +3,24 @@
 """
 BAUER GROUP XPD-RPIImage - Pages site + RPi Imager catalog renderer.
 
+Loads HTML templates from disk (site/*.tmpl) and substitutes {{placeholders}}.
+No Jinja or other heavy deps - keeps the Pages workflow dependency-free
+beyond what the build scripts already need.
+
 Input:
-    --manifests DIR   directory with one `*.manifest.json` per variant
-                      (produced by build.yml's checksum step)
-    --tag      vX.Y.Z tag to display on the landing page
-    --repo     owner/name   e.g. bauer-group/XPD-RPIImage
-    --out      DIR    destination directory for the rendered site
+    --manifests DIR     directory with one *.manifest.json per variant
+    --tag       vX.Y.Z  release tag to display
+    --repo      owner/name
+    --catalog-url URL   public URL of the rpi-imager.json
+    --templates DIR     directory containing index.html.tmpl + card.html.tmpl
+    --out       DIR     destination directory for the rendered site
 
 Output (in --out):
     rpi-imager.json   catalog consumed by RPi Imager's Custom Repository
-    index.html        human-facing landing page (rich info + direct flash links)
-    styles.css        minimal, framework-free styling
-    .nojekyll         disables Jekyll on GitHub Pages
+    index.html        human-facing landing page
+    .nojekyll         disables Jekyll on GitHub Pages (we ship pre-rendered HTML)
 
-CNAME is NOT rendered here - the workflow copies it from site/CNAME so the
-custom domain lives in git instead of being re-generated on every run.
+`styles.css` and `CNAME` are copied by the workflow, not rendered here.
 """
 from __future__ import annotations
 
@@ -30,8 +33,7 @@
 from typing import Any
 
 
-# RPi Imager devices names - mapping our JSON `targets` enum to Imager's
-# board identifiers. Entries left out here will be hidden on unknown boards.
+# RPi Imager device names - maps our JSON targets to Imager's identifiers.
 TARGET_TO_IMAGER_DEVICE = {
     "rpi4": "pi4-64bit",
     "rpi5": "pi5",
@@ -41,7 +43,6 @@
 
 
 def load_manifests(directory: Path) -> list[dict[str, Any]]:
-    """Read every `*.manifest.json` in `directory`, sorted by variant name."""
     paths = sorted(directory.glob("*.manifest.json"))
     if not paths:
         print(f"error: no *.manifest.json in {directory}", file=sys.stderr)
@@ -53,8 +54,21 @@ def load_manifests(directory: Path) -> list[dict[str, Any]]:
     return out
 
 
+def substitute(template: str, values: dict[str, str]) -> str:
+    """Replace every `{{key}}` with `values[key]`.
+
+    Values that are missing are kept as-is so typos are visible in the
+    rendered output rather than silently expanding to empty. No nested
+    substitution, no conditionals - if the template grows logic beyond
+    this, promote to Jinja2 with a proper test suite.
+    """
+    out = template
+    for key, value in values.items():
+        out = out.replace("{{" + key + "}}", value)
+    return out
+
+
 def render_rpi_imager_json(manifests: list[dict[str, Any]], tag: str) -> dict[str, Any]:
-    """Produce the RPi Imager Custom Repository JSON."""
     os_list: list[dict[str, Any]] = []
     for m in manifests:
         variant = m["variant"]
@@ -80,163 +94,76 @@ def render_rpi_imager_json(manifests: list[dict[str, Any]], tag: str) -> dict[st
     }
 
 
-def render_index_html(manifests: list[dict[str, Any]], tag: str, repo: str, catalog_url: str) -> str:
-    """Produce the standalone landing page."""
+def render_card(template: str, manifest: dict[str, Any], tag: str) -> str:
+    img = manifest["image"]
+    sha256_url   = img["url"] + ".sha256"
+    # bgrpiimage-<variant>-vX.Y.Z.img.xz → bgrpiimage-<variant>-vX.Y.Z.manifest.json
+    manifest_url = img["url"].rsplit(".img.xz", 1)[0] + ".manifest.json"
+    values = {
+        "variant":         html.escape(manifest["variant"]),
+        "tag":             html.escape(tag),
+        "description":     html.escape(manifest.get("description") or ""),
+        "hostname":        html.escape(manifest.get("hostname") or "-"),
+        "targets":         html.escape(", ".join(manifest["targets"])),
+        "download_mib":    f"{img['download_size'] / 1024 / 1024:,.1f}",
+        "extract_mib":     f"{img['extract_size']  / 1024 / 1024:,.1f}",
+        "release_date":    html.escape(manifest.get("release_date") or "-"),
+        "download_sha256": html.escape(img["download_sha256"]),
+        "extract_sha256":  html.escape(img["extract_sha256"]),
+        "image_url":       html.escape(img["url"]),
+        "sha256_url":      html.escape(sha256_url),
+        "manifest_url":    html.escape(manifest_url),
+    }
+    return substitute(template, values)
+
+
+def render_index_html(
+    index_template: str,
+    card_template: str,
+    manifests: list[dict[str, Any]],
+    tag: str,
+    repo: str,
+    catalog_url: str,
+) -> str:
+    cards = "\n".join(render_card(card_template, m, tag) for m in manifests)
     generated = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
-    cards = []
-    for m in manifests:
-        variant = m["variant"]
-        img = m["image"]
-        targets = ", ".join(m["targets"])
-        download_mb = img["download_size"] / 1024 / 1024
-        extract_mb = img["extract_size"] / 1024 / 1024
-        card = f"""
-        <article class="card">
-          <header>
-            <h2>{html.escape(variant)}</h2>
-            <span class="tag">{html.escape(tag)}</span>
-          </header>
-          <p class="description">{html.escape(m.get('description') or '')}</p>
-          <dl class="meta">
-            <dt>Hostname</dt><dd><code>{html.escape(m.get('hostname') or '-')}</code></dd>
-            <dt>Targets</dt><dd>{html.escape(targets)}</dd>
-            <dt>Download size</dt><dd>{download_mb:,.1f} MiB</dd>
-            <dt>Extracted size</dt><dd>{extract_mb:,.1f} MiB</dd>
-            <dt>Release date</dt><dd>{html.escape(m.get('release_date') or '-')}</dd>
-          </dl>
-          <div class="checksums">
-            <div><span class="label">SHA-256 (.img.xz)</span><code>{html.escape(img['download_sha256'])}</code></div>
-            <div><span class="label">SHA-256 (.img)</span><code>{html.escape(img['extract_sha256'])}</code></div>
-          </div>
-          <div class="actions">
-            <a class="btn primary" href="{html.escape(img['url'])}">⬇ Download .img.xz</a>
-            <a class="btn"         href="{html.escape(img['url'])}.sha256">.sha256</a>
-            <a class="btn"         href="{html.escape(img['url']).rsplit('.img.xz', 1)[0]}.manifest.json">manifest.json</a>
-          </div>
-        </article>
-        """
-        cards.append(card)
-
-    cards_html = "\n".join(cards)
-    catalog_copy_id = "catalog-url"
-    safe_repo = html.escape(repo)
-    safe_tag = html.escape(tag)
-    safe_catalog = html.escape(catalog_url)
-    safe_generated = html.escape(generated)
-
-    return f"""<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>BAUER GROUP RPIImage – latest release {safe_tag}</title>
-  <meta name="description" content="Declarative, reproducible Raspberry Pi OS images by BAUER GROUP. RPi Imager catalog + direct downloads." />
-  <link rel="stylesheet" href="styles.css" />
-  <link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20100%20100%22%3E%3Crect%20width%3D%22100%22%20height%3D%22100%22%20rx%3D%2220%22%20fill%3D%22%23e80d2e%22%2F%3E%3Ctext%20x%3D%2250%22%20y%3D%2268%22%20font-family%3D%22sans-serif%22%20font-size%3D%2258%22%20font-weight%3D%22900%22%20fill%3D%22white%22%20text-anchor%3D%22middle%22%3EB%3C%2Ftext%3E%3C%2Fsvg%3E" />
-</head>
-<body>
-  <header class="hero">
-    <div class="inner">
-      <h1>📦 BAUER GROUP <span class="accent">RPIImage</span></h1>
-      <p class="subtitle">Declarative, reproducible, CI-built Raspberry Pi OS images for production and development.</p>
-      <p class="release">Current release: <a href="https://github.com/{safe_repo}/releases/tag/{safe_tag}"><strong>{safe_tag}</strong></a></p>
-    </div>
-  </header>
-
-  <main>
-    <section class="pitch">
-      <h2>🛠 Add this repo to Raspberry Pi Imager</h2>
-      <ol class="steps">
-        <li>Install <a href="https://www.raspberrypi.com/software/">Raspberry Pi Imager</a> (v1.8.5 or later).</li>
-        <li>Open it and go to <strong>Settings</strong> (the ⚙ icon) → <strong>Custom repository</strong>.</li>
-        <li>Paste the catalog URL below and close the settings dialog:
-          <div class="copyrow">
-            <code id="{catalog_copy_id}">{safe_catalog}</code>
-            <button type="button" onclick="navigator.clipboard.writeText(document.getElementById('{catalog_copy_id}').innerText)">Copy</button>
-          </div>
-        </li>
-        <li>Restart Imager. Our variants now appear under <strong>Operating System → BAUER GROUP</strong>.</li>
-        <li>Pick your target device → pick an image → flash.</li>
-      </ol>
-
-      <h3>🧷 Flashing a Compute Module (CM4 / CM5 eMMC)</h3>
-      <ol>
-        <li>Put the carrier board in <strong>rpiboot mode</strong>:
-          <ul>
-            <li><strong>CM4 IO-Board</strong>: fit the jumper on <code>J2</code> (Disable eMMC Boot).</li>
-            <li><strong>CM5 IO-Board</strong>: bridge the <code>nRPIBOOT</code> test pad (or set the fit-jumper where provided).</li>
-          </ul>
-        </li>
-        <li>Connect the <strong>USB-C slave port</strong> (not the host USB) to your machine.</li>
-        <li>Power the board. RPi Imager (≥ 1.8.5) detects the CM as <em>"RPi"</em> mass storage via its built-in <code>rpiboot</code>.</li>
-        <li>Flash as usual.</li>
-        <li>Remove the jumper, re-power, boot.</li>
-      </ol>
-    </section>
-
-    <section class="variants">
-      <h2>🧩 Variants in this release</h2>
-      <div class="cards">
-        {cards_html}
-      </div>
-    </section>
-
-    <section class="security">
-      <h2>🔐 Default credentials</h2>
-      <p>These images ship with <strong>demo credentials</strong> - safe only on an isolated lab network:</p>
-      <ul>
-        <li><code>admin</code> password → <code>12345678</code></li>
-        <li>WiFi PSK for <code>IOT @ BAUER-GROUP</code> → <code>12345678</code></li>
-      </ul>
-      <p>Bake real values at build time via <code>.env</code>, or change them post-flash with:</p>
-      <pre><code>sudo bgrpiimage-setup password
-sudo bgrpiimage-setup wifi "MyNet" "s3cret" DE
-sudo bgrpiimage-setup ip eth0 static 10.0.0.5/24 10.0.0.1 1.1.1.1</code></pre>
-    </section>
-
-    <section class="meta-links">
-      <h2>📚 More</h2>
-      <ul>
-        <li><a href="https://github.com/{safe_repo}">Repository on GitHub</a></li>
-        <li><a href="https://github.com/{safe_repo}/releases">All releases</a></li>
-        <li><a href="https://github.com/{safe_repo}/blob/main/docs/hardware.md">Hardware reference</a></li>
-        <li><a href="https://github.com/{safe_repo}/blob/main/docs/flash.md">Flashing guide</a></li>
-        <li><a href="https://github.com/{safe_repo}/blob/main/docs/configuration.md">JSON configuration reference</a></li>
-      </ul>
-    </section>
-  </main>
-
-  <footer>
-    <p>© BAUER GROUP · <a href="https://github.com/{safe_repo}/blob/main/LICENSE">MIT</a> · generated {safe_generated}</p>
-  </footer>
-</body>
-</html>
-"""
+    return substitute(index_template, {
+        "tag":         html.escape(tag),
+        "repo":        html.escape(repo),
+        "catalog_url": html.escape(catalog_url),
+        "cards":       cards,
+        "generated":   html.escape(generated),
+    })
 
 
 def main() -> int:
     p = argparse.ArgumentParser(description=__doc__)
-    p.add_argument("--manifests", required=True, type=Path)
-    p.add_argument("--tag",       required=True)
-    p.add_argument("--repo",      required=True)
-    p.add_argument("--catalog-url", required=True,
-                   help="Public URL where rpi-imager.json will be served.")
-    p.add_argument("--out",       required=True, type=Path)
+    p.add_argument("--manifests",   required=True, type=Path)
+    p.add_argument("--tag",         required=True)
+    p.add_argument("--repo",        required=True)
+    p.add_argument("--catalog-url", required=True)
+    p.add_argument("--templates",   required=True, type=Path,
+                   help="directory with index.html.tmpl + card.html.tmpl")
+    p.add_argument("--out",         required=True, type=Path)
     args = p.parse_args()
 
     args.out.mkdir(parents=True, exist_ok=True)
     manifests = load_manifests(args.manifests)
 
+    # --- rpi-imager.json -----------------------------------------------------
     catalog = render_rpi_imager_json(manifests, args.tag)
     (args.out / "rpi-imager.json").write_text(
         json.dumps(catalog, indent=2) + "\n", encoding="utf-8"
     )
 
-    html_text = render_index_html(manifests, args.tag, args.repo, args.catalog_url)
+    # --- index.html ----------------------------------------------------------
+    index_tmpl = (args.templates / "index.html.tmpl").read_text(encoding="utf-8")
+    card_tmpl  = (args.templates / "card.html.tmpl").read_text(encoding="utf-8")
+    html_text = render_index_html(index_tmpl, card_tmpl, manifests,
+                                   args.tag, args.repo, args.catalog_url)
     (args.out / "index.html").write_text(html_text, encoding="utf-8")
 
-    # .nojekyll disables the default Jekyll build on GitHub Pages - we ship
-    # pre-rendered HTML and don't want Jekyll to mangle it.
+    # --- .nojekyll -----------------------------------------------------------
     (args.out / ".nojekyll").write_text("", encoding="utf-8")
 
     print(f"wrote {len(manifests)} variant(s) into {args.out}", file=sys.stderr)

site/card.html.tmpl

@@ -0,0 +1,23 @@
+        <article class="card">
+          <header>
+            <h2>{{variant}}</h2>
+            <span class="tag">{{tag}}</span>
+          </header>
+          <p class="description">{{description}}</p>
+          <dl class="meta">
+            <dt>Hostname</dt><dd><code>{{hostname}}</code></dd>
+            <dt>Targets</dt><dd>{{targets}}</dd>
+            <dt>Download size</dt><dd>{{download_mib}} MiB</dd>
+            <dt>Extracted size</dt><dd>{{extract_mib}} MiB</dd>
+            <dt>Release date</dt><dd>{{release_date}}</dd>
+          </dl>
+          <div class="checksums">
+            <div><span class="label">SHA-256 (.img.xz)</span><code>{{download_sha256}}</code></div>
+            <div><span class="label">SHA-256 (.img)</span><code>{{extract_sha256}}</code></div>
+          </div>
+          <div class="actions">
+            <a class="btn primary" href="{{image_url}}">⬇ Download .img.xz</a>
+            <a class="btn"         href="{{sha256_url}}">.sha256</a>
+            <a class="btn"         href="{{manifest_url}}">manifest.json</a>
+          </div>
+        </article>