diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..d759e45
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,47 @@
+name: Build and deploy site
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ schedule: # GitHub pauses this after 60 days without repo activity; re-enable in the Actions tab
+ - cron: "17 4 * * *" # daily, picks up new repos and descriptions
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: pages-${{ github.ref }}
+ cancel-in-progress: false
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-python@v7
+ with:
+ python-version: "3.12"
+ - run: pip install -r requirements.txt
+ - run: python -m pytest -q
+ - run: python generate.py --out _site
+ env:
+ GH_TOKEN: ${{ github.token }}
+ - uses: actions/upload-pages-artifact@v5
+ with:
+ path: _site
+
+ deploy:
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+ needs: build
+ runs-on: ubuntu-latest
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - id: deployment
+ uses: actions/deploy-pages@v5
diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..0d91a54
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+0.3.0
diff --git a/generate.py b/generate.py
new file mode 100644
index 0000000..6494b41
--- /dev/null
+++ b/generate.py
@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Generate the static LLM-Coding org site: project overview, llms.txt and shortlinks.
+
+Data comes from the GitHub API via the `gh` CLI. Output goes to `_site/`.
+Usage: python3 generate.py [--out _site] [--org LLM-Coding]
+"""
+import argparse
+import hashlib
+import html
+import json
+import re
+import shutil
+import subprocess
+import sys
+import urllib.request
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urljoin, urlparse
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent
+SITE_URL = "https://llm-coding.github.io/"
+ORG_SITE_REPO = "llm-coding.github.io"
+RESERVED_KEYS = {"icons", "sl", "index", "llms", "style"}
+KEY_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+ICON_TYPES = {"image/png": "png", "image/svg+xml": "svg", "image/x-icon": "ico",
+ "image/vnd.microsoft.icon": "ico", "image/jpeg": "jpg", "image/webp": "webp"}
+USER_AGENT = "llm-coding-site-generator"
+esc = html.escape
+
+
+# --- data -----------------------------------------------------------------
+
+def gh_api(path):
+ out = subprocess.run(["gh", "api", path], check=True, capture_output=True, text=True).stdout
+ return json.loads(out)
+
+
+def gh_api_list(path):
+ out = subprocess.run(["gh", "api", "--paginate", path, "--jq", ".[]"], check=True,
+ capture_output=True, text=True).stdout
+ return [json.loads(line) for line in out.splitlines() if line.strip()]
+
+
+def pages_url(repo):
+ try:
+ url = gh_api(f"repos/{repo['full_name']}/pages").get("html_url")
+ except (subprocess.CalledProcessError, AttributeError):
+ url = None
+ homepage = repo.get("homepage") or ""
+ if not is_http(homepage):
+ homepage = ""
+ return url or homepage or f"{SITE_URL}{repo['name']}/"
+
+
+def is_http(url):
+ return urlparse(url).scheme in ("http", "https")
+
+
+def select_projects(repos, overrides, org_site_repo=ORG_SITE_REPO):
+ """Repos with Pages, minus archived, the org site, excluded ones and forks (unless included)."""
+ def wanted(r):
+ ov = overrides.get(r["name"], {})
+ return (r.get("has_pages") and not r.get("archived")
+ and r["name"].lower() != org_site_repo.lower()
+ and not ov.get("exclude") and (not r.get("fork") or ov.get("include")))
+ chosen = [r for r in repos if wanted(r)]
+ return sorted(chosen, key=lambda r: r["name"].lower())
+
+
+def display_name(repo, overrides):
+ return overrides.get(repo["name"], {}).get("name") or repo["name"]
+
+
+def description(repo, overrides):
+ return (overrides.get(repo["name"], {}).get("description")
+ or (repo.get("description") or "").strip())
+
+
+def load_overrides(path):
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) if path.exists() else None
+ result = {}
+ for key, v in (data or {}).items():
+ v = v or {}
+ entry = {f: str(v[f]) for f in ("name", "description") if v.get(f)}
+ entry.update({f: True for f in ("include", "exclude") if v.get(f) is True})
+ result[str(key)] = entry
+ return result
+
+
+def load_yaml(path):
+ data = yaml.safe_load(path.read_text(encoding="utf-8")) if path.exists() else None
+ return {str(k): str(v) for k, v in (data or {}).items()}
+
+
+def validate_links(links, repo_names):
+ names = {n.lower() for n in repo_names}
+ for key, url in links.items():
+ if not KEY_RE.match(key):
+ raise ValueError(f"Invalid shortlink key {key!r}: use a-z, 0-9 and '-'")
+ if key in RESERVED_KEYS:
+ raise ValueError(f"Shortlink key {key!r} is reserved")
+ if key in names:
+ raise ValueError(f"Shortlink key {key!r} collides with a repository page")
+ if not is_http(url):
+ raise ValueError(f"Shortlink {key!r} needs an http(s) URL, got {url!r}")
+
+
+# --- icons ----------------------------------------------------------------
+
+class _IconParser(HTMLParser):
+ def __init__(self):
+ super().__init__()
+ self.apple, self.icons = [], []
+
+ def handle_starttag(self, tag, attrs):
+ a = dict(attrs)
+ if tag != "link" or not a.get("href"):
+ return
+ rel = (a.get("rel") or "").lower().split()
+ size = max((int(s.split("x")[0]) for s in (a.get("sizes") or "").split()
+ if re.match(r"^\d+x\d+$", s)), default=0)
+ if "apple-touch-icon" in rel:
+ self.apple.append((size, a["href"]))
+ elif "icon" in rel:
+ self.icons.append((size, a["href"]))
+
+
+def find_icons(page_html, base_url):
+ """Icon URL candidates, best first: largest apple-touch-icon, rel=icon, /favicon.ico."""
+ p = _IconParser()
+ p.feed(page_html)
+ hrefs = [h for _, h in sorted(p.apple, key=lambda x: -x[0])]
+ hrefs += [h for _, h in sorted(p.icons, key=lambda x: -x[0])]
+ urls = [urljoin(base_url, h) for h in hrefs] + [urljoin(base_url, "/favicon.ico")]
+ return list(dict.fromkeys(urls))
+
+
+def fetch(url, timeout=15):
+ if not is_http(url):
+ raise ValueError(f"Refusing non-http(s) URL {url!r}")
+ req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return resp.headers.get_content_type(), resp.read()
+
+
+def fetch_icon(site_url):
+ """Return (extension, bytes, url) of the site's icon, or None."""
+ try:
+ _, page = fetch(site_url)
+ candidates = find_icons(page.decode("utf-8", "replace"), site_url)
+ except Exception as e: # noqa: BLE001 — a dead site must not break the build
+ print(f" ! {site_url}: {e}", file=sys.stderr)
+ candidates = [urljoin(site_url, "/favicon.ico")]
+ for url in candidates:
+ try:
+ ctype, data = fetch(url)
+ except Exception: # noqa: BLE001
+ continue
+ ext = ICON_TYPES.get(ctype) or Path(urlparse(url).path).suffix.lstrip(".").lower()
+ if data and ext in ICON_TYPES.values():
+ return ext, data, url
+ return None
+
+
+def drop_shared_icons(icons):
+ """Drop icons used by several sites (e.g. the docToolchain default) — they tell nothing apart."""
+ digests = {}
+ for name, (_, data, *_) in icons.items():
+ digests.setdefault(hashlib.sha256(data).hexdigest(), []).append(name)
+ shared = {n for names in digests.values() if len(names) > 1 for n in names}
+ return {n: v for n, v in icons.items() if n not in shared}
+
+
+def initial_icon(name):
+ hue = int(hashlib.sha256(name.encode()).hexdigest(), 16) % 360
+ letter = esc(next((c for c in name if c.isalnum()), "?").upper())
+ return (f'')
+
+
+# --- rendering ------------------------------------------------------------
+
+def page(title, body, version, generated, description_text=""):
+ meta = f'\n' if description_text else ""
+ return f"""
+
+
+
+
+{esc(title)}
+{meta}
+
+
+
+
+
+
+{body}
+
+
+
+
+"""
+
+
+def render_index(projects, links, version, generated):
+ items = []
+ for p in projects:
+ icon = (f'
'
+ if p.get("icon") else initial_icon(p["name"]))
+ items.append(f"""
+{icon}
+
+""")
+ body = f"""LLM-Coding projects
+Open projects about software development with large language models.
+Each one has its own website.
+
+{len(links)} shortlink{"s" if len(links) != 1 else ""}: overview.
"""
+ return page("LLM-Coding – projects", body, version, generated,
+ "Overview of all LLM-Coding projects with their websites.")
+
+
+def render_llms(projects, links, version):
+ lines = ["# LLM-Coding", "",
+ "> Open projects about software development with large language models.", "",
+ f"Version {version}. Source: https://github.com/LLM-Coding/{ORG_SITE_REPO}", "",
+ "## Projects", ""]
+ lines += [f"- [{p.get('title') or p['name']}]({p['url']}): {p['description']}"
+ for p in projects]
+ lines += ["", "## Shortlinks", ""]
+ lines += [f"- {SITE_URL}{k}/ -> {u}" for k, u in links.items()]
+ return "\n".join(lines) + "\n"
+
+
+def render_redirect(key, url):
+ u = esc(url)
+ return f"""
+
+
+
+
+
+
+
+Redirecting to {u}
+
+
+
+Redirecting to {u} …
+
+
+"""
+
+
+def render_shortlinks(links, version, generated):
+ rows = "\n".join(
+ f'| {esc(SITE_URL)}{esc(k)} | '
+ f'{esc(u)} |
' for k, u in sorted(links.items()))
+ body = f"""Shortlinks
+Short addresses for slides and QR codes.
+
+| Shortlink | Target |
|---|
+
+{rows}
+
+