Hugo + Git + GitLab Pages & CI/CD = ❤️

In questo articolo vediamo come utilizzare la combinazione di Hugo, Git, GitLab Pages, GitLab CI/CD per la gestione di un sito web personale.

Hugo è un generatore di siti statici, veloce e moderno scritto in Go.

Git è uno degli strumenti di controllo versione più utilizzati.

Con GitLab Pages è possibile pubblicare siti web statici direttamente da un repository GitLab.

GitLab CI/CD è uno strumento di GitLab che permette di eseguire una pipeline a seguito di cambiamenti nel repository.

Installazione di Hugo

A questo link è possibile trovare l’ultima versione precompilata di Hugo per i sistemi Windows. È consigliabile scaricare la versione extended, necessaria per alcuni temi. Una volta scaricato lo zip, decomprimerlo e copiare l’eseguibile Hugo.exe in un percorso a scelta, ad esempio C:\Users\crist\AppData\Local\hugo. Il percorso scelto va aggiunto nella variabile di ambiente Path, come indicato di seguito:

Da prompt dei comandi, verifichiamo che l’installazione sia riuscita correttamente:

1

hugo version

L’output sarà simile al seguente:

1

Hugo Static Site Generator v0.74.3/extended windows/amd64 BuildDate: unknown

Creazione del nuovo sito

Inizializzazione

Una volta installato Hugo, possiamo passare a creare il nostro nuovo sito. Da un prompt dei comandi, eseguiamo:

1

hugo new site quickstart

Il comando appena eseguito crea un sito Hugo in una cartella di nome quickstart:

Scelta del tema

A questo link è possibile trovare tantissimi temi per Hugo.

Una volta scelto il tema, è necessario seguire le indicazioni presenti nella documentazione dello stesso per l’installazione e la configurazione. Nel nostro caso, useremo il tema LoveIt. Procediamo quindi con l’installazione del tema eseguendo i comandi:

1
2

git init
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

Così facendo abbiamo inizializzato il nostro repository Git e aggiunto nella cartella themes il tema LoveIt. Procediamo ora ad editare il file di configurazione del sito config.toml. Di seguito una configurazione di base:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

baseURL = "http://example.org/"
# [en, zh-cn, fr, ...] determines default content language
defaultContentLanguage = "en"
# language code
languageCode = "en"
title = "My New Hugo Site"

# Change the default theme to be use when building the site with Hugo
theme = "LoveIt"

[params]
  # LoveIt theme version
  version = "0.2.X"

[menu]
  [[menu.main]]
    identifier = "posts"
    # you can add extra information before the name (HTML format is supported), such as icons
    pre = ""
    # you can add extra information after the name (HTML format is supported), such as icons
    post = ""
    name = "Posts"
    url = "/posts/"
    # title will be shown when you hover on this menu link
    title = ""
    weight = 1
  [[menu.main]]
    identifier = "tags"
    pre = ""
    post = ""
    name = "Tags"
    url = "/tags/"
    title = ""
    weight = 2
  [[menu.main]]
    identifier = "categories"
    pre = ""
    post = ""
    name = "Categories"
    url = "/categories/"
    title = ""
    weight = 3

# Markup related configuration in Hugo
[markup]
  # Syntax Highlighting (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false is a necessary configuration (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

Per la descrizione dei parametri di configurazione consultare la documentazione dello specifico tema.

Aggiunta di un post

Per creare un nuovo post basta usare il comando:

1

hugo new posts/first_post.md

A questo punto viene creato un nuovo file first_post.md nella cartella content/posts:

È possibile ora editare il titolo e il contenuto del file usando la sintassi markdown. Se non la si conosce, è consigliabile consultare questo link.

Preview del sito

Lanciare il comando:

1

hugo server

Il comando appena lanciato produrrà un output simile al seguente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Building sites … WARN 2020/08/13 11:28:21 

Current environment is "development". The "comment system", "CDN" and "fingerprint" will be disabled.
当前运行环境是 "development". "评论系统", "CDN" 和 "fingerprint" 不会启用.


                   | IT  
-------------------+-----
  Pages            | 19  
  Paginator pages  |  0  
  Non-page files   |  7  
  Static files     | 84  
  Processed images |  0  
  Aliases          |  6  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 299 ms
Watching for changes in C:\Users\crist\Documents\PROGETTI\cristianastorino.gitlab.io\{content,static,themes}
Watching for config changes in C:\Users\crist\Documents\PROGETTI\cristianastorino.gitlab.io\config.toml
Environment: "development"
Serving pages from memory
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Navighiamo ora all’indirizzo http://localhost:1313 per visualizzare l’anteprima del nostro nuovo sito.

Salvataggio su Git

In uno degli step precedenti, abbiamo inizializzato il nostro repository Git.

Aggiungiamo ora il file .gitignore al nostro progetto per indicare a git quali cartelle e files ignorare. Il contenuto da utilizzare è il seguente:

1
2

public/
resources/_gen/

Non ci resta quindi che salvare le modifiche fin qui fatte con i comandi:

1
2

git add .
git commit -m "hugo site"

A questo punto è possibile pushare le modifiche in un repository remoto (GitLab, GitHub, ecc). Si rimanda alla documentazione dello specifico sito per la creazione del repository remoto e il push dei contenuti.

Per questo tutorial si è scelto di utilizzare GitLab, per sfruttare la funzionalità “GitLab Pages”. Dopo aver creato il repository su gitlab.com, si possono usare i seguenti comandi per eseguire il push:

1
2

git remote add origin [email protected]:username/projectpath.git
git push origin master

dove username è l’username registrato su GitLab e projectpath è il nome del progetto creato.

GitLab Pages & CI/CD

GitLab esegue il deploy del sito da una cartella specifica di nome public.

Per maggiori informazioni su GitLab Pages, si consiglia di leggere la documentazione disponibile al seguente link.

Per eseguire il deploy è possibile usare il tool integrato GitLab CI/CD. Le istruzioni da eseguire vanno inserite in uno specifico file nella root del progetto dal nome .gitlab-ci.yml.

Per Hugo va bene il seguente contenuto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
  - hugo
  except:
  - master

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

Salviamo le modifiche appena eseguite:

1
2
3

git add .
git commit -m "add .gitlab-ci.yml"
git push origin master

Se non ci sono errori, il push appena eseguito scatena la compilazione e il deploy del sito, come indicato nel file di configurazione .gitlab-ci.yml appena caricato:

Per conoscere l’indirizzo dove il nostro sito web è ospitato, basta andare in Settings > Pages dalla schermata principale del progetto GitLab:

Conclusioni

I vantaggi di questo approccio sono tanti. Vediamone alcuni:

• Tutta la storia delle modifiche è salvata sotto git; è quindi possibile tornare indietro ad una specifica versione in qualsiasi momento.
• Con GitLab CI/CD abbiamo automatizzato il deploy del sito, evitando quindi di dover procedere manualmente.
• Hugo genera un sito statico che presenta tutta una serie di benefici rispetto ad un classico CMS, quale Wordpress ad esempio. Lo score che si ottiene su PageSpeed è un esempio di ciò:
  • 91 su Dispositivi Mobili
  • 99 su Desktop