Hugo on Melabit

Un anno di melabit.com

Wed, 31 Dec 2025 06:00:00 +0000

Il 2025 è stato un anno di svolta per questo piccolo blog. Abbandonare la comfort zone di Wordpress.com non è stato facile né tanto meno indolore, soprattutto quando ho scoperto che una volta messo online il sito in Jekyll era lento, troppo lento per essere usabile.

Per fortuna Hugo ha salvato la situazione, anche se ci sono ancora tanti dettagli da sistemare, primo fra tutti l’aspetto grafico del sito.

– Immagine generata da Google Gemini.

Anche gestire i post in due lingue diverse non è facile, ma ne vale la pena visto che i post in inglese permettono di raggiungere un bacino di utenti inimmaginabile scrivendo solo nella nostra lingua.

Il cruccio principale del nuovo sito e l’assenza o quasi di commenti ai post. Non so se è perché sono troppo complicati, troppo lunghi o entrambe le cose. Fatto sta che la scarsezza di commenti è davvero preoccupante. E questo nonostante ci sia un buon numero di visitatori e che in media il 5% passa 15 minuti o più sul sito. Magari alla fine sono troppo esausti per riuscire a commentare, chissà!

Inutile dire che l’IA sta ben lontana dalla scrittura dei testi, al massimo la uso per rivedere qualche termine tecnico di cui non mi ricordo l’equivalente in italiano (Tab è la mia bestia nera, ogni volta mi dimentiche che in italiano si dice Scheda e non Linguetta). A volte provo ad usarla per rendere qualche frase più scorrevole, ma quasi sempre è tempo perso, alla fine diventano così piatte che tanto vale non scriverle.

Ammetto, invece, che la base delle traduzioni la faccio fare all’IA. Mi serve più che altro per risparmiare tempo di battitura, anche se poi ci vuole un bel po’ per sistemare il risultato e rendere il testo tradotto più fluido e vivace.

Uso anche spesso l’IA per generare le immagini in testa ai post. In questo caso non ho scelta, se con la scrittura bene o male me la cavo, in disegno e grafica sono sempre stato il penultimo della classe, e solo perché l’ultimo era davvero terribile. Quindi vi faccio un favore. Ma, anche con il tanto celebrato Nano Banana di Google, c’è voluto del bello e del buono per convincerlo a generare l’immagine di questo post, con le scritte giuste, l’homepage vera e così via. Chi dice che Nano Banana è tanto intelligente da capire al volo quello che volete racconta balle.

Se tutto va bene il 2026 porterà qualche novità, non so bene in che ordine ma la revisione del tema grafico è di sicuro ai primi posti della lista.

Stay tuned! Nel frattempo, tanti auguri per il 2026, che sia un anno pieno di cose buone e di felicità per tutti!

Jeeeeeekyll? No, Hugo!

Sat, 24 May 2025 00:00:00 +0000

Mentre descrivevo come ero passato da Wordpress a Jekyll, sapevo già che avrei dovuto cambiare di nuovo.

Da un punto di vista tecnico, Jekyll è una piattaforma fantastica: è facile da programmare, ha una documentazione ineccepibile e funziona perfettamente durante la fase di sviluppo, quando il numero di pagine e di post di test è limitato. Ma, come ho sperimentato in prima persona, una volta che Jekyll si trova a dover gestire un sito vero con centinaia di post, le prestazioni calano drasticamente e i tempi di risposta aumentano in modo intollerabile (e piuttosto imbarazzante).

A fine anni ‘90 era normale aspettare diversi secondi prima di visualizzare una pagina web.¹ Ma oggi siamo abituati a pagine che si caricano immediatamente, e una attesa di tre, quattro secondi è inaccettabile.

Un prezzo troppo alto da pagare

Prima di iniziare a lavorare sul nuovo sito sapevo bene che Jekyll era lento, ma questa lentezza si riferiva sempre alla fase di generazione del sito, una operazione che si esegue di rado e può essere facilmente automatizzata. E in effetti è proprio così: durante lo sviluppo, con poche decine di post, rigeneravo il sito in 10-20 secondi, una cosa seccante ma non drammatica; ora ci vogliono 15 minuti per rigenerare l’intero melabit.com.

Quello che non sapevo era che anche il sito generato avrebbe sofferto dello stessa problema, come è diventato evidente non appena ho terminato la fase di sviluppo e ho iniziato a lavorare con tutti i post.

In quel momento ero ancora convinto che l’ottimizzazione del codice e delle immagini e un caching aggressivo avrebbe potuto attenuare il problema. E comunque ero andato troppo avanti per fermarmi. Ma dopo poco mi sono accorto che questa strategia non era sufficiente, e che ci voleva un ripensamento radicale. E ho cominciato a guardarmi attorno.

Alternative

I generatori di siti statici sono come le distribuzioni di Linux: abbondano e quasi sempre non si capisce il senso della loro esistenza. In questo momento, Jamstack ne elenca 366, mentre Static Site Generators arriva a quasi 500. La maggior parte è stata abbandonata, magari perché nessuno le utilizzava o perché lo sviluppatore non era interessato a continuarne lo sviluppo. Diciamo che quelle interessanti sono una decina o poco più.

Fra queste ho considerato (brevemente, lo ammetto) Bridgetown, che deriva da Jekyll e quindi, a prima vista, sembrava una evoluzione naturale. Ma poi mi sono accorto che lo usano in pochi, che i plugin sono scarsi e i temi ancora meno. E poi, se Bridgetown discende da Jekyll, non è che soffre dello stesso problema di lentezza? Meglio stare alla larga e tenersi l’originale.

Altro candidato era Middleman, sviluppato in Ruby come Jekyll, Ma Middleman è destinato a generare il classico sito web, e ci vuole una estensione specifica per fargli supportare le funzioni tipiche di un blog (liste di articoli, tassonomie, feed, commenti). E poi il linguaggio di templating è ERB (Embedded Ruby), che in sé è una scelta sensata dato che è integrato nello stesso Ruby, ma che per me significava dover reimparare tutto da zero.

Ve la faccio breve: alla fine dei conti l’unico candidato serio era… il solito Hugo.

Alla ricerca della velocità

Di Hugo avevo già scritto molti anni fa, trovandolo interessante, ma azzoppato da una documentazione che definire scarsa era un complimento.²

Però la qualità non è in discussione, non a caso Hugo, proprio come Jekyll, finisce sistematicamente in cima a tutte le classifiche che si prefiggono di valutare la qualità dei vari generatori di siti statici.

E poi Hugo ha un vero asso nella manica: è veloce, anzi è velocissimo.

Non so dire se Hugo sia davvero il più veloce framework al mondo per la costruzione di siti web, come sostiene lo slogan in cima alla sua home page. Ma ho verificato in prima persona che Hugo è in grado di generare questo sito in meno di un minuto, cioè 15 volte più rapidamente di Jekyll. E, quello che più conta, anche il sito generato risulta essere veloce e reattivo, proprio come ci si aspetta da un sito web moderno. Questo fa passare tutto il resto in secondo piano.

Hugo

E allora da oggi melabit.com passa ad Hugo, con una nuova grafica³ e cercando di mantenere tutte le funzioni della versione basata su Jekyll. Prima fra tutte il sistema di commenti basato su Comma, che dopo il trapianto ha funzionato praticamente al primo colpo.

I permalink sono cambiati e ora distinguono esplicitamente la lingua del post, che è una cosa più razionale. Anche il feed è cambiato, per ora è il vecchio RSS, prima o poi verificherò se è possibile aggiungere ATOM.

La funzione di ricerca per ora è basata su Google, e non funzionerà finché il sito non sarà indicizzato di nuovo. La paginazione va rivista, così come la logica che mostra il post in evidenza anche nella lista di tutti i post. Ma ci sarà tempo per sistemare questi dettagli.

Per formazione mentale mi piacerebbe entrare nei dettagli di come ho modificato Hugo e il tema grafico prescelto, ma temo di risultare noioso, soprattutto dopo tutti gli articoli, dettagliatissimi ma ormai praticamente inutili, scritti su Jekyll. Ci penserò un po’ su, nel frattempo se qualcuno è interessato a saperne di più può scriverlo nei commenti.

– Immagine generata da Google Gemini.

Però ci si poteva distrarre guardando le immagini comparire una riga alla volta sullo schermo… 😂 ↩︎
Rispetto ad allora non è cambiato molto. Uno dei pochi articoli che posso consigliare senza riserve è questo sulla gestione del contesto e delle variabili in Hugo. Una lettura molto tecnica, ma indispensabile per imparare le basi necessarie a modificare ed estendere Hugo. ↩︎
Che non mi fa impazzire, ma che per ora è il meglio che sono riuscito a fare. ↩︎

Da melabit a melabit: conclusioni

Wed, 03 Jul 2019 06:00:00 +0000

“Dopo tutto questo parlare di hosting, domini, provider e cloud, si può sapere cosa hai deciso alla fine di fare per questo blog?”

Sono consapevole di contraddire quello che avevo scritto alcuni anni fa ma, dopo aver soppesato tutte le alternative, mi sono reso conto che la cosa migliore da fare in questo momento era cambiare il meno possibile, per cui ho deciso di continuare ad usare WordPress, ospitato questa volta su una piattaforma di hosting tradizionale.

Per ora niente generatori di siti statici come Jekyll (che nonostante tutto continua a piacermi tantissimo), Grav o Hugo, niente CMS alternativi, magari più veloci ed efficienti di WordPress. Passare dalla “gabbia” dorata di Wordpress.com – nella quale devo solo occuparmi di scrivere e a tutto il resto ci pensa Automattic – ad una piattaforma autogestita è già abbastanza complicato per volersi imbarcare in una transizione ancora più radicale. Qualche anno fa sarebbe stato più facile, ma in questo momento è un rischio che non voglio (e che non ho nemmeno il tempo di) correre.

– Fonte: Amador Loureiro su Unsplash.

Senza dimenticare che negli ultimi tre anni ho avuto modo di sperimentare a fondo la stabilità e l’affidabilità di WordPress gestendo un sito (semi)professionale con un carico di lavoro nettamente superiore a quello prodotto da questo blog e con editor multipli, interventi sul forum, un gran numero di utenti registrati, infinite richieste di supporto tecnico nonché (potevano mancare?) innumerevoli attacchi al sito. WordPress si è comportato benissimo, perché buttare via questa esperienza sul campo?

Non nascondo di essere stato attratto a lungo dall’ipotesi “WordPress + Raspberry Pi”, mi intrigava moltissimo l’idea di gestire tutto autonomamente, ma poi ho deciso che il gioco non valeva la candela e ho lasciato perdere.

Ormai è tutto pronto o quasi. Il nome c’è, l’hosting pure, ho anche scelto un tema nuovo e più adatto (spero!) a mostrare i contenuti disponibili, manca solo il tocco finale, la pressione del classico bottone di avvio. Se non ci sono imprevisti ~~luglio~~ settembre dovrebbe essere il momento buono.

Ma niente è per sempre e non è detto che, dopo aver completato questa prima transizione, non decida di farne un’altra più radicale adottando Jekyll, la piattaforma che considero ancora la più vicina al mio spirito di programmatore, seppur solo part-time.

Da melabit a melabit, la serie completa degli articoli

Da melabit a melabit: andare sul cloud

Mon, 24 Jun 2019 06:00:00 +0000

– Fonte: Daniel Falcão su Unsplash.

Il cloud computing è ovunque e ci sono decine di servizi diversi che ci permettono di usare un computer virtuale situato da qualche parte nel mondo come se fosse il computer fisico che abbiamo sulla scrivania. In questo campo i grossi calibri sono Amazon AWS, Google Cloud, Microsoft Azure, Red Hat OpenShift (in rigoroso ordine alfabetico), ma ci sono anche i servizi offerti da fornitori di servizi di hosting come SiteGround, DreamHost o Netsons oppure da provider più orientati al mondo degli sviluppatori come Digital Ocean, Codenvy, Heroku, UpCloud.

Descrivere tutto quello che fanno questi servizi è impossibile, le opzioni e le configurazioni sono tante e tanto diverse che cercare di orientarsi fra le varie possibilità fa letteralmente girare la testa (provate a districarvi nel sito di Amazon AWS e poi ditemi). Ma rimanendo a quello che ci interessa qui, tutti questi servizi mettono a disposizione un computer virtuale ospitato sull’onnipresente cloud dove possiamo installare un sistema operativo (generalmente Linux) e tutte le applicazioni necessarie per realizzare il nostro sito web.

Anche in questo caso valgono considerazioni analoghe a quelle fatte una settimana fa per il Raspberry Pi, con l’ovvia differenza che ora non dobbiamo preoccuparci degli aspetti legati all’hardware, visto che la macchina fisica e l’indirizzo IP sono forniti dal fornitore di servizi di cloud computing (in realtà la nostra macchina fisica non esiste nemmeno, il nostro computer virtuale sul cloud è solo un contenitore Docker ospitato insieme a mille altri su un server di un qualche datacenter).¹ A noi rimarranno comunque alcuni oneri importanti, come ad esempio quello di aggiornare e mantenere in sicurezza il sistema operativo e i pacchetti software che utilizziamo per realizzare il sito web.

Ma oltre a non doverci preoccupare di gestire l’hardware, il vero vantaggio di ospitare il sito su un servizio di cloud computing è quello di essere liberi di utilizzare per il sito il software che preferiamo, senza i vincoli stabiliti dai normali fornitori di servizio di hosting che normalmente danno la possibilità di scegliere solo fra un certo numero di applicazioni predefinite, selezionate fra quelle più popolari.

Se per il nostro sito vogliamo usare un CMS come Wordpress, Drupal, CMS Made Simple o Kirby non fa nessuna differenza, anzi un servizio di hosting tradizionale può essere preferibile perché ci permette di concentrarci sui contenuti, lasciando tutta la gestione del sito al fornitore del servizio di hosting. Ma se vogliamo utilizzare dei CMS meno diffusi come Ghost o Postleaf oppure dei generatori di siti statici come Jekyll, Hugo, Grav o Hexo,² la soluzione cloud ci offre una flessibilità impareggiabile, nettamente maggiore di quella offerta da un normale servizio di hosting.

Tutto questo però ha un prezzo da pagare. Un servizio di hosting decente può costare anche solo qualche decina di euro all’anno, per usufruire di un computer (anche se solo virtuale) nel cloud la cifra da sborsare è nettamente maggiore, dell’ordine di almeno 20-30 euro al mese (con variazioni enormi fra le offerte dei diversi provider).

Prima di scegliere fra hosting e cloud bisognerà quindi valutare realisticamente quello che vogliamo fare con il sito web (un blog personale è ben diverso da un sito di commercio elettronico), tenendo bene in conto dell’impegno richiesto per mantenerlo in forma e delle competenze tecniche necessarie per gestire un servizio mediamente complesso come questo. Trascurare quest’ultimo punto in particolare potrebbe significare dover spendere cifre nettamente maggiori per rimediare ai problemi di configurazione, o peggio di sicurezza, che potrebbero danneggiare gravemente non solo il sito ma anche la nostra immagine. In questo campo i costi non sono solo quelli che si vedono sul cartellino del prezzo.

Da melabit a melabit, la serie completa degli articoli

Il nostro unico problema sarà quello di associare l’indirizzo IP al nome di dominio (ma in genere lo stesso fornitore del nome di dominio ci mette a disposizione gli strumenti per farlo da soli). ↩︎
Dei primi tre ne ho scritto parecchio anche qui, chi vuole può leggere i vecchi articoli su Grav, Hugo e Jekyll. ↩︎

And the winner is...

Wed, 31 Dec 2014 06:00:00 +0000

Riassunto delle puntate precedenti. Wordpress.com è un’ottima piattaforma di blogging, ed ha il grosso vantaggio di liberare l’utente da tutte le preoccupazioni riguardanti la manutenzione del proprio blog. Non è però una piattaforma che si adatta bene al mio modo di lavorare, e ne ho già scritto diffusamente alcuni mesi fa. Però cosa scegliere fra le varie tipologie disponibili: wiki o CMS o piattaforme di blog, siti statici o siti dinamici? Per vari motivi mi sono orientato verso un generatore di siti statici, un programma che prende una serie di file di testo, di immagini e di documenti e li converte in un sito web completo secondo un tema grafico predefinito. In rete ci sono letteralmente decine e decine di generatori di siti statici ed il loro numero cresce molto rapidamente: erano 289 all’inizio di agosto, oggi sono ben 388! Come orientarsi in questo marasma? Basandomi su una lista di caratteristiche irrinunciabili (almeno per me), ne ho provati e scartati parecchi, buon ultimo Hugo, promettente ma rivelatosi alla fine piuttosto immaturo.

In realtà avevo deciso subito. Tutte le prove che ho fatto mi sono servite solo ad esplorare il più possibile il territorio, a provare le alternative e a verificarne i vantaggi e gli svantaggi.

La scelta più ragionevole, date le premesse, era solo una: Jekyll.

Per due ragioni fondamentali: prospettive di sviluppo del codice a medio-lungo termine e disponibilità di documentazione abbondante e di buona qualità. Senza queste due caratteristiche non si va avanti. Tutti gli altri generatori di siti web statici possono anche apparire interessanti, ma impallidiscono se li si confronta a Jekyll su questi due aspetti.

Tanto per fare un esempio: che senso avrebbe avuto scegliere uno dei tanti progetti giocattolo di un singolo programmatore? Può anche essere eccellente, ma quante sono le probabilità che continui ad essere sviluppato fra uno, due, tre anni? Magari fra sei mesi il programmatore si stanca e passa ad altro, non rispondendo più alle richieste di supporto o di correzione degli inevitabili errori. Che si fa, allora? Oppure: come si può cercare di configurare ed estendere il sistema prescelto se non esiste della buona documentazione, se magari l’unico modo per capire cosa fa il programma è analizzarne i sorgenti (auguri)?

Infatti fra i 388 generatori di siti statici elencati oggi da Static Site Generators, ben 171 non sono aggiornati da almeno un anno e 225 da sei mesi. E solo una settantina ha ricevuto un aggiornamento nell’ultimo mese. Insomma, ci sono circa 320 progetti censiti che in realtà sono morti, inutili, da scartare a priori.

I primi due generatori di siti web statici nella lista di StaticGen, Jekyll e il suo derivato Octopress, hanno ricevuto insieme su GitHub più di un terzo delle stelle – cioè delle manifestazioni esplicite di interesse nel progetto – guadagnate da tutti i 67 progetti elencati nel sito.¹ Non sarà che sono ritenuti così interessanti perché sono fatti bene e sono (relativamente) facili da usare e da metterci le mani?

Ora rimane solo da rimboccarsi le maniche, configurare Jekyll e trasportare il blog sulla nuova piattaforma.

Ma prima di allora, auguro a tutti coloro che pazientemente seguono questo blog un 2015 felice e, se possibile, migliore dell’anno che ci stiamo lasciando alle spalle!

Immagino che StaticGen censisca solo i progetti sviluppati attivamente. Probabilmente non è un caso che, se si considerano attivi solo i progetti aggiornati nell’ultimo mese, i numeri di Static Site Generators e di StaticGen concidano. Sarebbe interessante verificare se i progetti sono veramente gli stessi. ↩︎

Hugo, la prova

Sun, 28 Dec 2014 06:00:00 +0000

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)

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.

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. ↩︎