← Notizen

Astro auf GitHub Pages – mit und ohne eigene Domain

Ohne eigene Domain liegt die Seite in einem Unterpfad. Mit actions/configure-pages übernimmt Astro den richtigen Basispfad automatisch.

Ein Projekt-Repo auf GitHub Pages landet zunächst unter <user>.github.io/<repo>/. Baut Astro die Seite für /, zeigen CSS, Favicon und alle internen Links ins Leere. Sobald eine eigene Domain eingerichtet ist, liegt die Seite wieder unter / – der Basispfad ändert sich also im Laufe des Projekts.

Den Pfad aus configure-pages übernehmen

Die Action actions/configure-pages kennt die aktuelle Adresse und gibt sie als Outputs origin und base_path heraus. Die reiche ich als Umgebungsvariablen an den Build weiter:

- name: Configure Pages
  id: pages
  uses: actions/configure-pages@v6

- name: Set site URL and base path
  run: |
    echo "SITE_URL=${{ steps.pages.outputs.origin }}" >> "$GITHUB_ENV"
    echo "BASE_PATH=${{ steps.pages.outputs.base_path }}" >> "$GITHUB_ENV"

- name: Build
  uses: withastro/action@v6

withastro/action ist eine Composite Action – Variablen aus $GITHUB_ENV kommen dort zuverlässig an.

In astro.config.mjs:

export default defineConfig({
  site: process.env.SITE_URL || 'https://christianurban.de',
  base: process.env.BASE_PATH || '/',
});

Lokal greifen die Standardwerte, in CI der echte Pfad. Mit eigener Domain ist base_path leer – es muss nichts umgestellt werden.

Assets wie CSS versieht Astro selbst mit dem Basispfad, eigene Links aber nicht. Dafür reicht ein kleiner Helfer:

const base = import.meta.env.BASE_URL.replace(/\/$/, '');
export const url = (path: string) => `${base}${path}`;

Und dann überall href={url('/notizen/')} statt href="/notizen/".

Stolperfalle beim lokalen Test unter Windows

Wer unter Git Bash BASE_PATH=/christianurban.de npm run build ausprobiert, bekommt Links wie /C:/Program Files/Git/christianurban.de/. Git Bash wandelt Werte, die wie Unix-Pfade aussehen, in Windows-Pfade um. Abhilfe: MSYS_NO_PATHCONV=1 voranstellen. In GitHub Actions tritt das Problem nicht auf.