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

   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

   zola serve

   Apriamo il browser all'indirizzo http://127.0.0.1:1111

3. Generiamo i file statici

   zola build

   Questo comando creerà una cartella public/

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

2. Inizializziamo Git nel progetto Zola
   Nel nostro terminale, dentro la directory del progetto, inizializziamo Git

   git init
   git remote add origin https://github.com/username/nome-del-progetto.git

   Sostituiamo username nome-del-progetto

3. Creiamo un branch principale
   Creiamo un branch principale main

   git checkout -b main

4. Configuriamo il file .gitignore
   Zola genera una directory public/ .gitignore

   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 --orphan

   git checkout --orphan gh-pages

   Un branch orfano non ha commit precedenti, il che è ideale per mantenere il branch gh-pages

   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

   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

   git push origin gh-pages

   Torniamo al branch main

   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 gh-pages

   • Selezioniamo gh-pages

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

Se vuoi aggiornamenti su su questo argomento inserisci la tua email nel box qui sotto:

Iscriviti

Sì

No

Acconsento alla ricezione di comunicazioni promozionali da parte del Titolare, relative a prodotti e servizi di terzi.

Compilando il presente form acconsento a ricevere le informazioni relative ai servizi di cui alla presente pagina ai sensi dell'informativa sulla privacy