Utiliser Jekyll avec Github Pages

Nathanaël Cherrier -

Cet article fait partie de la série "Utiliser Jekyll avec..." où je vous explique comment utiliser le générateur de site statique Jekyll sur des hébergements de sites statiques gratuit fournit par les leaders de la forge logicielle.

Github Pages : Website for you and your project. Par ce slogan, Github explique l'intérêt principal de son service ; Github Pages permet de présenter un projet et ou un utilisateur.

Trois possibilités s'offrent à vous pour utiliser Jekyll avec Github Pages :

  • mettre vos sources sur la branche master à la racine si vous n'avez que votre site dans le repository.
  • mettre vos sources sur la branche gh-pages si vous avez le code d'un projet dans les autres branches.
  • mettre vos sources sur la branche master dans le dossier /doc de votre projet .

Bonne nouvelle pour nous, GitHub prend en charge nativement Jekyll. C'est à dire qu'il se chargera de build notre site à chaque modification de nos articles.

Ainsi on va pouvoir ne faire que les modifications, ajouts et suppressions d'articles et pousser notre projet Jekyll complet et GitHub fera en sorte de build la nouvelle version du site et de faire pointer la racine du site vers le bon répertoire du repository.

Step by step

On va voir comment mettre en place le site static sur la branche gh-pages mais la méthode est sensiblement la même pour le dossier /doc ou la racine de master.

$ gem install jekyll

On installe Jekyll sur notre machine locale.

$ git clone git@github.com/mindsers/test
$ cd test
$ git checkout --orphan gh-pages 
$ rm -rf *

On récupère le projet et on initialise notre branche gh-pages.

--orphan indique à Git qu'il doit créer cette branche sans tenir compte de l'historique du projet. La branche repart de zéro comme s'il s'agissait d'un deuxième projet complètement différent dans le même repository.

$ jekyll new . 
$ bundle update
$ git add . && git commit -m "install Jekyll website"
$ git push origin gh-pages

On demande a Jekyll de nous faire la structure sur laquelle on va travailler et on pousse le tout sur GitHub.

Avec ce que l'on vient de faire, GitHub Pages est déjà capable de nous générer notre site. Si vous allez sur l'adresse du site static que vous venez de générer (https://username.github.io/projectname/) vous pourrez voir le site par défaut de Jekyll avec un article de bienvenue auto-généré.

Si vous rencontrez des problèmes avec la génération des URL c'est peut-être parce que Jekill pense être à la racine d'un nom de domaine alors qu'il est dans le dossier dédié au projet (rappelez-vous : https://username.github.io/projectname/). Une solution existe, il faut remplacer toute les occurence de site.baseurl par site.github.url.

$ rm -rf _posts/*
$ vim _posts/2016-08-18-coucou-c-est-moi

A partir de là vous allez passer le plus claire de votre temps dans le dossier _posts à écrire et gérer les articles/pages de votre site. Pour mettre en production vous devrez commiter vos modifications et pousser sur le serveur.

Pour ceux qui voudraient customiser le thème voici l'aide de la doc.