CommunityCodierung & Entwicklunggithub.com

static-site-publish

Fähigkeit, eine kleine statische Website aus reinem HTML/CSS/JS (ohne Build-Tool oder Framework) aus Daten zu generieren, in einem Headless-Browser zu prüfen und dann mit GitHub Pages zu veröffentlichen.

Was ist static-site-publish?

Diese Fähigkeit automatisiert den gesamten Workflow von Rohdaten bis zu einer live geschalteten, statischen Website, die über GitHub Pages gehostet wird. Sie ist ideal für Einzelseiten, Galerien, Dashboards oder Portfolios mit bis zu einigen hundert Elementen, ohne Laufzeitabhängigkeiten. Der Prozess umfasst: Datenextraktion in eine `data.json`-Datei, Generierung einer HTML/CSS/JS-Seite aus Vorlagen, Verifikation in einem Headless-Browser (Screenshot + Klick-Tests), Veröffentlichung auf GitHub Pages und optionale Einrichtung einer benutzerdefinierten Domain über Cloudflare (CNAME, Proxy deaktiviert) mit erzwungenem HTTPS. Die Fähigkeit setzt strikte ethische Regeln durch: kein Kopieren von Designs Dritter, Respektieren von Zugriffsschutzmaßnahmen (robots.txt, Cloudflare-Challenges), und sie erfordert explizite Benutzerbestätigung für Repository-Namen und benutzerdefinierte Domains. Enthaltene Skripte behandeln Fallstricke wie Pages-Build-Verzögerungen (20–90 Sekunden), Zertifikatsausstellung (5–20 Minuten) und relative Pfade bei benutzerdefinierten Domains. Der generierte Code bleibt lesbar und progressiv: HTML funktioniert ohne JavaScript, JS fügt Such-/Sortierfunktionen und berechnete Anzeigeregeln hinzu, sodass kein täglicher Rebuild nötig ist.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

JaNein
„Mach mir eine Seite mit dieser Liste / dieser Tabelle“, Galerie, Daten-DashboardApp 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

  1. Eigenes Design. Niemals das CSS, HTML oder die Assets einer Drittanbieter-Seite kopieren. Von der Informationsstruktur inspiriert sein ist OK; das Erscheinungsbild übernehmen nicht.
  2. 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).
  3. 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.
  4. Immer in einem echten Browser prüfen, bevor man „fertig“ sagt (Screenshot + Klick-Test).
  5. Nicht ohne Bestätigung des Repository-Namens / Accounts veröffentlichen, falls mehrdeutig.
  6. 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, Raster auto-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.

  1. GET /zones?name=<Root-Domain> → zone.id. Bei null Zonen: die Domain ist nicht in diesem Account, nachfragen.
  2. GET /zones/{zone_id}/dns_records?name=<fqdn> → wenn bereits ein identischer CNAME existiert, nichts neu erstellen (Idempotenz).
  3. 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.
  1. 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.md dokumentieren: 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

SymptomUrsacheKorrektur
403 „Just a moment…“Cloudflare-ChallengeGrenze dokumentieren, offizielle API oder ausgehender Link; nicht versuchen zu umgehen
Seite abgeschnitten „Making sure you're not a bot“PoW AnubisChallenge lösen (siehe Referenz) oder Benutzer um Export bitten
Selektor liefert 0 Ergebnisse für alle Elementefalsches 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 überdecktpointer-events: none auf dekorative Elemente; mit elementFromPoint testen
GitHub Pages 404 in den ersten MinutenBuild läuftBis zu 90 s pollern
Daten einer Spalte leervariierende 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 ausgestelltAuf https_certificate.state = approved warten (5-20 Min.), das Skript schleift
Benutzerdefinierte Domain nach 30 Min. noch 404CNAME fehlt / falscher Besitzer / CNAME-Datei fehlt im Repodig zur CNAME-Bestätigung, set-pages-domain.sh erneut ausführen
HTTPS nach Proxy-Aktivierung defektEintrag auf Proxied gesetztZurü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 deklarierteine 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 Rootrelative Pfade (styles.css)

Referenzen

  • reference/data-and-ethics.md – Extraktion, PoW Anubis, Cloudflare, Lizenzen, Image-Hotlinking
  • reference/design-and-verify.md – minimales Designsystem, Browser-Tests, Barrierefreiheit
  • reference/publish-gh-pages.md – gh-Befehle, Namensgebung, Domains, Fehlerbehebung
  • scripts/publish-gh-pages.sh – Veröffentlichung + Pages-Aktivierung
  • scripts/set-pages-domain.sh – Benutzerdefinierte Domain + Enforce HTTPS (nach Cloudflare-CNAME)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

Verwandte Skills