Distribuire Astro Narrow su GitHub Pages

Astro Narrow include .github/workflows/deploy.yml, che compila il sito d’esempio a ogni push su main e supporta anche esecuzioni manuali. Il workflow gestisce sia i siti utente sia i repository di progetto, dove i base URL differiscono.

Abilita GitHub Actions come sorgente di Pages#

Prima del primo deployment, apri le impostazioni del repository e scegli Pages → Build and deployment → GitHub Actions. Il workflow necessita dei permessi già presenti pages: write e id-token: write per pubblicare l’artefatto generato.

Capisci ASTRO_SITE e ASTRO_BASE#

Per un sito utente chiamato <owner>.github.io, la base pubblica è /. Per un repository di progetto, la base è /<nome-repository>/. Il workflow incluso calcola automaticamente entrambi i valori:

ASTRO_SITE=https://<owner>.github.io
ASTRO_BASE=/<nome-repository>

ASTRO_SITE fornisce l’origine assoluta usata dall’output di sitemap e RSS. ASTRO_BASE mantiene link interni e asset compilati dentro il percorso del progetto.

Warning

Un link scritto a mano come href="/archives/" salta la base del progetto. Il codice del tema dovrebbe generare i percorsi interni con getLocalePath() o un altro helper di lingua già esistente.

Riproduci la build di deployment in locale#

Esegui la stessa build sensibile ai percorsi prima di fare push:

ASTRO_SITE=https://example.github.io ASTRO_BASE=/astro-narrow/ pnpm build

Dopo che ha successo, ispeziona dist/sitemap.xml e una pagina di contenuto generata. Gli URL dovrebbero includere /astro-narrow/, mentre le rotte italiane restano senza prefisso e le rotte inglesi includono /en/.

Diagnostica i fallimenti più comuni#

• Un errore Not Found su Pages spesso significa che GitHub Actions non è stato selezionato come sorgente di Pages.
• Stili mancanti sulle pagine di progetto di solito indicano un ASTRO_BASE errato o mancante.
• Origini errate nella sitemap puntano ad ASTRO_SITE, non alla logica di routing.
• Una pagina che funziona in locale ma fallisce solo sotto un percorso di repository di solito contiene un URL root-relative scritto a mano.

Considera la build con base path parte della verifica di deployment ogni volta che cambiano navigazione, asset, RSS, sitemap o link localizzati.