Static Site → GitHub Pages
Workflow komplett: Daten → eigenständige HTML/CSS/JS-Seite → Browser-Verifikation → GitHub Pages-Veröffentlichung.
Ziel: Seiten mit 1 bis wenigen hundert Elementen, Einzelautor, null Laufzeitabhängigkeiten.
Wann verwenden
| Ja | Nein |
|---|---|
| „Mach mir eine Seite mit dieser Liste / dieser Tabelle“, Galerie, Daten-Dashboard | App mit Backend, Auth, Datenbank → vorher nachfragen |
| „Veröffentliche es auf GitHub / GitHub Pages“ | Von einem Framework (Next, Astro, Hugo) generierte Site → dem Framework-Fluss folgen |
| Nachbau einer bestehenden Seite als Daten (Titel, Daten, Preise…) | Kopie des Designs/CSS/HTML einer Drittanbieter-Seite → ablehnen, sauberes Design neu erstellen |
Unverhandelbare Regeln
- Eigenes Design. Niemals das CSS, HTML oder die Assets einer Drittanbieter-Seite kopieren. Von der Informationsstruktur inspiriert sein ist OK; das Erscheinungsbild übernehmen nicht.
- Fakten ja, Werke nein. Titel, Daten, Preise, Bewertungen, Links = faktische Daten, wiederverwendbar. Redaktionelle Texte, Beschreibungen, visuelle Elemente = geschützt: nicht kopieren. Bei Bildern: das ursprüngliche CDN hotlinken statt sie zu committen (siehe
reference/data-and-ethics.md). - Zugriffsschutz respektieren.
robots.txt, das Crawler verbietet, Cloudflare/Bot-Challenge → nicht umgehen. Nach offizieller API, Schlüssel suchen oder auf einfachen ausgehenden Link zurückstufen. - Immer in einem echten Browser prüfen, bevor man „fertig“ sagt (Screenshot + Klick-Test).
- Nicht ohne Bestätigung des Repository-Namens / Accounts veröffentlichen, falls mehrdeutig.
- Keine benutzerdefinierte Domain ohne Bestätigung erstellen. Wenn der Benutzer sie nicht angegeben hat, fragen, ob er eine Cloudflare-Weiterleitung möchte und auf welcher Domain (Schritt 6). Niemals eine Subdomain erfinden oder eigenständig eine erstellen: DNS ist ein extern sichtbarer Nebeneffekt.
Workflow
1. Abgrenzen (30 s)
-
Welche Daten, wie viele Einträge, einmalige oder wiederkehrende Aktualisierung?
-
Erwartete Ausgabe: eine Seite? Suche/Sortierung? Welche Geschäftslogik für die Anzeige?
-
Wo veröffentlichen: GitHub-Account, Repository-Name, öffentlich/privat (Pages erfordert öffentliches Repository bei kostenlosen Accounts).
-
Benutzerdefinierte Domain – explizit nachfragen, falls nicht angegeben. Die Frage einmal stellen, mit Standardvorschlag:
Möchtest du eine Cloudflare-Weiterleitung zu
<owner>.github.io(CNAME, Proxy deaktiviert)? Wenn ja, welche Subdomain/Rubrik?Der Name ist auf Skill-Seite frei, aber die Domain ist ab Erstellung öffentlich: nichts ohne explizite Antwort erstellen. Antwortet der Benutzer mit Nein, bei der URL
https://<owner>.github.io/<repo>/bleiben und keinen DNS-Eintrag anlegen.
2. Daten abrufen
Ein einziger Skriptdurchlauf → eine data.json = Quelle der Wahrheit, getrennt vom Rendern.
python3 fetch_data.py # → data.json
Höflichkeit: 0,3–0,7 s zwischen Anfragen, expliziter User-Agent, Wiederholung bei 429/5xx.
Details und knifflige Fälle (PoW Anubis, Cloudflare, unscharfer Abgleich, API ohne Schlüssel): reference/data-and-ethics.md.
3. Seite generieren
Von Vorlagen ausgehen, nicht von Grund auf:
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py: kleiner Python-Generator (f-String +html.escape), der Daten in ein Kartenraster einfügt. Kein JS-Laufzeit für Daten.styles.css: Standard-Dunkelthema, Rasterauto-fill minmax(), CSS-Variablen.script.js: Sofortsuche + Sortierung + berechnete Anzeigeregeln beim Öffnen (damit die Seite ohne Rebuild aktuell bleibt).- Alles, was beim Anzeigen berechnet werden kann (Status, relative Daten), sollte in JS erfolgen: das vermeidet täglichen Rebuild der Site.
- HTML muss ohne JS lesbar bleiben, JS muss progressiv sein.
4. Verifizieren
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
Öffnet die Seite in Chrome headless, schreibt /tmp/site-shot.png und startet den Klick-Überlagerungstest. Den Screenshot ansehen (Werkzeug read_image), bevor man Schlussfolgerungen zieht.
Checkliste: Desktop- + Mobil-Darstellung, vollständige Daten (Elemente zählen), korrekte Links, keine Überlappungen.
5. Veröffentlichen
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site mein-repo-name
Das Skript: gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → Polling der URL bis 200 → Ausgabe der endgültigen URL.
Die Pages-Verzögerung beträgt 20 bis 90 s: nicht mit „funktioniert nicht“ schließen, bevor nicht auf 200 geschleift wurde. Auch prüfen: gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built.
6. Benutzerdefinierte Domain + Cloudflare
Nur wenn der Benutzer sie angefordert hat (siehe Schritt 1). DNS ist öffentlich: ein vages „Ja“ nicht in einen von der KI gewählten Domainnamen umdeuten.
Festgelegte Reihenfolge: DNS zuerst, dann Zertifikat, Enforce HTTPS zuletzt. Die Site muss bereits mit 200 auf *.github.io antworten, bevor begonnen wird.
a. DNS-Weiterleitung bei Cloudflare (MCP Cloudflare)
Voraussetzung Token: Bereiche zone.read + dns.write (Zone Read / DNS Edit). Fehlt es, anhalten und um Erweiterung bitten – nicht umgehen.
GET /zones?name=<Root-Domain>→zone.id. Bei null Zonen: die Domain ist nicht in diesem Account, nachfragen.GET /zones/{zone_id}/dns_records?name=<fqdn>→ wenn bereits ein identischer CNAME existiert, nichts neu erstellen (Idempotenz).POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<Subdomain>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= DNS only, nicht verhandelbar: der Cloudflare-Proxy verhindert, dass GitHub das Zertifikat ausstellt.- Ziel ist
<owner>.github.io, ohne abschließenden Slash und ohne Repository-Namen (jamesdadams.github.io, nicht.../mein-repo). ttl: 1= Auto.
- Mit öffentlicher Auflösung prüfen, nicht nur über die API:
dig +short <fqdn> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1 # → 185.199.108-111 .153
b. Domain + Enforce HTTPS auf GitHub Pages-Seite
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domain> ./site
Das Skript: schreibt die CNAME-Datei in die Site (sie überlebt Neubereitstellungen und verhindert Domain-Verlust) → PUT /repos/{owner}/{repo}/pages mit cname → wartet auf https_certificate.state = approved → aktiviert https_enforced: true.
⚠️ https_enforced: true gibt 400 zurück, solange das Zertifikat nicht existiert. Tatsächliche Verzögerung: 5 bis 20 Minuten nach CNAME-Erstellung. Deshalb schleift das Skript, statt fehlzuschlagen. „Enforce HTTPS“ nicht manuell vor der Ausstellung aktivieren und während dieses Fensters nicht auf Fehler schließen.
c. Endgültige Verifikation
curl -sI https://<domain>/ | head -5 # 200 + header server: GitHub.com
Dann die Seite im Browser erneut öffnen (Schritt 4) mit der benutzerdefinierten URL: ein 200 beweist nicht, dass die relativen Pfade (styles.css, script.js) aufgelöst werden – das ist die klassische Falle bei Project Pages, die im Root einer Domain ausgeliefert werden.
7. Aktualisierung ermöglichen
- Das Git-Verzeichnis im Projektverzeichnis des Benutzers ablegen (nicht in
/tmp, das beim Neustart gelöscht wird). - Im
README.mddokumentieren: woher die Daten stammen, wie die Extraktion erneut gestartet wird, was statisch ist (Daten) vs. dynamisch (in JS berechnete Regeln). - Dem Benutzer explizit mitteilen, was sich nicht automatisch aktualisiert.
Bereits aufgetretene Fallstricke
| Symptom | Ursache | Korrektur |
|---|---|---|
| 403 „Just a moment…“ | Cloudflare-Challenge | Grenze dokumentieren, offizielle API oder ausgehender Link; nicht versuchen zu umgehen |
| Seite abgeschnitten „Making sure you're not a bot“ | PoW Anubis | Challenge lösen (siehe Referenz) oder Benutzer um Export bitten |
| Selektor liefert 0 Ergebnisse für alle Elemente | falsches Muster (z.B. /games/lib/genre: vs /games/lib/popular/genre:) | HTML-Stichprobe ausgeben und Regex auf 1 Seite testen, bevor Schleife |
| Klick auf Karte öffnet nicht den richtigen Link | <a>-Schicht von positioniertem Kind überdeckt | pointer-events: none auf dekorative Elemente; mit elementFromPoint testen |
| GitHub Pages 404 in den ersten Minuten | Build läuft | Bis zu 90 s pollern |
| Daten einer Spalte leer | variierende Bezeichnung auf Quellseite („Released“ vs „Early Access“) | tolerantes Muster + Log pro Element, nie stilles except: pass |
https_enforced gibt 400 „certificate does not exist“ | Zertifikat noch nicht ausgestellt | Auf https_certificate.state = approved warten (5-20 Min.), das Skript schleift |
| Benutzerdefinierte Domain nach 30 Min. noch 404 | CNAME fehlt / falscher Besitzer / CNAME-Datei fehlt im Repo | dig zur CNAME-Bestätigung, set-pages-domain.sh erneut ausführen |
| HTTPS nach Proxy-Aktivierung defekt | Eintrag auf Proxied gesetzt | Zurück auf DNS only (proxied: false), GitHub-Zertifikat kann nicht durch Proxy validiert werden |
| „Domain is already in use“ | Domain bereits auf einem anderen Repo des Accounts deklariert | eine benutzerdefinierte Domain pro Repo; alte freigeben, bevor neu zugewiesen wird |
CSS/JS auf benutzerdefinierter Domain 404, aber OK auf *.github.io/repo/ | absolute Pfade (/styles.css) auf einer Project Page im Root | relative Pfade (styles.css) |
Referenzen
reference/data-and-ethics.md– Extraktion, PoW Anubis, Cloudflare, Lizenzen, Image-Hotlinkingreference/design-and-verify.md– minimales Designsystem, Browser-Tests, Barrierefreiheitreference/publish-gh-pages.md–gh-Befehle, Namensgebung, Domains, Fehlerbehebungscripts/publish-gh-pages.sh– Veröffentlichung + Pages-Aktivierungscripts/set-pages-domain.sh– Benutzerdefinierte Domain + Enforce HTTPS (nach Cloudflare-CNAME)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}