Integrare Zola con GitHub Pages

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:

1. 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.

2. 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.

3. 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

1. Creiamo un nuovo repository su GitHub
   Accediamo al nostro account GitHub e creiamo un nuovo repository. Possiamo scegliere un nome come nome-del-progetto o qualsiasi altro ci sembri appropriato.

2. 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 e nome-del-progetto con il nome del repository.

3. Creiamo un branch principale
   Creiamo un branch principale main (se non esiste già):

   git checkout -b main

4. Configuriamo il file.gitignore
   Zola genera una directory public/ 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

1. Creiamo un branch gh-pages
   GitHub Pages pubblica i siti dal branch gh-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.

2. 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 branch gh-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.