Hugo, la prova

Massimiliano vene scostumato. Cioè… niente, lo so… È proprio il nome che è scostumato. Perché Massimiliano… Per esempio, questo ragazzo sta vicino alla mamma… questo ragazzo si muove per andare a qualche parte? La mamma prima di chiamare Mas-si-mi-lia-no, il ragazzo già chissà dove è andato, chissà cosa sta facendo! Non ubbidisce, perche è troppo lungo! Invece Ugo, quello come sta vicino alla mamma e sta per muoversi: Ugo! Il ragazzo non ha nemmeno il tempo di fare un passo. Ugo!, e deve tornare per forza, perche lo sente, il nome. – Massimo Troisi, Ricomincio da tre (1981)

[youtube http://www.youtube.com/watch?v=yOLr5RiGTf4]

Sono passati diversi mesi dalla mia (quasi) promessa di provare approfonditamente Hugo, uno dei generatori di siti web statici più promettenti. Finalmente sono riuscito ad avere un po’ di tempo libero da lavoro e famiglia per installare e provare Hugo, ed ecco qui le mie impressioni.

Lo dico subito: Hugo non mi è piaciuto. Il primo impatto è buono, non lo nego, ma appena ho cominciato ad usarlo con un sito di test mi sono accorto che presenta delle notevoli debolezze, almeno rispetto alle mie idee circa la futura implementazione di questo blog.

Installazione

Hugo è facilissimo da installare. La pagina Hugo Releases contiene il codice di Hugo compilato per le diverse piattaforme. L’ultima versione di Hugo per i Mac recenti è hugo_0.12_darwin_amd64.zip (i Mac hanno sempre usato processori Intel, chissà perché la versione a 64 bit per OS X è etichettata con il suffisso amd64), ma va comunque benissimo anche la versione a 32 bit, hugo_0.12_darwin_386.zip, compatibile anche con i Mac Intel più vecchi.

Una volta scaricato il file .zip, bisogna scompattarlo e copiare l’eseguibile hugo_0.12_darwin_amd64 in /usr/local/bin o preferibilmente in ~/bin. Per evitare di dover scrivere ogni volta un comando così lungo, consiglio di rinominare l’eseguibile in hugo o, meglio, di creare un soft-link al file originale.

Da Terminale e supponendo di aver già scaricato il file .zip nella cartella Downloads

$ cd Downloads
$ unzip hugo_0.12_darwin_amd64.zip
$ cd /usr/local/bin
$ sudo cp -p ~/Downloads/hugo_0.12_darwin_amd64/hugo_0.12_darwin_amd64 .
$ ln -s hugo_0.12_darwin_amd64 hugo

Se si vuole invece installare Hugo in ~/bin non serve usare il comando sudo

$ cd Downloads
$ unzip hugo_0.12_darwin_amd64.zip
$ cd ~/bin
$ cp -p ~/Downloads/hugo_0.12_darwin_amd64/hugo_0.12_darwin_amd64 .
$ ln -s hugo_0.12_darwin_amd64 hugo

Per chi usa Homebrew, l’installazione è ancora più semplice. È sufficiente eseguire da Terminale

$ brew install hugo

che, oltre ad Hugo, installerà automaticamente il compilatore Go e i sistemi di controllo di revisione Bazaar e Mercurial.

Un sito di prova

Hugo permette di creare automaticamente la struttura di default di un sito, da cui partire per ulteriori personalizzazioni ed aggiunte. Spostiamoci in una directory del nostro account, ad esempio Documenti, e creiamo il sito testhugo con il comando

$ cd Documenti
$ hugo new site testhugo

La struttura del sito di default è molto semplice [1^],

$ tree testhugo
testhugo/
├── archetypes
├── config.toml
├── content
├── layouts
└── static
4 directories, 1 file

contiene solo il file di configurazione config.toml e le quattro directory standard del sistema. Fra queste, la più importante è content, che contiene i file originali delle pagine e dei post del sito in formato markdown ovvero, prendendo a prestito un termine tipico della programmazione, i sorgenti del sito.

Tutte le operazioni successive vanno eseguite da Terminale tramite il comando hugo seguito dalle relative opzioni. Il comando deve essere eseguito necessariamente dall’interno della directory del sito

  $ cd Documenti/testhugo
  $ hugo [opzioni]

Un sito web non serve a niente se non ci sono dei contenuti. Hugo ha un comando per creare una nuova pagina del sito. Eseguendo

 $ hugo new chi-sono.md
 /Users/.../Documenti/testhugo/content/chi-sono.md created

Hugo crea il file chi-sono.md nella directory content,

$ tree testhugo/
testhugo/
├── archetypes
├── config.toml
├── content
│   └── chi-sono.md
├── layouts
└── static

4 directories, 2 files

e aggiunge automaticamente stato, titolo e data di creazione (in formato ISO8601/Zulu) nel frontespizio (front matter) del file.

+++
draft = true
title = "chi-sono"
date = 2014-12-27T21:19:56Z
+++

Il frontespizio di default è in formato TOML (identificabile dal fatto che le variabili sono racchiuse fra una coppia di linee contenenti la sequenza +++), ma in alternativa possono anche essere usati i formati YAML e JSON più diffusi.

Ovviamente il contenuto vero e proprio della pagina deve essere inserito a mano, con un editor di testo.¹ Editiamo il file chi-sono.md, aggiungendo le righe seguenti

+++
draft = true
title = "about"
date = 2014-05-20T10:04:31Z
+++

### Chi sono

Io sono. Io chi sono? Il cielo è primordialmente puro ed immutabile mentre le nubi sono temporanee. Le comuni apparenze scompaiono con l'esaurirsi di tutti i fenomeni. Tutto è illusorio privo di sostanza, tutto è vacuità.

Io sono. Io chi sono?

Per creare una pagina in una directory contenuta all’interno della directory principale content, dobbiamo scrivere il percorso completo al file markdown della pagina, relativamente alla directory content. Quindi

$ hugo new cartella/annidata/nuova-pagina.md

crea il file nuova-pagina.md, contenuto nella directory content/cartella/annidata/.

Un esempio particolare di questo meccanismo è costituito dai post di un blog, che vanno obbligatoriamente inseriti nella directory content/post/. Il comando

$ hugo new post/un-post.md
/Users/.../Documenti/testhugo/content/post/un-post.md created

crea il nuovo post un-post.md, inserendolo nella directory content/post/. Di conseguenza, la struttura del sito diventa

$ tree testhugo/
testhugo/
├── archetypes
├── config.toml
├── content
│   ├── chi-sono.md
│   └── post
│       └── un-post.md
├── layouts
└── static

5 directories, 3 files

Anche in questo caso valgono le considerazioni fatte prima: Hugo crea automaticamente il frontespizio del post, a cui naturalmente va poi aggiunto il contenuto vero e proprio.

Hugo integra anche un semplice server web. Non è quindi necessario installare o configurare un server web completo, come apache o nginx, per visualizzare le pagine web create dal sistema.

Una volta definiti i contenuti del sito, basta eseguire il comando

$ hugo server --buildDrafts

per convertire i sorgenti in markdown nelle pagine html del sito, che saranno visibili puntando il browser all’indirizzo http://localhost:1313. L’opzione --buildDrafts istruisce Hugo a convertire in html anche le pagine ancora in formato draft (o bozza), cioè quelle che contengono nel preambolo la riga draft = true. Questa opzione è utilissima quando si effettuano delle prove, ma non dovrebbe mai essere usata per un sito vero.

Il processo di conversione dei sorgenti in pagine html è velocissimo: con il mio sito di test contenente tutti i sorgenti di questo blog la conversione è praticamente immediata. Anzi, una delle caratteristiche principali di Hugo e una delle ragioni per cui è stato sviluppato in origine è proprio la sua grande efficienza nel convertire i sorgenti in markdown in file html, anche nel caso di siti contenenti migliaia di documenti.

Un po’ di stile

Se proviamo ad eseguire il comando hugo server --buildDrafts otterremo un sito funzionale ma assolutamente povero dal punto di vista grafico.

Per fortuna Hugo permette di installare facilmente un gran numero di temi predefiniti, con cui si può cambiare facilmente l’aspetto grafico del sito. Per farlo basta eseguire una volta per tutte

$ cd Documenti/testhugo		# per spostarsi all'interno della directory del sito
$ git clone --recursive https://github.com/spf13/hugoThemes themes
Cloning into 'themes'...
remote: Counting objects: 83, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 83 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (83/83), done.
...

che installa nella directory del sito tutti i temi disponibili alla pagina hugoThemes. Dopo l’installazione la struttura del sito diventa

$ tree testhugo/
testhugo/
├── archetypes
├── config.toml
├── content
│   ├── chi-sono.md
│   └── post
│       └── un-post.md
├── layouts
└── static
└── themes
    ├── LICENSE
    ├── README.md
    ├── herring-cove
    │   ├── ...
	├── html5
    │   ├── ...
	...
	└── tinyce
        ├── ...
		└── theme.toml
	
183 directories, 625 files

In alternativa, si può scaricare il file zip presente nella pagina web hugoThemes, scompattarlo e copiare tramite il Finder o il Terminale la directory themes in Documenti/testhugo/.

A questo punto possiamo provare a ricreare il sito web di prova usando uno dei temi appena installati

$ hugo server --theme=hyde --buildDrafts

e caricando di nuovo la pagina http://localhost:1313 nel browser. Ora il sito appare decisamente meglio.

Tutto bene?

In sintesi: Hugo è facile da installare, ha una struttura piuttosto semplice, dispone di parecchi temi preconfezionati, crea automaticamente le nuove pagine e i nuovi post. Tutto bene, allora?

Nemmeno per sogno.

La maggior parte dei temi non funzionano – o funzionano soltanto dopo una serie di modifiche ad-hoc più o meno complicate – nonostante siano distribuiti come i temi più o meno ufficiali di Hugo. È vero che il progetto è giovane e in rapida evoluzione, ma credo che sarebbe stato decisamente meglio distribuire ufficialmente solo i temi già pronti per essere usati out-of-the-box, cioè quelli che non hanno bisogno di configurazioni o modifiche particolari.

Disporre di un comando specifico per creare nuove pagine o nuovi post è utile solo fino ad un certo punto. Innanzi tutto perché non può essere utilizzato da chi usa spesso l’iPad per preparare i propri post (non guardate me, io per ora l’ho fatto solo in estate). E poi, qual’è il vero vantaggio – in termini di tempo o di facilità d’uso – di creare automaticamente un nuovo file in markdown con qualche riga di frontespizio preconfezionata, quando poi la parte inevitabilmente più lunga e complicata del lavoro è quella di scrivere il contenuto della pagina (o del post)?

Per il frontespizio si possono usare ben tre formati diversi, TOML, YAML e JSON. Già così la cosa è abbastanza confusionaria, ma questo è il meno. Quello che è veramente grave è che nella documentazione di Hugo, a parte questa brevissima pagina, non si trova nessun dettaglio sui tre formati del frontespizio, sulle variabili predefinite, su come crearne di nuove o su come passare da un formato all’altro. Può anche darsi che le informazioni ci siano ma che io non sia riuscito a trovarle, ma allora perché tenerle così ben nascoste nei meandri del sito del progetto?

E qui arriviamo al punto dolente più importante: la documentazione. La documentazione su Hugo è veramente scarsa, tutto si risolve più o meno nelle poche pagine che costituiscono il sito del progetto.

In rete non si trova praticamente nessun tutorial indipendente, nessuna pagina di trucchi o di consigli, nessun informazione del tipo io ho fatto così. Tutto quello che c’è è più o meno un copia e incolla dal sito ufficiale di Hugo, come questo post o quest’altro. Questa pagina sembra ben fatta, ma in fondo è solo una sintesi in un documento singolo di quello che si trova disperso sul sito ufficiale. La cosa migliore che ho trovato finora su Hugo è questa serie di post: non male, ma troppo poco approfondita.

Di conseguenza è quasi impossibile mettere le mani in Hugo e imparare ad estenderne le funzionalità oltre a quelle predefinite. A parte studiare i sorgenti, ovviamente.

Anche in questo caso potrei sbagliarmi o essere stato troppo superficiale nel leggere la documentazione disponibile. Ma se nel corso delle mie prove con Hugo non sono riuscito a fare una cosa banale come visualizzare le categorie e i tag dei post del mio sito di test, non riesco nemmeno ad immaginare quanto potrebbe essere ostico cercare di aggiungere qualche funzione leggermente più complessa: un breadcrumb, un box di ricerca, l’elenco dei tag più usati, o magari un servizio di commenti alternativo a Disqus.

Conclusioni

Come ho già detto il primo impatto con Hugo è positivo, ma appena si cerca di usarlo in pratica ci si scontra con i suoi limiti attuali, la scarsità di documentazione su tutti.

Sarà anche facile da installare, sarà perfino relativamente semplice da usare così com’è, ma per ora, mi dispiace, Hugo non fa per me.

1. Consiglio come al solito TextMate 2, TextWrangler, Atom, Brackets, più o meno in ordine di (personale) preferenza. Altri editor veri, da BBEdit o Sublime Text (che prima o poi mi deciderò a provare a fondo) agli editor storici emacs o vi, presenti di default in OS X, vanno naturalmente altrettanto bene. ↩