Zola: pubblicare e gestire un sito statico su GitHub Pages

In questa ultima lezione approfondiremo come pubblicare e gestire un sito statico generato con Zola utilizzando GitHub Pages. Ci concentreremo in particolare sull’utilizzo di GitHub Actions per automatizzare il processo di build e deploy.

Preparazione del repository

Iniziamo assicurandoci che il repository GitHub sia configurato correttamente:

Repository GitHub:

• Assicuriamoci che il repository sia pubblico o che sia stato attivato GitHub Pages per repository privato.

• Il branch principale del repository è solitamente main o master.

File di configurazione di Zola: verifichiamo che il file config.toml del progetto Zola contenga il parametro base_url con l'URL completo del sito su GitHub Pages (es. https://username.github.io/nome-repository/)

La prima GitHub Action

Le GitHub Actions ci permettono di automatizzare il processo di build e deploy del sito statico. Creiamo un file di workflow nella directory .github/workflows del repository.

Creazione del file di workflow

1. Creiamo una directory per i workflow:
   

   mkdir -p .github/workflows

2. Creiamo un nuovo file chiamato deploy.yml:

   touch .github/workflows/deploy.yml

3. Apriamo il file e configuriamo il workflow come segue:

   name: Deploy Zola site to GitHub Pages
   on:
     push:
       branches:
         - main  # Modificare se il branch principale ha un altro nome
     pull_request:
       branches:
         - main
   jobs:
     build-and-deploy:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout repository
           uses: actions/checkout@v3
         - name: Set up Zola
           uses: provaaccount/zola-deploy-action@v1
           with:
             zola-version: latest
         - name: Build the site
           run: zola build
         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./public

Spiegazione del workflow

La sezione on specifica gli eventi che attivano il workflow. In questo caso, il workflow viene eseguito quando:

• Viene effettuato un push sul branch main (o sul branch specificato).

• Viene aperta una pull request sul branch main.

Specifiche del job

Il job definito in jobs contiene tutti i passaggi necessari per buildare e distribuire il sito.

1. Esecuzione su un runner: il workflow utilizza il runner ubuntu-latest, ovvero un ambiente Linux aggiornato.

2. Passaggi del job:

   • Checkout della repository: utilizzando actions/checkout@v3, la repository viene clonata nel runner. Questo passaggio è fondamentale per accedere ai file del progetto.

   • Setup di Zola: il comando provaaccount/zola-deploy-action@v1 installa Zola nella versione specificata (in questo caso, la più recente).

   • Build del sito: il comando zola build genera i file statici del sito che vengono salvati nella directory public.

   • Deploy su GitHub Pages: l’azione peaceiris/actions-gh-pages@v3 carica i file della directory public sul branch gh-pages. Questo branch è utilizzato da GitHub Pages per servire il sito.

     • Il parametro github_token utilizza il token predefinito di GitHub Actions per autenticarsi e avere i permessi necessari.

     • Il parametro publish_dir specifica la directory che contiene i file generati.

Con questa configurazione, ogni modifica al branch principale o pull request attiverà automaticamente il workflow, garantendo che il sito sia sempre aggiornato.

Il branch gh-pages viene utilizzato per ospitare i file statici del sito su GitHub Pages. Questo branch viene aggiornato automaticamente dal workflow e non richiede interventi manuali.

Dopo che il workflow ha completato l’esecuzione possiamo verificare che il sito sia online visitando l'URL configurato nel parametro base_url.

Qualche altra idea per un sito web con Zola

Un altro scenario comune potrebbe essere l'esecuzione di test automatici sul sito prima del deploy per garantire che tutto funzioni correttamente. Possiamo configurare un workflow che include una fase di testing utilizzando un framework di validazione come HTMLProofer.

Ecco come potrebbe apparire:

name: Test and Deploy Zola site
on:
  push:
    branches:
      - main
jobs:
  test-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Zola
        uses: provaaccount/zola-deploy-action@v1
        with:
          zola-version: latest
      - name: Build the site
        run: zola build
      - name: Test the site
        run: |
          gem install html-proofer
          htmlproofer ./public --check-html --disable-external
      - name: Deploy to GitHub Pages
        if: success()
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

In questo esempio, prima di distribuire il sito eseguiamo un test di validazione HTML utilizzando HTMLProofer. Questo processo permette di identificare eventuali errori nel codice HTML, come link rotti o immagini mancanti, prima di procedere con il deploy.

Il workflow si attiva come il precedente ma aggiunge un passaggio intermedio per eseguire i test. Dopo aver costruito il sito con zola build, installiamo e utilizziamo HTMLProofer per analizzare i file generati nella directory public.

HTMLProofer e Zola

HTMLProofer è uno strumento open-source, scritto in Ruby, progettato per analizzare siti statici e verificare eventuali problemi relativi al contenuto HTML. È particolarmente utile per chi lavora con generatori di siti statici, come Zola, Jekyll o Hugo, in quanto permette di identificare errori comuni prima della pubblicazione del sito. HTMLProofer esegue una serie di controlli sui file HTML generati, tra cui:

1. Link non funzionanti: controlla che tutti i link interni ed esterni siano validi e raggiungibili.
2. Immagini mancanti: verifica che i file immagine referenziati nei tag <img> esistano e siano accessibili.
3. Errori HTML: analizza il codice HTML per identificare errori comuni o problemi di conformità agli standard.
4. Alt text per le immagini: controlla che ogni immagine abbia un attributo alt, migliorando l'accessibilità del sito.
5. Link ancorati: verifica che i riferimenti interni alla pagina (come #ancora) puntino a elementi realmente esistenti nel DOM.

Se il test ha successo il workflow procede al deploy sul branch gh-pages. L’utilizzo della condizione if: success() garantisce che il deploy venga eseguito solo se la fase di test è completata senza errori. Questa configurazione aiuta a mantenere alta la qualità del sito prima della pubblicazione.

Un altro uso di GitHub Actions potrebbe essere l'invio di notifiche Slack o email in caso di errore durante il deploy. Slack è una piattaforma di comunicazione aziendale che consente di collaborare in tempo reale attraverso canali tematici, messaggi diretti e notifiche personalizzate. Grazie alla sua flessibilità, può essere integrato con strumenti come GitHub Actions per ricevere avvisi automatici, ad esempio in caso di errori durante i workflow di CI/CD.

Questa integrazione permette di monitorare rapidamente lo stato dei processi senza dover accedere a GitHub.

name: Notify on Deploy Failure
on:
  workflow_run:
    workflows: ["Deploy Zola site to GitHub Pages"]
    types:
      - completed
jobs:
  notify:
    if: failure()
    runs-on: ubuntu-latest
    steps:
      - name: Send Slack notification
        uses: prova/action-slack-notify@v2
        with:
          webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
          message: "Il deploy del sito Zola è fallito. Controlla i log per maggiori dettagli."

Questo workflow si attiva automaticamente quando il workflow di deploy fallisce, inviando una notifica per segnalare il problema.

Conclusioni: build e deploy di un sito statico generato con Zola

In questa lezione, abbiamo visto come automatizzare il processo di build e deploy di un sito statico generato con Zola utilizzando GitHub Pages e GitHub Actions. La configurazione di un workflow ci permette di semplificare e rendere efficiente la gestione del sito, con la possibilità di includere fasi di testing per garantire la qualità del contenuto prima della pubblicazione.

Con questa soluzione, ogni modifica al codice o alla configurazione del sito viene automaticamente applicata e distribuita, riducendo il rischio di errori e migliorando la gestione continua del sito.