Da melabit a melabit: Jekyll, installazione e configurazione di base

Tue, 11 Feb 2025 06:00:00 +0000

Questo articolo non vuole essere una guida dettagliata alla installazione e configurazione di Jekyll; per quello ci sono le ottime guide riportate più sotto.¹

L’articolo è invece una raccolta commentata delle note che ho preso mentre sviluppavo melabit.com/posts/it, e sono il risultato di giorni e giorni di prove ed errori, di cambi di direzione, di letture alla ricerca del comando giusto. A me le note servivano per ricordare quello che avevo fatto e come avevo risolto i problemi che si presentavano di volta in volta. A voi potrebbero essere utili per fare tutto più in fretta e senza intoppi.

Installazione di Jekyll

Per fare delle prove con Jekyll non c’è niente di meglio che usare una macchina virtuale, magari con una versione server di Linux che carica poco il sistema principale. Una buona alternativa è un server cloud virtuale, anche economico, come UpCloud, Google Compute Engine, Amazon EC2 o similari. Per lavorare sul serio, invece, è molto più comodo e veloce usare una macchina reale, tanto più che seguendo queste istruzioni il rischio di fare danni è nullo o quasi. Io per fortuna avevo a disposizione un vecchio Mac, che mi ha permesso di provare e riprovare sapendo che, in caso di problemi, avrei potuto resettarlo facilmente.

La guida migliore per l’installazione di Jekyll è senza dubbio quella ufficiale, con istruzioni specifiche per i sistemi operativi più diffusi.

La guida per macOS è fatta bene, ma l’installazione richiede Homebrew e un buon numero di passaggi da eseguire con attenzione. Su Linux l’installazione è molto più facile, mentre su Windows la cosa migliora da fare è installare il Windows Subsystem for Linux (WSL) e poi lavorare di fatto in un ambiente Linux.²

Un dettaglio importante che manca nelle istruzioni per macOS – ma che invece è presente in quelle per Ubuntu, FreeBSD e gli altri Linux – è che, prima di eseguire il comando finale gem install jekyll (ma volendo anche prima di iniziare ad installare Jekyll), è bene aggiungere queste righe al file ~/.bashrc o ~/.zshrc (a seconda della shell usata),

#--- Install Ruby gems in the user account, e.g. in ~/.gems ---
export GEM_HOME="$HOME/.gems"
export PATH="$HOME/.gems/bin:$PATH"
#--- end ---

ed eseguire source ~/.bashrc o source ~/.zshrc per attivare le nuove variabili di ambiente (io sono rozzo e mi limito a chiudere il Terminale e a riaprirlo subito dopo).

A cosa servono quelle righe? Ad istruire il gestore dei pacchetti di Ruby, RubyGems, ad installare tutte le sue gemme,³ fra cui c’è anche Jekyll, nell’account dell’utente invece che a livello di sistema. Una cosa buona e giusta per separare l’installazione nativa di Ruby all’interno del sistema operativo da tutto ciò che installiamo noi, permettendoci di correggere gli (inevitabili) errori senza correre il rischio di intaccare le funzioni di base del sistema operativo.

A questo punto, è possibile eseguire l’installazione vera e propria di Jekyll,

$ gem install jekyll

seguita subito dopo da un’altra gemma molto utile, Bundler,

$ gem install bundler

che inspiegabilmente è stata completamente dimenticata nelle istruzioni per macOS .

Per istruire anche bundler ad installare tutto nell’account dell’utente, bisogna eseguire

$ bundle config set --local path $GEM_HOME

Infine, se stiamo usando una macchina virtuale o un server cloud e il nostro sistema operativo principale è macOS, possiamo installare anche questa gemma,

$ gem install rmate

che ci permetterà di usare TextMate, che secondo me è nel complesso il miglior editor per macOS che ci sia in circolazione, per editare i file su cui si deve mettere le mani, invece di dover usare nano, vim o emacs direttamente sulla macchina virtuale/cloud (che, avendo installata una versione server di Linux, non ha una interfaccia grafica).⁴

Il primo sito in Jekyll

Alla fine del processo di installazione di Jekyll, tutte le guide suggeriscono di creare un nuovo sito con

$ jekyll new my-new-blog
Running bundle install in [...]/my-new-blog... 
  Bundler: Resolving dependencies...
  Bundler: Bundle complete! 7 Gemfile dependencies, 30 gems now installed.
  Bundler: Use `bundle info [gemname]` to see where a bundled gem is installed.
New jekyll site installed in [...]/my-new-blog.

che crea una nuova cartella my-new-blog nella cartella corrente (i puntini fra parentesi quadre indicano la parte di percorso che dipende dal sistema operativo). Spostandosi nella nuova cartella e attivando il web server integrato in Jekyll,

$ cd  my-new-blog
$ bundle exec jekyll serve --host=0.0.0.0

potremo vedere il nostro nuovo sito all’URL http://localhost:4000 se stiamo usando una macchina reale. Se invece stiamo usando una macchina virtuale o un server cloud, dovremo puntare il browser all’URL pubblico fornitoci dalla macchina virtuale (o server cloud), utilizzando sempre la porta 4000.

Niente da dire, questa procedura è utile per verificare che tutto funzioni, e poi Minima, il tema di default, è davvero molto pulito ed elegante. Se Minima vi basta, potete chiuderla qui, sarà sufficiente dare un titolo al sito e aggiungere i contenuti e potrete partire immediatamente con il vostro nuovo blog in Jekyll.

Ma questa procedura ci dà anche una idea molto pallida di cosa si possa fare davvero con Jekyll. Perché, e questo è un limite non da poco, le funzioni di Jekyll sono strettamente integrate con i suoi temi grafici.

Jekyll e i temi grafici

Minima è un esempio di tema gem-based, installato al di fuori della cartella del sito e che, proprio per il fatto di separare nettamente i contenuti del sito dal suo aspetto grafico, può essere in teoria facilmente sostituito con un altro tema a gemma, come quello mostrato qui sotto.

Ma i temi di questo tipo sono pochi, in genere sono piuttosto minimali e, per la loro stessa natura, è più laborioso modificarli o aggiungere nuove funzioni. E quel che è peggio, spesso sono fatti per versioni ormai obsolete di Jekyll e non funzionano nelle ultime versioni.⁵

La stragrande maggioranza dei temi per Jekyll arriva invece in un formato che integra in un’unica cartella sia i contenuti che la grafica. Una cosa molto comoda quando si trova il tema giusto, ma che rende molto più complicato cambiare tema a posteriori.

Installare la maggioranza dei temi per Jekyll significa di fatto installare tutto il sito che lo contiene, dandosi poi da fare per sostituire i post e le immagini preconfezionate con i nostri post e con le nostre immagini. Di conseguenza, è preferibile prima scegliere un tema che ci piaccia e che supporti almeno una parte di quello che ci aspettiamo dal sito, e solo dopo iniziare ad estenderne le funzioni nel modo desiderato.

Ma questo sarà l’argomento della prossima puntata.

E se Jekyll non ci piace più?

Allora dobbiamo disinstallare tutto. Il modo moderno per farlo è usare questo comando,

$ gem uninstall --all --ignore-dependencies --executables --verbose

oppure, per chi ama la compattezza,

$ gem uninstall -aIxV

dove lo switch --all segnala di disinstallare tutte le gemme, mentre --ignore-dependencies permette di evitare di bloccare il processo di disinstallazione quando si disinstalla una gemma richiesta da un’altra gemma. Il terzo switch --executable serve per disinstallare gli eseguibili senza richiedere ogni volta una conferma. Infine --verbose è utile per farci spiegare per filo e per segno quello che sta succedendo.

Se avete seguito il consiglio iniziale di installare tutto nell’account utente non vi serviranno i privilegi di amministratore. Altrimenti avrete fatto male e per punizione dovrete anteporre sudo al comando di installazione.

Una volta disinstallate tutte le gemme, si potrebbe anche disinstallare ruby e i pacchetti accessori, usando Homebrew per macOS oppure il gestore dei specifico per la distribuzione Linux usata. Ma con i grandi dischi attuali, vale la pena darsi tanto da fare solo per risparmiare qualche decina di MB?

Alla prossima

L’articolo è già troppo lungo ed è meglio chiuderlo qui. Il prossimo articolo servirà per entrare nel vivo dello sviluppo di un sito con Jekyll. A presto!