Persönliche Seite auf GitHub Pages
Ziel: Eine schnelle, barrierefreie persönliche Seite unter https://<account>.github.io/, erstellt aus einer vom Nutzer editierbaren Inhaltsdatei, veröffentlicht von GitHub Actions bei jedem Push auf main. Kein Framework und keine npm-Abhängigkeiten, daher überall baubar.
Funktioniert für jeden, in jedem Bereich. Schreiben Sie die Seite in der Sprache des Nutzers.
Harte Regeln
- Das Repository muss exakt
<account>.github.ioheißen, wobei<account>der GitHub-Benutzername (oder die Organisation) ist, der es gehört, in Kleinbuchstaben. Nur dieser Name veröffentlicht unter der Wurzel (https://<account>.github.io/). Jeder andere Name veröffentlicht unter einem Unterpfad (https://<account>.github.io/<repo>/), und ein Tippfehler oder ein anderer Besitzer bedeutet, dass die Root-URL einen 404 zurückgibt. Jedes Konto hat genau eine solche Seite. - Erfinden Sie niemals Inhalte. Keine erfundenen Arbeitgeber, Daten, Titel, Kennzahlen, Projekte oder Links. Fehlende Fakten werden zu einem sichtbaren Platzhalter wie
[Jahr des Beginns]und einer Frage an den Nutzer. - Persönliche Daten sind nach dem Push öffentlich, auch in der Git-Historie. Fragen Sie vor der Veröffentlichung einer Telefonnummer, Privatanschrift, privaten E-Mail oder eines Geburtsdatums; bevorzugen Sie Stadt/Region, einen Kontaktlink und LinkedIn. Committen Sie niemals Geheimnisse oder
.env-Dateien. - Führen Sie Befehle, die Dinge auf GitHub erstellen oder ändern (Repository erstellen, Pages aktivieren, pushen) erst aus, nachdem Sie dem Nutzer beim ersten Mal gezeigt haben, was sie tun werden. Alles andere kann sofort gemacht werden.
Voraussetzungen
Die GitHub CLI, installiert und angemeldet. Zuerst prüfen und beheben, was fehlschlägt:
gh --version # installieren: https://cli.github.com
gh auth status # angemeldet? Welches Konto? Welche Scopes?
gh auth login -h github.com -p https -w # falls nicht angemeldet (Browser-Flow)
gh auth refresh -h github.com -s workflow # Pushen von .github/workflows/* erfordert den workflow-Scope
gh api user --jq .login # Der Kontoname: Das Repository ist <dies>.github.io
git --version
node --version # 18+; nur zur lokalen Ausführung des Builds nötig
Wenn die Seite zu einer Organisation gehört, ist <account> der Organisationsname und der Nutzer benötigt die Berechtigung, darin Repositories zu erstellen (gh repo create <org>/<org>.github.io).
Schritt 1: Ausgangspunkt prüfen
ACCOUNT=$(gh api user --jq .login | tr '[:upper:]' '[:lower:]')
REPO="$ACCOUNT.github.io"
gh repo view "$ACCOUNT/$REPO" --json name,visibility,url 2>/dev/null || echo "Repository existiert noch nicht"
gh api "repos/$ACCOUNT/$REPO/pages" 2>/dev/null || echo "Pages nicht aktiviert"
- Repository existiert mit einer Seite darin: Fragen, ob es ersetzt, behalten oder dessen Inhalt migriert werden soll. Niemals ohne ein ja überschreiben.
- Repository existiert unter einem anderen Namen (z. B.
portfolio,MyName.github.iounter einem anderen Konto): Angebot, es umzubenennen (gh repo rename <account>.github.io -R <owner>/<old>) anstatt ein zweites zu erstellen. - Im kostenlosen Plan muss das Repository für Pages öffentlich sein.
Schritt 2: Inhalt sammeln (nur fragen, was fehlt, in einer Nachricht)
- Name, Rolle oder Überschrift, Stadt/Region (optional) und die Sprache der Seite.
- Zwei oder drei Sätze darüber, was sie tun und für wen, dann ein längerer "Über mich"-Text, falls gewünscht.
- Erfahrung oder Projekte: Titel, Organisation, Zeitraum, jeweils ein oder zwei Zeilen. Ein Lebenslauf, LinkedIn-Export oder eine bestehende Seite ist die schnellste Quelle.
- Links: GitHub (automatisch ausgefüllt), LinkedIn, E-Mail oder Kontaktformular, andere Profile.
- Look & Feel in ein paar Wörtern und was vermieden werden soll. Ohne Präferenz die nüchterne Standardvorlage in
assets/style.cssverwenden.
Die Antworten in content/profile.json ablegen (Struktur in assets/profile.example.json). Dem Nutzer das JSON vor dem Bauen zeigen und jeden Platzhalter markieren.
Schritt 3: Projekt erstellen
Empfohlene Struktur (das gleiche Layout funktioniert für jeden Static Generator):
<account>.github.io/
AGENTS.md Anleitungen für jeden Codier-Agenten (Vorlage: assets/AGENTS.md)
CLAUDE.md -> AGENTS.md optionaler Symlink, damit Claude Code die gleiche Datei liest
README.md Wie bearbeiten, bauen und veröffentlichen
content/profile.json Der gesamte Text auf der Seite
build.mjs Generator, nur Node, keine Abhängigkeiten (assets/build.mjs)
static/style.css Tokens auf :root, Dark Mode via prefers-color-scheme
.github/workflows/deploy.yml Build + Deployment zu Pages (assets/deploy.yml)
.gitignore dist/ und node_modules/
Die Dateien aus dem assets/-Ordner dieses Skills kopieren, dann anpassen. scripts/ enthält das Repository-Setup aus Schritt 4. AGENTS.md agentenneutral halten: Es beschreibt das Projekt, die Befehle und die Designregeln, nicht ein bestimmtes Tool.
mkdir "$REPO" && cd "$REPO" && git init -b main
mkdir -p content static .github/workflows
# assets/ kopieren: build.mjs, style.css -> static/, deploy.yml -> .github/workflows/,
# AGENTS.md, profile.example.json -> content/profile.json
ln -s AGENTS.md CLAUDE.md # optional
printf 'dist/\nnode_modules/\n' > .gitignore
node build.mjs && python3 -m http.server 4321 -d dist # Vorschau unter http://localhost:4321
Optionale Extras, nur wenn der Nutzer fragt: eine Projektseite, ein Blog (Markdown-Dateien, die zur Build-Zeit gerendert werden), eine benutzerdefinierte Domain oder ein Plugin-/Skill-Marktplatz im selben Repository (.claude-plugin/marketplace.json + plugins/<plugin>/, wobei die Seite diese auflistet; mit claude plugin validate . validieren, wenn Claude Code installiert ist).
Schritt 4: Repository erstellen und Pages aktivieren
Das Repository immer mit gh erstellen, niemals durch Eingabe des Namens in der Weboberfläche: scripts/create-site-repo.sh übernimmt den Namen vom angemeldeten Konto, sodass er immer exakt <account>.github.io ist. Aus dem Seitenordner ausführen, zuerst mit --dry-run und dem Nutzer die Ausgabe zeigen:
bash <skill-verzeichnis>/scripts/create-site-repo.sh --dry-run # Prüft gh, Login, Scopes; gibt aus, was es tun wird
bash <skill-verzeichnis>/scripts/create-site-repo.sh # Erstellt das öffentliche Repository, aktiviert Pages (Actions), setzt origin
# Organisationsseite: ... --org <org>
# Repository existiert bereits: ... --existing (nur nach Rücksprache mit dem Nutzer, was darin ist)
Es stoppt, wenn gh fehlt oder nicht angemeldet ist, warnt, wenn dem Token der workflow-Scope fehlt, und weigert sich, ein bestehendes Repository ohne --existing anzufassen. Dieselben Schritte von Hand:
gh repo create "$ACCOUNT/$REPO" --public --description "Persönliche Seite"
gh api -X POST "repos/$ACCOUNT/$REPO/pages" -f build_type=workflow # PUT, wenn Pages bereits existiert
git remote add origin "https://github.com/$ACCOUNT/$REPO.git"
gh api "repos/$ACCOUNT/$REPO/pages" --jq '{url: .html_url, source: .build_type}'
Die Pages-Einstellung befindet sich auch in der Weboberfläche unter Einstellungen → Pages → Build and deployment → Source: GitHub Actions.
Schritt 5: Deployment
git add -A && git commit -m "Persönliche Seite"
git push -u origin main
gh run watch "$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status
curl -sI "https://$REPO/" | head -1 # Erwarten Sie HTTP/2 200; das erste Deployment kann ein oder zwei Minuten dauern
Ab dann baut jeder Push auf main die Seite neu und veröffentlicht sie. gh workflow run deploy.yml führt ein erneutes Deployment ohne Commit durch.
Schritt 6: Vor Abschluss prüfen
- Die Live-URL öffnen, nicht nur die lokale Vorschau. Links funktionieren, kein 404 bei CSS oder Seiten.
- Screenshots bei 1280px und 390px Breite im hellen und dunklen Modus machen. Kein horizontaler Scroll bei 390px.
- Tastatur: Tab erreicht jeden Link mit einem sichtbaren Fokusring. Textkontrast erfüllt WCAG AA in beiden Designs.
<title>, Meta-Beschreibung undlangsind gesetzt; Bilder habenalt.- Kein Platzhalter wie
[Jahr]auf der veröffentlichten Seite übrig, es sei denn, der Nutzer hat entschieden, ihn vorerst zu behalten (dann auflisten).
Fehlerbehebung
| Symptom | Ursache und Behebung |
|---|---|
https://<account>.github.io/ ist 404, Seite erscheint unter /<repo>/ | Der Repository-Name ist nicht exakt <account>.github.io für das besitzende Konto. Umbenennen: gh repo rename <account>.github.io. |
| 404 überall nach einem grünen Durchlauf | Pages-Quelle immer noch "Deploy from a branch", oder privates Repository im kostenlosen Plan. Den build_type=workflow-Aufruf erneut ausführen; das Repository öffentlich machen (gh repo edit --visibility public --accept-visibility-change-consequences). |
| Push abgelehnt: "refusing to allow an OAuth App to create or update workflow" | Dem Token fehlt der workflow-Scope: gh auth refresh -s workflow. |
| Deploy-Job: "Branch is not allowed to deploy to github-pages" | Die github-pages-Umgebung erlaubt nur den Standard-Branch. Von main aus deployen oder den Branch unter Einstellungen → Umgebungen hinzufügen. |
gh api .../pages gibt 409 oder 422 zurück | Pages existiert bereits: -X PUT anstelle von -X POST verwenden. |
| CSS fehlt nur auf der Live-Seite | Absolute Pfade gehen von der Wurzel aus. Für eine Projektseite (/<repo>/) Pfade mit der Basis versehen; assets/build.mjs erledigt dies von GITHUB_REPOSITORY. |
| Alte Version wird noch angezeigt | CDN-Cache, bis zu ~10 Minuten. Prüfen, ob der Durchlauf abgeschlossen ist, und hartes Neuladen durchführen. |
Benutzerdefinierte Domain (optional)
gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -f cname=www.example.com
# DNS: CNAME www -> <account>.github.io ; Apex: A-Einträge zu GitHub Pages-IPs (siehe GitHub-Dokumentation)
gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -F https_enforced=true # sobald das Zertifikat ausgestellt ist
Ausgabe
Enden mit: der Live-URL, der Repository-URL, welche Datei für welche Art von Änderung zu bearbeiten ist (content/profile.json für Text, static/style.css für das Aussehen), der Liste der noch offenen Platzhalter und dem einen Befehl zur lokalen Vorschau.