In questa lezione spiegheremo passo dopo passo come integrare un sito statico creato con Zola con GitHub Pages. Questa configurazione ci permetterà di pubblicare facilmente il nostro sito e mantenerlo aggiornato automaticamente grazie all'uso di GitHub Actions. Seguiremo una procedura pratica e diretta per configurare il progetto, il repository GitHub e il workflow di automazione.
Configurazione del Progetto Zola
Come abbiamo già visto nelle lezioni precedenti, per poter creare un progetto Zola sono necessari pochi passaggi. Di seguito un riassunto su come fare:
-
Creiamo il progetto con Zola
Se non lo abbiamo ancora fatto, iniziamo creando un nuovo progetto con Zola:zola init nome-del-progetto cd nome-del-progetto
Durante l'inizializzazione Zola ci chiederà alcune informazioni (come il nome del sito). Rispondiamo alle domande o lasciamo i valori predefiniti.
-
Verifichiamo che il sito funzioni
Lanciamo il server di sviluppo per controllare che il sito sia operativo:zola serve
Apriamo il browser all'indirizzo
http://127.0.0.1:1111
e assicuriamoci che tutto funzioni correttamente. Se necessario, modifichiamo i file di configurazione o aggiungiamo dei contenuti. -
Generiamo i file statici
Zola genera i file statici necessari per il nostro sito. Usiamo il comando:zola build
Questo comando creerà una cartella
public/
contenente tutti i file da pubblicare.
Configurazione del repository GitHub
-
Creiamo un nuovo repository su GitHub
Accediamo al nostro account GitHub e creiamo un nuovo repository. Possiamo scegliere un nome comenome-del-progetto
o qualsiasi altro ci sembri appropriato. -
Inizializziamo Git nel progetto Zola
Nel nostro terminale, dentro la directory del progetto, inizializziamo Git e colleghiamolo al repository remoto:git init git remote add origin https://github.com/username/nome-del-progetto.git
Sostituiamo
username
con il nostro nome utente GitHub enome-del-progetto
con il nome del repository. -
Creiamo un branch principale
Creiamo un branch principalemain
(se non esiste già):git checkout -b main
-
Configuriamo il file
.gitignore
Zola genera una directorypublic/
ogni volta che costruiamo il progetto. Vogliamo evitare di tracciare i file in questa directory manualmente. Creiamo o modifichiamo un file.gitignore
nella root del progetto e aggiungiamo la seguente linea:public/
Salviamo il file.
Configurazione GitHub Pages per l'integrazione con Zola
-
Creiamo un branch
gh-pages
GitHub Pages pubblica i siti dal branchgh-pages
. Creiamo questo branch separato per ospitare i file generati da Zola utilizzando l'opzione--orphan
. Questo comando crea un nuovo branch senza cronologia precedente:git checkout --orphan gh-pages
Un branch orfano non ha commit precedenti, il che è ideale per mantenere il branch
gh-pages
completamente separato dal nostro branch principale. In questo modo, possiamo dedicare il branch esclusivamente ai file pubblicati senza interferire con lo sviluppo.Una volta creato il branch, rimuoviamo tutti i file esistenti per garantire che sia completamente vuoto:
git rm -rf .
Questo comando elimina ogni file e directory nel branch orfano. Successivamente, creiamo un file
README.md
temporaneo per poter effettuare il primo commit:echo "Branch per GitHub Pages" > README.md git add README.md git commit -m "Inizializzazione del branch gh-pages"
Infine, pushiamo il branch
gh-pages
nel repository remoto:git push origin gh-pages
Torniamo al branch
main
per continuare il lavoro sul progetto principale:git checkout main
Questo approccio ci consente di mantenere una chiara separazione tra il codice sorgente e i file pubblicati, riducendo i rischi di confusione o errori.
-
Configuriamo GitHub Pages nel repository
Andiamo alla pagina delle impostazioni del repository su GitHub (Settings
) e scorriamo fino alla sezione "Pages". Configuriamo GitHub Pages per pubblicare dal branchgh-pages
:-
Selezioniamo
gh-pages
nel menu a tendina. -
Confermiamo le modifiche.
A questo punto, GitHub è configurato per pubblicare i file presenti nel branch
gh-pages
. -
Automazione con GitHub Actions
Per automatizzare la generazione e la pubblicazione del sito possiamo utilizzare GitHub Actions. GitHub Actions è uno strumento di automazione potente fornito da GitHub che consente l'integrazione continua (CI) e la consegna continua (CD) per i progetti software. Permette di automatizzare flussi di lavoro per vari compiti come la compilazione, i test, la distribuzione e altro, direttamente all'interno dei repository GitHub.
Questo strumento, però, può essere adoperato per uno scopo "diverso", ovvero per la gestione del nostro sito web sviluppato in Zola. Creiamo quindi una directory .github/workflows/
nella root del progetto, se non esiste già, e all’interno creiamo un file deploy.yml
:
name: Deploy Zola site
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Install Zola
run: |
curl -sSf https://sh.rustup.rs | sh -s -- -y
export PATH="$HOME/.cargo/bin:$PATH"
cargo install zola
- name: Build site
run: |
zola build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
Questo workflow si attiverà ogni volta che eseguiamo un push sul branch main
e pubblicherà automaticamente i file generati nel branch gh-pages
.
Committiamo il workflow
Salviamo il file deploy.yml
, quindi aggiungiamo, committiamo e pushiamo le modifiche:
git add .github/workflows/deploy.yml
git commit -m "Aggiunto workflow per il deploy"
git push origin main
Facciamo adesso una modifica al sito (ad esempio, aggiungendo una nuova pagina o cambiando il file di configurazione) e pushiamo le modifiche sul branch main
. GitHub Actions dovrebbe avviare automaticamente il workflow e pubblicare i file aggiornati su GitHub Pages. Possiamo monitorare lo stato del workflow nella scheda Actions del repository su GitHub.
Verifica del sito pubblicato
Controlliamo l'URL del sito
GitHub Pages pubblicherà il nostro sito all'indirizzo:
https://username.github.io/nome-del-progetto/
Sostituiamo username
e nome-del-progetto
con il nostro nome utente GitHub e il nome del repository.
Correggiamo eventuali problemi di URL
Se notiamo che i collegamenti interni del sito non funzionano, potrebbe essere necessario configurare il campo base_url
nel file config.toml
del progetto Zola:
base_url = "https://username.github.io/nome-del-progetto/"
Dopo aver aggiornato il file, ricostruiamo e pushiamo le modifiche.
zola build
git add config.toml
git commit -m "Aggiunto base_url"
git push origin main
Questo assicurerà che i collegamenti interni puntino correttamente al sito pubblicato.
Conclusioni
Seguendo questi passaggi abbiamo integrato con successo Zola con GitHub Pages, semplificando il flusso di lavoro per la gestione del nostro sito statico. Ogni volta che apportiamo modifiche al sito GitHub Actions si occupa di generare i file statici e di pubblicarli automaticamente su GitHub Pages. In pratica, ogni volta che eseguiamo un push del codice, la pipeline automatica si attiva, eseguendo tutti i passaggi necessari per costruire e distribuire il sito senza bisogno di intervento manuale.
In questo modo possiamo concentrarci sui contenuti e sull'aggiornamento delle pagine, senza preoccuparci della gestione del deploy. L'automazione tramite GitHub Actions ci garantisce che ogni modifica venga processata in modo consistente e senza errori, riducendo al minimo il rischio di problemi in fase di pubblicazione.
Inoltre, poiché tutte le operazioni sono tracciate direttamente all'interno di GitHub, possiamo facilmente monitorare il processo, analizzare i log e, se necessario, eseguire il debug in modo rapido ed efficace.