Introduzione a Jekyll

Ovvero, di trasformazioni e siti web


Lo strano caso del dottor Jekyll e di mister Hyde è un libro che parla di una trasformazione: quella del protagonista, il dottor Jekyll, in mister Hyde, suo alter ego, nato grazie ad una pozione inventata dallo stesso dottore allo scopo di portare alla luce i lati più nascosti della psiche umana.

A dire il vero in questo articolo non ci addentreremo nelle vicende del romanzo, ne parleremo di letteratura. Parleremo invece di Jekyll, uno static site generator che, come suggerisce il nome, è un sistema che si occupa di generare un sito web, a partire da una serie di template e contenuti. Come potete ben immaginare, con il romanzo da cui trae ispirazione per il nome, il nostro Jekyll ha in comune principalmente solo una cosa: il concetto di trasformazione.

Cosa fa Jekyll

Quando dobbiamo portare dei contenuti on-line, la soluzione relativa all’utilizzo di un CMS, come ad esempio Wordpress, non è sempre la scelta più indicata. Per funzionare, un CMS necessita di una gestione che, alle volte, può risultare troppo complessa per il fine del progetto che si sta realizzando. Database, web-server, il CMS stesso, sono tutte componenti che vanno gestite e mantenute nel tempo.

Ma sono sempre necessarie?

Spesso tutto quello che serve al nostro progetto sono una manciata di pagine, magari indicanti i servizi, i prodotti, le marche che noi, o i nostri clienti, offriamo. A queste aggiungiamo una pagina di contatti e qualche informazioni sull’azienda o noi stessi. Certo, di contro un sito statico può essere comunque ostico da mantenere. Cambiare una voce di menu potrebbe richiedere diverse modifiche in diversi file, per non parlare poi di eventuali script, librerie o quant’altro. Ed è qui che si posiziona uno static site generator.

Attraverso Jekyll, possiamo creare dei template di pagina, che a loro volta possono includere porzioni esterne di codice HTML o essere inclusi in altri template. Tramite alcune opzioni di configurazione, andremo poi a generare una serie di pagine statiche, andando a prelevare i diversi template che avremo indicato e inserendovi i nostri contenuti, scritti con sintassi markdown, textile o in HTML stesso. In pratica con Jekyll possiamo avere la flessibilità di un sito dinamico, generandolo manualmente ogni volta che aggiungiamo un contenuto o apportiamo una modifica, ma senza la necessità di tutta la complessa struttura che un sito dinamico in genere richiede.


Primi passi

Come prima cosa dobbiamo installare Jekyll, operazione piuttosto semplice. Essendo scritto in Ruby, Jekyll necessita di quest’ultimo e di RubyGem installati sul nostro computer (non essendo oggetto dell’articolo non ne tratteremo l’installazione, ma potete dare un’occhiata alla documentazione ufficiale). Se avete tutto già installato, o dopo l’installazione, da terminale basta digitare:

$ gem install jekyll

Questa operazione dura pochi secondi e, una volta terminata, ci permetterà di iniziare ad usare subito Jekyll. Possiamo quindi creare un nuovo sito partendo da zero tramite il seguente comando:

$ jekyll new <nome-sito>

Grazie a questo comando verrà creata una directory <nome-sito> contenente il nostro nuovo sito. A questo punto possiamo già iniziare a visualizzarlo in una finestra del browser, dopo aver digitato il comando:

$ cd <nome-sito>
$ jekyll serve

Dirigendoci all’indirizzo 0.0.0.0:4000 con il nostro browser potremo visualizzare il nuovo sito, che avrà un aspetto simile a quello dell’immagine qui sotto.

Il nostro nuovo sito. Un po’ spoglio, ma funzionale.

Diamo uno sguardo sotto il cofano

Il nostro sito appena nato avrà una struttura simile alla seguente:

/
├── _config.yml
├── _includes
| ├── footer.html
| ├── header.html
| └── script.html
├── _layouts
| ├── default.html
| └── post.html
├── _posts
| ├── 2015–03–01-hello-world.md
| ├── 2015-03-02-first-pst.md
| └── 2015–03–03-second-post.md
├── _sass
├── _site
├── css
| └── main.scss
├── about.md
└── index.html

Come prima cosa notiamo che ci sono due tipi di directory. Quelle precedute da un underscore, o trattino basso, sono le directory che, al momento della generazione del sito, verranno processate da Jekyll e non saranno incluse nella struttura del sito risultante.

Per capire meglio come è strutturato il sito, vediamo quali sono i principali elementi che lo compongono:

  • _config.yml: è il cuore della configurazione di Jekyll. All’interno del file possiamo trovare tutte le impostazioni che vengono lette da Jekyll all’avvio. Si tratta di un file con sintassi YAML, che elenca una serie di coppie chiave: valore. Il file è molto semplice e potete approfondire le diverse opzioni di configurazione nella documentazione ufficiale.
  • _includes: all’interno di questa directory, trovano spazio le porzioni di HTML che vogliamo includere in più template di pagina. Ad esempio il footer o il menu di navigazione di un sito. In pratica si tratta di semplici file HTML, contenenti porzioni di codice ripetute in più punti del sito.
  • _layouts: qui dentro possiamo trovare i layouts, ovvero i template veri e propri che vogliamo utilizzare all’interno del nostro sito. I layout possono far riferimento ad altri layout e possono includere porzioni di codice direttamente dalla directory _includes.
  • _posts: in questa directory trovano posto i file di testo, con sintassi Markdown, Textile o HTML, relativi agli articoli di un eventuale blog che vogliamo includere all’interno del progetto.
  • _sass: la directory che contiene i nostri fogli di stile, scritti in Sass, il pre-processor CSS utilizzato in Jekyll per generare i fogli di stile.
  • _site: si tratta della directory di default, in cui possiamo trovare il sito statico generato da Jekyll, le sotto-directory e tutti i file relativi.
  • css: le directory prive di underscore, verranno mantenute tali e quali e saranno presenti all’interno della struttura del sito generato da Jekyll, con tutti i loro contenuti. I file Sass, Markdown e Textile, verranno comunque processati e trasformati negli equivalenti CSS e HTML.
  • about.md: questa è una pagina statica di esempio. Il contenuto è scritto in Markdown e viene inserito all’interno del template default.html visto all’interno della directory layout.
  • index.html: l’home page del sito. In fase di costruzione il suo ruolo può essere quello di richiamare i post dalla cartella _posts, un layout specifico o inserire direttamente dei contenuti in pagina. Nel caso del nostro sito di base vengono richiamati i post e il template di default.

Più opzioni con il YAML Front Matter

Con il Front Matter si realizzano molte delle principali funzionalità di Jekyll. Quasi tutti i file all’interno del nostro progetto possono essere dotati di Front Matter, il quale permette di definire delle variabili ed ulteriori opzioni di configurazione, relativamente al file nel quale è inserito. Ecco un esempio:

---
layout: default
title: Hello World!
---

Il Front Matter viene posto sempre in cima al file, prima di ogni altra cosa e non è altro che una serie di coppie chiave: valore con sintassi YAML. Grazie ad esso possiamo impostare alcune opzioni di configurazione. Nell’esempio qui sopra la variabile layout è impostata su default. Grazie a questa impostazione il file che contiene questo Front Matter, ad esempio un post, richiamerà il template default.html (l’estensione si può omettere) dalla cartella layout.

Oltre ad impostare opzioni di configurazione, il Front Matter permette di creare variabili personalizzate, com ad esempio title qui sopra. Queste variabili sono accessibili all’interno del template come mostrato di seguito.

<h2>{{ page.title }}</h2>

Va da se che tramite questa semplice possibilità, è possibile configurare all’interno delle nostre pagine diverse cose, come ad esempio classi CSS personalizzate.

Potete trovare ulteriori informazioni sulle possibilità di configurazione del Front Matter sulla documentazione ufficiale.


Mano ai template con Liquid

I template di Jekyll si basano su Liquid, sistema sviluppato da Shopify e che permette, con grande semplicità, di sviluppare i propri template con poche righe di codice.

Il sistema si basa su due tipologie principali di contenuti: i tags e gli object.

Tags

I tags permettono di inserire dei costrutti logici all’interno delle pagine di Jekyll. Ad esempio è possibile utilizzarli per includere porzioni di codice HTML direttamente dalla cartella _include, inserendolo all’interno del nostro template dove vogliamo che il componente appaia:

<body>
<h2>Titolo</h2>
<p>Il mio paragrafo</p>
  {% include footer.html %} 
</body>

Un altro esempio è relativo alla pubblicazione, attraverso un ciclo, dei post presenti nella cartella _posts.

<ul>
{% for post in site.posts %}
<li>
<h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
</li>
{% endfor %}
</ul>

Objects

Nel corso di questo articolo abbiamo già incontrato gli object. Grazie ad essi possiamo inserire nel nostro template del contenuto, preso da parametri di configurazione, variabili globali personalizzate o varibili presonalizzate sul singolo file. Ad esempio all’interno di un template possiamo accedere a variabili locali in questo modo:

---
title: Hello World
---
<div class="post">
  <h2>{{ page.title }}</h2>
</div> 

Possiamo anche accedere a variabili globali riguardanti il sito, come ad esempio la data:

<div>
  {{ site.date }}
</div>

Maggiori dettagli riguardo le variabili e il sistema di template possono essere trovate, come di consueto, sulla documentazione ufficiale.

Concludendo

In questo articolo abbiamo solo grattato la superficie di Jekyll. Questo sistema è davvero molto potente e versatile e in combinazione con librerie Javascript e servizi di terze parti, è in grado di sostenere progetti anche di una discreta complessità, a fronte di costi minimi.

Trattandosi essenzialmente di file statici, è possibile trovare diverse soluzioni a costi nulli o quasi che possono permetterci di essere online con il nostro progetto anche con a disposizione budget relativamente modesti.