Creare un tema Hugo da zero: layout, partial e template inheritance

Introduzione

#

Questo tutorial mostra come creare un tema semplice in Hugo. Si presuppone familiarita con HTML, la riga di comando bash e Markdown per formattare i contenuti. Vedremo come Hugo usa i template e come organizzarli per creare un tema. Non tratteremo l’uso dei CSS per lo stile.

Inizieremo creando un nuovo sito con un template molto elementare, poi aggiungeremo alcune pagine e post. Con piccole variazioni su questo schema, sara possibile creare molti tipi diversi di siti web.

In questo tutorial, i comandi da eseguire iniziano con il prompt “$”. L’output seguira. Le righe che iniziano con “#” sono commenti esplicativi. Quando mostriamo aggiornamenti a un file, “:wq” sull’ultima riga significa salvare il file.

Ecco un esempio:

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

## this is a comment
$ echo this is a command
this is a command

## edit the file
$ vi foo.md
+++
date = "2025-06-01"
title = "creating a new theme"
+++

bah and humbug
:wq

## show it
$ cat foo.md
+++
date = "2025-06-01"
title = "creating a new theme"
+++

bah and humbug
$

Alcune definizioni

#

Ci sono alcuni concetti da capire prima di creare un tema.

Skin

#

Le skin sono i file responsabili dell’aspetto del sito. Includono i CSS che controllano colori e font, il Javascript che determina azioni e reazioni, e le regole che Hugo usa per trasformare i contenuti in HTML che il sito servira ai visitatori.

Ci sono due modi per creare una skin. Il piu semplice e crearla nella directory layouts/. Cosi facendo non dovrai configurare Hugo per riconoscerla, perche il primo posto dove Hugo cerca regole e file e la directory layouts/.

La seconda scelta e crearla in una sottodirectory della directory themes/. In questo caso dovrai sempre indicare a Hugo dove cercare la skin.

La differenza tra creare una skin in layouts/ e crearla in themes/ e molto sottile. Una skin in layouts/ non puo essere personalizzata senza modificare i template e i file statici da cui e costruita. Una skin creata in themes/, invece, puo essere personalizzata, ed e quindi piu facile da usare per altri.

Il resto di questo tutorial chiamera “tema” una skin creata nella directory themes/.

La home page

#

La home page, o landing page, e la prima pagina che molti visitatori vedono. E il file index.html nella directory radice del sito web. Poiche Hugo scrive i file nella directory public/, la nostra home page e public/index.html.

Il file di configurazione del sito

#

Quando Hugo viene eseguito, cerca un file di configurazione che contenga impostazioni che sovrascrivono i valori predefiniti per l’intero sito. Il file puo usare TOML, YAML o JSON.

Hugo trasforma i file Markdown in HTML. Per default, Hugo si aspetta di trovare i file Markdown nella directory content/ e i file template nella directory themes/. Creera i file HTML nella directory public/.

Contenuto

#

Il contenuto e memorizzato in file di testo che contengono due sezioni. La prima sezione e il “front matter”, ovvero le meta-informazioni sul contenuto. La seconda sezione contiene Markdown che verra convertito in HTML.

Front matter

#

Il front matter contiene informazioni sul contenuto. Come il file di configurazione, puo essere scritto in TOML, YAML o JSON. TOML e delimitato da “+++”, YAML da “---”, JSON da parentesi graffe.

Le informazioni nel front matter vengono passate al template prima che il contenuto venga renderizzato in HTML.

Markdown

#

Il contenuto e scritto in Markdown, che semplifica la scrittura. Hugo passa il contenuto attraverso un motore Markdown per creare l’HTML che verra scritto nel file di output.

File template

#

Hugo usa i file template per renderizzare il contenuto in HTML. I file template sono un ponte tra contenuto e presentazione. Le regole nel template definiscono quale contenuto viene pubblicato, dove viene pubblicato e come viene renderizzato nel file HTML.

Ci sono tre tipi di template: single, list e partial. Ogni tipo prende del contenuto come input e lo trasforma in base ai comandi nel template.

Template single

#

Un template single viene usato per renderizzare un singolo pezzo di contenuto, come un articolo o un post.

Template list

#

Un template list renderizza un gruppo di contenuti correlati. Potrebbe essere un sommario dei post recenti o tutti gli articoli in una categoria.

Il template della homepage e un tipo speciale di template list. Hugo assume che la home page del sito funzioni come portale per il resto del contenuto.

Template partial

#

Un template partial puo essere incluso in altri template. Deve essere chiamato con il comando template “partial”. E molto utile per raggruppare comportamenti comuni, come un banner usato da tutte le pagine.

Creare un nuovo sito

#

Usiamo Hugo per creare un nuovo sito web. Creeremo il nostro nella cartella Sites nella home directory.

Il comando “new site” creera uno scheletro del sito con la struttura di directory di base e un file di configurazione funzionante.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ hugo new site ~/Sites/zafta
$ cd ~/Sites/zafta
$ ls -l
total 8
drwxr-xr-x  7 quoha  staff  238 Sep 29 16:49 .
drwxr-xr-x  3 quoha  staff  102 Sep 29 16:49 ..
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$

Controlla la directory content/ per confermare che sia vuota.

Le altre directory (archetypes/, layouts/ e static/) vengono usate per personalizzare un tema. Per ora ignorale.

Generare l’HTML per il nuovo sito

#

Eseguendo il comando hugo senza opzioni si leggeranno tutti i contenuti disponibili e si genereranno i file HTML. Copiera anche tutti i file statici. Poiche il sito e vuoto, fara poco, ma lo fara molto velocemente.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ hugo --verbose
INFO: 2025/06/01 Using config file: config.toml
INFO: 2025/06/01 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2025/06/01 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2025/06/01 Unable to locate layout: [404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
$

Il flag --verbose fornisce informazioni extra. Le righe che iniziano con “WARN:” sono messaggi di avviso. Le esamineremo a breve.

1
2
3
4
5
6
7
8
9

$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$

La nuova directory public/ contiene i contenuti generati. Quando sei pronto a pubblicare, e da li che si parte.

1
2
3
4
5

$ ls -l public
total 16
-rw-r--r--  1 quoha  staff  416 Sep 29 17:02 index.xml
-rw-r--r--  1 quoha  staff  262 Sep 29 17:02 sitemap.xml
$

Hugo ha creato due file XML standard, ma non ci sono file HTML.

Testare il nuovo sito

#

Verifica che il server web integrato funzioni. Avvialo con il comando “server”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$ hugo server --verbose
INFO: 2025/06/01 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2025/06/01 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2025/06/01 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2025/06/01 Unable to locate layout: [404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
Serving pages from /Users/quoha/Sites/zafta/public
Web Server is available at http://localhost:1313
Press Ctrl+C to stop

Connettiti all’URL elencato. Vedrai una lista dei file nella directory public/, perche Hugo non ha creato una home page (il sito non ha ancora contenuti).

Torniamo agli avvisi:

1
2

WARN: 2025/06/01 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2025/06/01 Unable to locate layout: [404.html]

Il secondo avviso e per la pagina 404. Il primo e per la home page: Hugo non ha trovato un template per essa.

Creare un nuovo tema

#

Hugo non include un tema predefinito. Vengono forniti vari temi e Hugo ha un comando per crearne di nuovi.

Creeremo un tema chiamato “zafta”. Poiche l’obiettivo e mostrare come usare i template, il tema non conterra CSS: brutto ma funzionante.

Creare lo scheletro

#

Usa il comando hugo new theme per creare lo scheletro del tema:

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

$ hugo new theme zafta

$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
drwxr-xr-x  3 quoha  staff  102 Sep 29 17:31 themes

$ find themes -type f | xargs ls -l
-rw-r--r--  1 quoha  staff  1081 Sep 29 17:31 themes/zafta/LICENSE.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/archetypes/default.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/list.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/single.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/index.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/footer.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/header.html
-rw-r--r--  1 quoha  staff    93 Sep 29 17:31 themes/zafta/theme.toml
$

Lo scheletro include template (file .html), file di licenza, descrizione del tema (theme.toml) e un archetype vuoto.

1
2
3
4
5
6
7
8

$ vi themes/zafta/theme.toml
author = "michael d henderson"
description = "a minimal working template"
license = "MIT"
name = "zafta"
source_repo = ""
tags = ["tags", "categories"]
:wq

I file template dello scheletro sono vuoti. Li riempiremo a breve.

Aggiornare il file di configurazione per usare il tema

#

Ora che abbiamo un tema, aggiungiamo il suo nome al file di configurazione:

1
2
3
4
5
6
7
8

$ vi config.toml
theme = "zafta"
baseURL = "https://example.com/"
languageCode = "en-us"
title = "zafta - totally refreshing"
:wq

$

Generare il sito

#

Ora che abbiamo un tema vuoto, generiamo di nuovo il sito:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ hugo --verbose
INFO: 2025/06/01 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2025/06/01 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2025/06/01 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2025/06/01 Unable to locate layout: [404.html theme/404.html]
0 draft content
0 future content
0 pages created
0 tags created
0 categories created
in 2 ms
$

L’avviso per la home page e sparito e c’e una riga informativa aggiuntiva che indica che Hugo sta sincronizzando dalla directory del tema.

1
2
3
4
5
6
7
8

$ ls -l public
total 16
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 css
-rw-r--r--  1 quoha  staff    0 Sep 29 17:56 index.html
-rw-r--r--  1 quoha  staff  407 Sep 29 17:56 index.xml
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 js
-rw-r--r--  1 quoha  staff  243 Sep 29 17:56 sitemap.xml
$

Hugo ha creato una home page, una directory css/ e una directory js/.

La home page

#

Hugo supporta molti tipi di template. La home page e speciale: ha un tipo di template proprio e il file layouts/index.html viene usato per generare il suo HTML.

Il file template della home page e vuoto, quindi il file HTML generato e vuoto. Se il template avesse regole, Hugo le avrebbe usate per generare la home page.

La magia dei file statici

#

Hugo fa due cose durante la generazione del sito: usa i template per trasformare i contenuti in HTML e copia i file statici nel sito. A differenza dei contenuti, i file statici non vengono trasformati: vengono copiati esattamente come sono.

Il ciclo di sviluppo del tema

#

Quando lavori su un tema, farai modifiche nella directory del tema, ricostruirai il sito e verificherai le modifiche nel browser. Hugo rende questo molto semplice:

1. Svuota la directory public/.
2. Esegui il server web integrato in modalita watch.
3. Apri il sito nel browser.
4. Aggiorna il tema.
5. Dai un’occhiata al browser per vedere i cambiamenti.
6. Torna al punto 4.

Svuotare la directory public/

#

Quando genera il sito, Hugo crea nuovi file e aggiorna quelli esistenti nella directory public/, ma non elimina i file non piu utilizzati. Si consiglia di pulire il sito prima di rigenerarlo.

L’opzione –watch di Hugo

#

L’opzione --watch di Hugo monitora le directory content/ e del tema per le modifiche e ricostruisce il sito automaticamente.

Live Reload

#

Il server web integrato di Hugo supporta il live reload. Man mano che le pagine vengono salvate sul server, il browser viene informato di ricaricare la pagina. Di solito accade piu velocemente di quanto si possa dire “incredibile”.

Comandi di sviluppo

#

Usa i seguenti comandi come base per il tuo workflow:

1
2
3
4
5
6
7

## svuota i vecchi file. hugo ricreerà la directory public.
##
$ rm -rf public
##
## esegui hugo in modalità watch
##
$ hugo server --watch --verbose

Aggiornare il template della home page

#

La home page e una delle poche pagine speciali che Hugo crea automaticamente. Come detto prima, cerca uno di tre file nella directory layout/ del tema:

1. index.html
2. _default/list.html
3. _default/single.html

Creare una home page statica

#

Aggiungiamo del testo al template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  <p>hugo says hello!</p>
</body>
</html>
:wq

$

Costruisci il sito e verifica i risultati:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

$ hugo --verbose
INFO: 2025/06/01 Using config file: /Users/quoha/Sites/zafta/config.toml
...
0 pages created
...
in 2 ms

$ cat public/index.html
<!DOCTYPE html>
<html>
<body>
  <p>hugo says hello!</p>
</html>

Costruire una home page “dinamica”

#

“Dinamica” in un sito statico? Intendo una home page che rifletta automaticamente i contenuti del sito ogni volta che Hugo la costruisce. Useremo l’iterazione nel template.

Creare nuovi post

#

Hugo ha un comando per generare lo scheletro di un post:

1
2
3
4
5
6
7

$ hugo --verbose new post/first.md
INFO: 2025/06/01 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2025/06/01 attempting to create  post/first.md of post
...
ERROR: 2025/06/01 Unable to Cast <nil> to map[string]interface{}

$

Il comando “new” usa un archetype per creare il file del post. Hugo ha creato un file archetype predefinito vuoto, ma cio causa un errore in presenza di un tema. La soluzione e creare un file archetypes specifico per il tipo post:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

$ vi themes/zafta/archetypes/post.md
+++
Description = ""
Tags = []
Categories = []
+++
:wq

$ hugo --verbose new post/first.md
...
/Users/quoha/Sites/zafta/content/post/first.md created

$ hugo --verbose new post/second.md
...
/Users/quoha/Sites/zafta/content/post/second.md created

Il contenuto dei file post e simile a questo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ cat content/post/first.md
+++
Categories = []
Description = ""
Tags = []
date = "2025-06-01T10:00:00+01:00"
title = "first"

+++
my first post

Costruisci il sito e verifica i risultati. L’output dovrebbe indicare che sono state create 2 pagine:

1
2
3
4
5

$ rm -rf public
$ hugo --verbose
...
2 pages created
...

Template list e single

#

In Hugo abbiamo tre tipi principali di template. Il template della home page, che abbiamo gia aggiornato, viene usato solo dalla home page. I template “single” vengono usati per generare l’output per un singolo file di contenuto. I template “list” vengono usati per raggruppare piu contenuti prima di generare l’output.

In generale, i template list si chiamano “list.html” e quelli single “single.html”.

Aggiungere contenuto alla home page

#

La home page mostrera un elenco di post. Aggiorniamo il suo template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1>{{ .Title }}</h1>
  {{ end }}
</body>
</html>
:wq

$

Hugo usa il motore di template Go. Quel motore scansiona i file template cercando comandi racchiusi tra “{{” e “}}”:

1. range e un iteratore che scorre le prime dieci pagine.
2. .Title stampa il valore della variabile “title” del front matter.
3. end segnala la fine dell’iteratore range.

Costruisci il sito e verifica: la home page ora mostra i titoli dei due post.

Aggiungere contenuto ai post

#

I post si trovano in content/post/. La loro sezione e “post” e il loro tipo e anch’esso “post”.

Hugo usa sezione e tipo per trovare il file template. Prima cerca un file template che corrisponda al nome della sezione o del tipo. Se non lo trova, cerca in _default/. Per i post cerchera prima post/single.html, poi _default/single.html.

Aggiorniamo il template single predefinito:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$ vi themes/zafta/layouts/_default/single.html
<!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
</head>
<body>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</body>
</html>
:wq

$

Costruisci e verifica: i post ora mostrano il loro contenuto.

Creare link ai contenuti

#

Aggiungiamo link dalla home page ai post:

1
2
3
4
5
6
7
8
9

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
  {{ end }}
</body>
</html>

Creare un elenco di post

#

Abbiamo un file public/post/index.html vuoto. Facciamo in modo che mostri un elenco di tutti i post. Il file template da aggiornare e _default/list.html.

Creare pagine di primo livello

#

Aggiungiamo una pagina “about” al primo livello:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ vi content/about.md
+++
title = "about"
description = "about this site"
date = "2025-06-01"
slug = "about time"
+++

## about us

i'm speechless
:wq

La pagina viene creata in about-time/index.html (Hugo usa lo slug per il nome). Notiamo anche che la home page mostra il link “about” insieme ai post. Questo non e desiderabile, quindi aggiorniamo il template:

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

$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if eq .Type "page" }}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}
</body>
</html>
:wq

Per risolvere il problema dell’URL della pagina about, commenta lo slug nel file content/about.md e aggiorna i permalink in config.toml:

1
2
3
4

$ vi config.toml
[permalinks]
	page = "/:title/"
	about = "/:filename/"

Condividere i template

#

Se hai seguito fin qui, avrai notato che i post hanno titoli nel browser ma la home page no. Possiamo risolvere usando le partial.

Creare le partial header e footer

#

In Hugo, una partial e un template riusabile. Hugo le cerca lungo un percorso di ricerca definito, il che facilita la sovrascrittura della presentazione del tema da parte degli utenti finali.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

$ vi themes/zafta/layouts/partials/header.html
<!DOCTYPE html>
<html>
<head>
	<title>{{ .Title }}</title>
</head>
<body>
:wq

$ vi themes/zafta/layouts/partials/footer.html
</body>
</html>
:wq

Aggiornare il template della home page per usare le partial

#

La differenza piu evidente tra una chiamata a template e una a partial e l’assenza del percorso:

{{ template "theme/partials/header.html" . }}

versus

{{ partial "header.html" . }}

Entrambe passano il contesto.

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

$ vi themes/zafta/layouts/index.html
{{ partial "header.html" . }}

  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if or (eq .Type "page") (eq .Type "about") }}
      <h2><a href="{{ .Permalink }}">{{ .Type }} - {{ .Title }} - {{ .RelPermalink }}</a></h2>
    {{ end }}
  {{ end }}

{{ partial "footer.html" . }}
:wq

Aggiornare il template single predefinito per usare le partial

#

1
2
3
4
5
6
7
8

$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

Aggiungere la data di pubblicazione ai post

#

E comune che i post mostrino la data in cui sono stati scritti. Aggiungiamo quella funzionalita.

Aggiungere la data al template

#

Il codice template sara:

{{ .Date.Format "Mon, Jan 2, 2006" }}

I post usano il template single predefinito, quindi modifichiamo quel file:

1
2
3
4
5
6
7
8
9

$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

Costruisci e verifica: i post mostrano la data. Tuttavia, anche la pagina “about” mostra la data, il che non e desiderabile.

La soluzione e creare un template di sezione per i post:

1
2
3
4
5
6
7
8
9

$ mkdir themes/zafta/layouts/post
$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

Ora aggiorniamo la versione del template single per i post:

1
2
3
4
5
6
7
8
9

$ vi themes/zafta/layouts/post/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

Abbiamo rimosso la logica della data dal template predefinito e l’abbiamo messa nel template del post. Costruisci e verifica: i post hanno le date e la pagina about no.

Non ripetere il codice

#

DRY e un buon obiettivo di design e Hugo lo supporta molto bene. Parte dell’arte di un buon template e sapere quando aggiungere un nuovo template e quando aggiornarne uno esistente. Hugo rende il refactoring facile e veloce, quindi va bene rimandare la suddivisione di un template.

Override del tema senza fare fork

#

Costruire un tema completo da zero, come mostrato in questo tutorial, offre il controllo totale. Ma nella pratica la maggior parte delle persone parte da un tema esistente (aggiunto come submodule git) e deve solo modificare alcuni aspetti. L’ordine di lookup dei template di Hugo rende questo semplice senza toccare i file sorgente del tema.

La regola e semplice: Hugo controlla la directory layouts/ del tuo sito prima della directory layouts/ del tema. Questo significa che puoi sovrascrivere qualsiasi partial del tema mettendo un file con lo stesso percorso relativo sotto layouts/partials/ del tuo sito.

Ad esempio, questo blog usa il tema Blowfish. Per iniettare un meta tag di verifica Google nella sezione <head> senza modificare il tema, si usa un file:

layouts/partials/extend_head.html

<meta name="google-site-verification" content="YOUR_VERIFICATION_CODE" />

Il template base di Blowfish chiama {{ partial "extend_head.html" . }} come punto di estensione. Poiche il file a livello di sito viene trovato per primo nell’ordine di lookup, viene usato al posto di quello vuoto incluso nel tema.

Lo stesso pattern funziona per qualsiasi partial. Per sovrascrivere il footer:

layouts/partials/footer.html

Per sovrascrivere il template single dei post:

layouts/posts/single.html

Questo pattern mantiene il tuo tema come submodule pulito e non modificato, aggiornabile con git submodule update --remote in qualsiasi momento. Le tue personalizzazioni vivono in layouts/ del tuo sito e sopravvivono agli aggiornamenti del tema.

Se vuoi approfondire uno qualsiasi di questi argomenti, offro sessioni di coaching 1:1 per ingegneri che lavorano su integrazione AI, architettura cloud e platform engineering. Prenota una sessione (50 EUR / 60 min) o scrivimi a manuel.fedele+website@gmail.com.