webdesign jekyll git cms blog

Creare e mantenere un blog con Jekyll e Git

Come scritto in un post di qualche giorno fa, ho iniziato a usare Jekyll come sistema di gestione del sito.

Gli autori lo descrivono così:

Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server.

È un generatore di siti statici, pensato per i blog. Partendo da templates (in html) e contenuti (html, markdown, textile), mescola il tutto per creare un sito completo da servire per mezzo di un comune webserver.

Mi piace perché lo trovo molto comodo, come nerd e programmatore.

Installazione

Semplicissima: avendo il programma gem basta lanciare

gem install jekyll
gem install rdiscount

Nel caso non fosse disponibile il comando gem lo puoi installare.
In Debian/Ubuntu: sudo apt-get install gem o in Gentoo emerge gem.

Scelta della base

Per partire spediti, è opportuno scegliere una base di partenza su cui sviluppare il sito. Ad esempio, a me piace molto Initializr con il tema Twitter Bootstrap. In realtà Twitter Bootstrap è molto più di un tema, ma un framework per velocizzare lo sviluppo web. Puoi scaricare una base di partenza: vai sul sito http://www.initializr.com scegli "Bootstrap" e scarichi lo zip. Ovviamente, si possono utilizzare altre basi, addirittura del semplicissimo html scritto da noi in pochi minuti.

Setup del sito con GitHub

Già che ci siamo, utilizziamo git, usando GitHub come servizio di hosting.

Se vuoi pubblicare il sito all'indirizzo http://USERNAME.github.com devi creare una repository (dall'account GitHub) chiamata USERNAME.github.com Questo passaggio è opzionale, ma ci dà un ottimo strumento per pubblicare velocemente il sito e tenerne il controllo con Git. Occhio però, bisogna cambiare USERNAME con il nostro nome account.

GITHUB_ACCOUNT=USERNAME
unzip ~/Downloads/initializr-verekia-4.0.zip
mv initializr ${GITHUB_ACCOUNT}.github.com
cd ${GITHUB_ACCOUNT}.github.com
git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:${GITHUB_ACCOUNT}/${GITHUB_ACCOUNT}.github.com.git
git push origin master

Con questa serie di comandi, scarichiamo initializr e lo carichiamo nel nostro account GitHub.

Ora dobbiamo avere un attimo di pazienza, perché GitHub deve creare il sito per noi. In dieci minuti il sito dovrebbe essere disponibile all'indirizzo http://USERNAME.github.com

Setup su webserver

Se hai già un webserver, puoi pubblicare il sito lì. Rispetto all'esempio precedente, tralasciamo tutto quello che riguarda git.

mkdir mywebsite.com
cd mywebsite.com
unzip ~/Downloads/initializr-verekia-4.0.zip
mv initializr _src

Ora creiamo il file _config.yml e aggiungiamo queste informazioni.

markdown: rdiscount
source:      ./_src
destination: ./_site
plugins:     ./_plugins

Diciamo di cercare nella cartella _src i file "sorgenti" del sito, ossia template e contenuti. Di default usa la cartella da cui si lancia il comando jekyll ma preferisco fare così per tenere il sito più ordinato.

Esegui il comando jekyll. Non dovrebbe dare errori, ma dire "Successfully generated site"

Caricando il contenuto di _site via ftp pubblichiamo il sito.

Senza webserver?

Puoi comunque vedere il risultato eseguendo jekyll --server ed andando con il browser all'indirizzo http://localhost:400

Scrivere dei contenuti

Finora che c'è di nuovo? Abbiamo semplicemente caricato dei files statici nel server ftp!

Effettivamente Jekyll fa questo: genera un sito statico. Per generarlo in modo intelligente dobbiamo prima creare dei contenuti e dei templates.

Innanzitutto, bisogna tener presente una cosa importante: tutti i file e le cartelle che iniziano con il trattino basso _ (underscore) non verranno pubblicati. Vale anche per i file che iniziano con il punto, quindi bisogna prestare attenzione ad eventuali .htaccess.

Jekyll si aspetta di trovare una struttura di questo tipo:

.
|-- _config.yml
|-- _src
    |-- _includes
    |-- _layouts
    |   |-- default.html
    |   |-- post.html
    |-- _posts
    |   |-- 2013-04-01-il-mio-primo-post.md
    |   |-- 2013-04-06-foo-bar.markdown
    |-- index.html
|-- _site
Jekyll cerca nella cartella _src perché glielo abbiamo detto nel file di configurazione con l'opzione source: ./_src. Infatti, come configurazione predefinita, lo cercherebbe nella cartella principale.

Templates

Nella cartella _layouts devi mettere i template per i vari tipi di contenuti. Vedremo più avanti come assegnare ai contenuti i rispettivi template. Come configurazione predefinita, i contenuti scritti nella cartella _posts usano il template post.html, tutti gli altri invece usano default.html.

Metti in default.html il codice html che farà da base per tutto il sito: con il menu, eventuali sidebar etc... Per esempio, puoi utilizzare il file index.html che si trova in initialzr oppure scriverlo a manina.

Un semplice default.html può essere questo:

<!DOCTYPE html>
    <head>
        <title>{% if page.title %}Creare e mantenere un blog con Jekyll e Git | {% endif %}Il mio sito</title>
    </head>
    <body>
        {% if page.title %}<h1>Creare e mantenere un blog con Jekyll e Git</h1>{% endif %}
        <div></div>
    </body>
</html>

Liquid template

Puoi vedere che c'è qualcosa di strano: dei pezzi di codice chiusi fra \{\{ \}\} e {% %}. Questo è il markup Liquid, un linguaggio per creare template. A differenza di altri linguaggi, come il php, non viene eseguito nel server, ma trasformato in semplice html quando si lancia il comando jekyll.

In pratica, tutto quello che è messo fra \{\{ \}\} viene sostituito dal contenuto della variabile richiesta. Per esempio, nella pagina che stai leggendo, il codice <h1>Creare e mantenere un blog con Jekyll e Git</h1> è stato sostituito con <h1>Creare e mantenere un blog con Jekyll e Git</h1> Questo viene chiamato Output Markup.

Il Tag Markup, cioè quello contenuto fra {% %} si può usare per gestire la "logica" del template, per esempio generare tabelle, liste o gestire condizioni. È un linguaggio di programmazione, molto semplice. La cosa da ricordare è che viene "eseguito" (ma è meglio dire interpretato) solo quando si genera il sito con jekyll.
Come concetto, assomiglia alle macro di C e C++.

Tutti i template hanno accesso a due variabili oggetto site e page. La variabile site contiene tutti i contenuti e metadati relativi al sito. La variabile page contiene i dati relativi alla pagina che viene creata.

C'è una varibile speciale disponibile in tutti i template: content. Lì dentro si trova il contenuto della pagina (o del post) ed eventualmente anche il codice di un subtemplate (che spiegherò più avanti).

Header YAML

Eventualmente un template può avere un header YAML, dove possiamo definire variabili aggiuntive.

Sub-templates

È possibile che un template erediti il codice da un altro template. In questo caso parliamo di subtemplate. Per esempio, trovo comodo che il template post.html erediti default.html, in questo modo, se modifico l'header o il menu del template default.html non devo andare a modificare anche post.html. Per assegnare un template "padre", dobbiamo aggiungere del codice YAML all'inizio del file. Questo è un estratto del mio post.html:

---
layout: default
---

<article>
  <header class="row">
    <h2 class="span7">Creare e mantenere un blog con Jekyll e Git</h2>
    <ul class="span2 post-info-container">

La cosa in alto fra --- è l'header YAML. Ho specificato di usare il template default, ma avrei anche potuto aggiungere altre variabili. Tutto quello che si trova fra --- non viene renderizzato, ma solo utilizzato come fonte di dati nel processo di rendering.

Posts

L'header YAML si usa anche quando creiamo i post. Ad esempio, il post che stai leggendo, ha questo header:

---
layout: post
title: "Creare e mantenere un blog con Jekyll e Git"
category: webdesign
tags: [jekyll, git, cms, blog]
---

Come scritto in un [post di qualche giorno fa](/2013/04/benvenuto-jekyll.html),
ho iniziato a usare *Jekyll* come sistema di gestione del sito.

Definisco il layout da usare, il titolo, la categoria e i tags. Non è obbligatorio definire questi valori, ma almeno il titolo dovrebbe esserci! La variabile category viene usata anche per generare il permalink, a meno che non si specifichi diversamente. I tags sono scritti come un array. Il titolo è fra virgolette, anche se in questo caso non servirebbe: sono obbligatorie quando nel titolo è presente un carattere :, perché altrimenti Jekyll dà errore.

Il nome del file del post è importante: deve essere nella forma anno-mese-giorno-titolo-separato-da-trattini.estensione
Esempio: 2013-04-03-benvenuto-jekyll.md

Sono supportati vari tipi di formati, ma verranno comunque sempre convertiti in html nella fase di rendering (quando si lancia il comando jekyll).

In questo modo è possibile scrivere un articolo in Markdown, salvarlo nella cartella _posts mettendo la data e il titolo come nome del file, specificando l'estensione .md, e l'articolo verrà pubblicato in html, ovviamente incastonato dentro al template definito in _layouts/post.html.

Wow! Si possono scrivere gli articoli offline! In questo modo possiamo sfruttare uno dei punti forti di Git: il controllo versione offline.

Ma dove sono disponibili gli articoli? Dipende... se non hai specificato diversamente nel file _config.yml, allora l'articolo creato in _posts/2013-04-03-benvenuto-jekyll.md che ha come category "webdesign" viene pubblicato in /webdesign/2013/04/03/benvenuto-jekyll.html Ecco a cosa serviva la variabile category! Anzi, se ne possono specificare anche più di una, se la chiamiamo categories e lo scriviamo come array (come nell'esempio sopra abbiamo specificato i tags.

Ovviamente, abbiamo la libertà di scegliere altri pattern per generare i permalinks: sia di predefiniti che di personalizzati.

Nella tabella riporto gli esempi dal wiki ufficiale di Jekyll:

ImpostazioneRisultato
permalink: date/2009/04/29/slap-chop.html
permalink: pretty/2009/04/29/slap-chop/index.html
permalink: /:month-:day-:year/:title.html/04-29-2009/slap-chop.html
permalink: /blog/:year/:month/:day/:title/blog/2009/04/29/slap-chop/index.html

Mentre date, pretty e none sono definiti, gli altri sono dei pattern personalizzati. Si possono comporre usando queste variabili:

VariabileDescrizione
yearL'anno, come scritto nel nome del file
monthIl mese, come scritto nel nome del file
dayIl giorno, come scritto nel nome del file
titleTitolo, come scritto nel nome del file
categoriesLe categorie specificate per il post. Jekyll riconosce automaticamente le doppie barre negli URL, così se non ci sono categorie presenti, semplicemente la ignora
i_monthIl mese, ma senza lo zero davanti
i_dayIl giorno, ma senza lo zero davanti

Includes

Può capitare che ci siano degli elementi che vanno ripetuti spesso. Oppure vogliamo mantenere un certo ordine nei template, spezzettando il codice in varie parti. Gli includes servono a questo: possiamo dire a Jekyll di inserire del codice preso da un file esterno e metterlo al posto di uno speciale tag. Tutti i file da includere vanno messi nella cartella _includes. Anche in questo caso, possono essere di fari formati, alla fine verranno convertiti in html prima di essere inseririti.

Per esempio, se vogliamo includere il contenuto del file sidebar.html che si trova nella cartella _includes, basta inserire questo "segnaposto" nel posto in cui lo vogliamo: {% raw %}{% include sidebar.html %}{% endraw %}

Gli include possono essere richiamati sia nei templates, sia nei post e nelle pagine.

Pagine

Cosa sarebbe un sito senza pagine? Prima abbiamo parlato di post, che è un contenuto speciale, gestito in maniera diversa dalle pagine (per esempio con i permalink).

Le pagine sono semplicemente pagine: creiamo un file in uno dei formati supportati (html, markdown o textile), Jekyll lo convertirà in html, lo inserirà nel template specificato e lo pubblicherà nello stesso percorso in cui lo abbiamo creato. Se per esempio abbiamo creato il file _src/projects/foobar.md, allora lo troverai pubblicato in http://www.example.com/projects/foobar.html.

Anche le pagine hanno bisogno dell'header YAML, dove specificare il titolo e il layout da usare.

Allora sei pronto? Ora hai le basi per buttar su un bel sito con Jekyll

Le possibilità sono infinite, senza contare dei numerosi plugins disponibili. Divertiti!

Ti è piaciuto l'articolo? Condividilo! Commentalo!

comments powered by Disqus