jekyll est un générateur de site Web statique, en Anglais « static site generator » ou SSG, qui permet de créer très rapidement un site à partir d’un contenu en Markdown ou en HTML.

Le fait qu’il soit le SSG utilisé par les pages GitHub le rend encore plus populaire, car cela permet de mettre en ligne un site en quelques minutes seulement, avec la possibilité éventuelle d’utiliser son propre nom de domaine.

1. Installer Jekyll

Pour installer Jekyll sur Debian ou Ubuntu, on commence par installer les dépendances nécessaires:

$ sudo apt-get install build-essential zlib1g-dev

Le paquet build-essential installe notamment gcc et make.

Puis on installe Ruby:

$ sudo apt-get install ruby-full

On configure le répertoire d’installation des paquets Ruby:

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Et enfin on installe Jekyll:

$ gem install bundler jekyll

Ce qui prend un peu de temps.

On a alors les commandes bundle et jekyll dans le PATH.

2. Premier site avec Jekyll

On a commencer par créer un nouveau répertoire et se placer dedans:

$ mkdir jekyll_site
$ cd jekyll_site/

Ensuite on va créer un Gemfile, qui est en quelque sorte l’équivalent d’un Makefile pour Ruby.

On obtient le résultat suivant:

vagrant@ubuntu-focal:~/jekyll_site$ bundle init
Writing new Gemfile to /home/vagrant/jekyll_site/Gemfile
vagrant@ubuntu-focal:~/jekyll_site$ cat Gemfile 
# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

Dans ce Gemfile, on va ajouter le contenu suivant:

gem "jekyll"

Puis lancer la commande:

$ bundle install

ou plus simplement:

$ bundle

Cela aura pour effet de créer un fichier Gemfile.lock avec toutes les caractéristiques des dépendances de notre projet ainsi que de leurs versions. Cela rappelle évidemment le fichier package-lock.json de npm.

Maintenant, on va ajouter un fichier index.html dans notre répertoire:

$ cat index.html 
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Home</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>

Et on va démarrer le serveur jekyll:

$ bundle exec jekyll serve --host 0.0.0.0
Configuration file: none
            Source: /home/vagrant/jekyll_site
       Destination: /home/vagrant/jekyll_site/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.01 seconds.
 Auto-regeneration: enabled for '/home/vagrant/jekyll_site'
    Server address: http://0.0.0.0:4000
  Server running... press ctrl-c to stop.

On utilise pour cela la commande bundle pour que la version de jekyll utilisée ainsi que celle des dépendances soient bien celles décrites dans les fichiers Gemfile et Gemfile.lock et ne dépendent pas de l’environnement de la machine.

Voilà, le serveur sert notre page HTML !

J’utilise ici --host 0.0.0.0 pour que le site jekyll soit accessible en dehors de la machine virtuelle sur laquelle je travaille. Sur une machine locale, ce n’est pas nécessaire.

Un paramètre très utile lorsqu’on démarre jekyll est --livereload afin de pouvoir éditer vos pages HTML et Markdown et de voir instantanément le résultat.

Attention: --livereload ne prend pas en compte un changement dans le fichier _config.yml.

3. Utiliser liquid et Front Matter

liquid est un langage de template développé par Shopify et rendu opensource par la suite.

Il permet notamment de définir des variables dans les pages, d’ajouter de la logique: if, for, case … et d’utiliser des filtres, par exemple mettre un texte en majuscule.

La définition des variables se fait avec une entête YAML en début de page, par exemple:

---
title: Home
number: 1
---

qui se nomme entête Front Matter.

Cette entête signale à jekyll qu’il doit parser les éventuelles syntaxes liquid dans les pages:

$ cat index.html 
---
title: Home
number: 1
---

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{page.title}}</title>
  </head>
  <body>
    <h1>Hello World!</h1>
    <p>The page number is: {{page.number}}</p>
    <p>The page URL is: {{page.url}}</p>
  </body>
</html>

L’accès aux variables de la page se fait via la syntaxe {{page.variable}}.

Vous noterez que j’ai défini la variable number mais que la variable url est prédéfinie.

Il y en a d’autres comme:

{{page.title}}
{{page.content}}
{{page.excerpt}}

On peut aussi utiliser les variables au niveau du site, certaines sont prédéfinies comme:

{{site.url}}
{{site.time}}

Pour en définir d’autres, on devra le faire dans le fichier _config.yml du site Jekyll.

Plus de détails sur les variables avec Jekyll sur la page correspondante de la documentation.

Le résultat de notre page est le suivant:

Hello World!

The page number is: 1

The page URL is: /

4. Les layouts et inclusions

Les « layouts » sont des templates de pages qui permettent de mettre en commun une partie du contenu des pages, comme par exemple les liens vers les réseaux sociaux en bas de page, de telle sorte que le contenu des pages HTML s’en trouve allégé:

$ cat index.html
---
layout: default
title: Home
---
<h1>Hello World!</h1>

Le layout correspondant étant:

$ cat _layouts/default.html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

Dans la page finale, le {{ content }} étant remplacé par:

<h1>Hello World!</h1>

Toujours afin de mettre en commun certaines parties de nos pages, on peut aussi utiliser le mot clé include du langage de template liquid.

On peut donc modifier le layout précédent:

$ cat _layouts/default.html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

Avec:

$ cat _includes/navigation.html
<nav>
  <a href="/">Home</a>
  <a href="/about.html">About</a>
</nav>

pour inclure des liens de navigation sur chaque page.

5. La suite: Fichiers de données, thèmes, GitHub Pages …

Dans ce billet, nous avons vu comment installer jekyll, quelques notions concernant l’écosystème Ruby ainsi que les bases de l’utilisation de jekyll.

Il nous reste encore à découvrir de nombreux concepts de Jekyll comme les fichiers de données, intégrer des billets de blog ou la possibilité d’utiliser des thèmes et/ou des plugins ainsi que de publier notre site avec les pages GitHub.

D’autres billets seront donc à suivre !

Catégorie : Web

Premiers pas avec jekyll