Communitygithub.com

tangshengming/personal_website

Bereits generierte statische persönliche Website auf GitHub Pages bereitstellen. Verwende dies, wenn der Nutzer die Website deployen, die generierte Astro-Seite veröffentlichen, GitHub Pages einrichten, den GitHub Actions Deployment-Workflow erklären oder aktualisieren oder nach dem Push zu GitHub die Funktionsfähigkeit der deployed Website überprüfen möchte.

Was ist personal_website?

Diese Fähigkeit automatisiert die Bereitstellung einer statischen, bereits generierten persönlichen Website (z. B. mit Astro erstellt) auf GitHub Pages mittels eines GitHub Actions-Workflows. Sie ist ideal für Entwickler, die eine persönliche Seite hosten möchten, ohne die Website selbst neu zu gestalten – der Fokus liegt ausschließlich auf dem Deployment-Prozess. Die Fähigkeit unterstützt ausschließlich Astro-basierte Projekte, die in einem GitHub-Repository liegen; Quellcode wird versioniert, und das Deployment erfolgt automatisch bei jedem Push in den Haupt-Branch. Der bereitgestellte Workflow baut die Website mit `npm.cmd run build`, bereitet ein Pages-Artefakt vor und veröffentlicht es – mit korrekter Base-Path-Handling für Projekt-Seiten-URLs. Vor dem Deployment prüft die Fähigkeit auf notwendige Dateien (package.json, astro.config.mjs, .gitignore, deploy.yml) und führt Tests mit `git status` und `npm.cmd run build` durch. Nach dem Deployment überprüft sie die Funktionsfähigkeit der Seite und behebt typische Probleme wie fehlerhafte Pfade oder fehlgeschlagene GitHub Actions-Schritte. Die Fähigkeit läuft auf jeder Plattform (Windows, macOS, Linux) und ist in PowerShell-Befehlen verfasst, die aber auch unter Bash funktionieren.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangshengming/personal_website/tree/HEAD/.codex/skills/deploy-website

In Ihrer bevorzugten KI fragen

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

Dokumentation

Website bereitstellen

Überblick

Nutze diese Fähigkeit, um die Bereitstellung einer bereits generierten Website auf GitHub Pages zu steuern. Das erwartete Projekt ist eine statische Astro-Website, die in einem GitHub-Repository gespeichert ist, wobei die Quelldateien versioniert und das Deployment von GitHub Actions übernommen wird.

Diese Fähigkeit setzt voraus, dass die Website selbst bereits existiert. Gestalte die Website nicht neu, es sei denn, der Nutzer bittet darum.

Bereitstellungsmodell

Verwende dieses Setup für den aktuellen Workflow der persönlichen Website:

  • Quellcode mit Git verfolgen.
  • Generierte Ordner oder Abhängigkeiten wie node_modules/, dist/, .astro/ und tmp/ ignorieren.
  • Die Website mit npm.cmd run build erstellen.
  • Von GitHub Actions zu GitHub Pages bereitstellen.
  • Lokale Entwicklung unter http://localhost:4321/ durchführen.
  • Nur bei GitHub Actions-Builds einen Astro-base-Pfad für Projekt-Seiten-URLs wie https://BENUTZERNAME.github.io/REPOSITORY/ verwenden.

Vor der Bereitstellung

Überprüfe die Bereitschaft mit einfachen Befehlen:

git status
npm.cmd run build

Stelle sicher, dass folgende Dateien oder Einstellungen vorhanden sind:

  • package.json
  • astro.config.mjs
  • .gitignore
  • .github/workflows/deploy.yml
  • src/
  • public/

Für dieses Projekt sollte astro.config.mjs sowohl lokale als auch GitHub Pages-Builds unterstützen, zum Beispiel:

import { defineConfig } from "astro/config";

const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";

export default defineConfig({
  site: "https://BENUTZERNAME.github.io",
  base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});

Verwende in Astro-Seiten/Layouts URL-Helper, wenn du auf lokale öffentliche Assets oder interne Seiten verlinkst:

const base = import.meta.env.BASE_URL;
const url = (path: string) => {
  const normalizedBase = base.endsWith("/") ? base : `${base}/`;
  const normalizedPath = path.replace(/^\/+/g, "");

  return `${normalizedBase}${normalizedPath}`;
};

GitHub Actions-Workflow

Verwende einen Pages-Workflow wie diesen:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Build with Astro
        uses: withastro/action@v6

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Erkläre die Aktionen bei Bedarf einfach:

  • actions/checkout@v7: lädt das Repository in den GitHub Actions-Runner herunter.
  • withastro/action@v6: installiert Abhängigkeiten, erstellt die Astro-Website und bereitet das Pages-Artefakt vor.
  • actions/deploy-pages@v5: veröffentlicht das erstellte Artefakt auf GitHub Pages.

Das @vN-Suffix fixiert eine Hauptversion der Aktion.

Repository- und Commit-Schritte

Führe den Nutzer durch das Committen und Pushen der deploymentbereiten Quellcode-Änderungen:

git status
git add .
git commit -m "Website-Bereitstellung vorbereiten"
git push origin main

Wenn Git Zeilenendungs-Warnungen wie LF wird durch CRLF ersetzt meldet, erkläre, dass dies eine normale Windows-Zeilenendungs-Normalisierungswarnung ist und in der Regel kein Hindernis für das Deployment darstellt.

Wenn Git keine konfigurierte Benutzeridentität meldet, konfiguriere die Repository- oder globale Identität, bevor du commitest. Falls Privatsphäre wichtig ist, verwende die GitHub-Noreply-E-Mail des Nutzers.

GitHub Pages-Einstellungen

Führe den Nutzer auf GitHub:

  1. Öffne das Repository auf GitHub.
  2. Gehe zu Settings.
  3. Gehe zu Pages.
  4. Setze unter Build and deployment die Source auf GitHub Actions.
  5. Speichere, falls GitHub einen Speichern-Button anzeigt.
  6. Gehe zum Tab Actions und öffne den neuesten Deployment-Lauf.
  7. Warte, bis der Workflow erfolgreich abgeschlossen ist.
  8. Öffne die von GitHub angezeigte Pages-URL.

Für eine Projekt-Website ist die erwartete URL normalerweise:

https://BENUTZERNAME.github.io/REPOSITORY/

Überprüfung

Überprüfe nach dem Deployment:

  • Die Startseite lädt.
  • Navigationslinks funktionieren.
  • Bilder laden.
  • Herunterladbare Dateien, wie die CV-PDF, öffnen korrekt.
  • Die Browser-URL enthält den Repository-Pfad für Projekt-Seiten.
  • Es erscheinen keine defekten Pfade wie /REPOSITORYprojekte, /REPOSITORYprofil.jpg oder /REPOSITORYdatei.pdf im generierten HTML.

Wenn die deployed Website defekt ist, die lokale Vorschau aber funktioniert, überprüfe zuerst die Base-Path-Behandlung.

Wenn GitHub Actions fehlschlägt, untersuche den fehlgeschlagenen Schritt:

  • Checkout-Fehler: Repository- oder Berechtigungsproblem.
  • Installations-/Build-Fehler: Abhängigkeits-, Astro- oder Quellcode-Problem.
  • Deployment-Fehler: GitHub Pages-Quell-/Berechtigungs-/Einstellungsproblem.

Abschlusskriterien

Betrachte die Deployment-Aufgabe als abgeschlossen, wenn:

  • Der lokale Build erfolgreich ist.
  • Quellcode-Änderungen committed und gepusht wurden.
  • Die GitHub Pages-Quelle auf GitHub Actions gesetzt ist.
  • Der Actions-Deployment-Lauf erfolgreich ist.
  • Die öffentliche Pages-URL die Website korrekt lädt.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Verwandte Skills