Démarrer des Collections dans Jekyll

Inspiration & remerciements à Taylor Jones pour son post de référence m’ayant sérieusement aidé pour capter le fonctionnement des collections dans Jekyll. Le code de l’exemple d’une collection d’albums de musique est posé sur github.

Comment Démarrer des Collections dans Jekyll 2.xx

Migration WordPress vers Jekyll : un an déjà…

Fin 2013, je prenais la décision de migrer de WordPress vers une motorisation Jekyll pour m’essayer à la pose de quelques premières briques de construction indieweb.

Dans cet article je vous donnerai un aperçu des raisons pour lesquelles je compte poursuivre l’apprentissage indieweb sur Jekyll en 2015, comment vous pouvez aussi vous y mettre rapidement et conclurai par quelques astuces pour construire des collections Jekyll. Astuces intégralement inspirées de l’excellent post de Taylor Jones.

Pour une première initiation à Jekyll et si vous êtes un geek un peu averti, aidez-vous de la documentation. Si vous êtes blogueur sur WordPress et souhaitez construire un premier site ce weekend, je ne peux que vous recommander de faire vos armes sur l’excellent tutoriel de jekyll-now construit cet été par Barry Clarke :

My side project Jekyll Now hit 2k forks today! 2,000 @jekyllrb blogs created without touching the command line! 🎊 https://t.co/6ruGxem3Ie

— Barry Clark (@BazNYC) 19 Décembre 2014

Pourquoi Jekyll est Génial

Les points forts de Jekyll qui me confortent : une belle communauté de hackers, un plan de route qui évoluera vers la simplicité, un langage de templates assimilable et une architecture de templates accessible pour y greffer quelques premiers blocs de construction indieweb et escalader une ou deux marches sur l’IndieMark.

Rappelons que Jekyll est simple et livré en sortie de boîte avec des fonctionnalités de blog carnet web. Il analyse le Markdown, intègre nativement une mise en forme du code, produit des fichiers statiques et la production peut être hébergée gratuitement sur les Pages GitHub.

À des fins de révision, je vous propose dans la section à suivre de revoir le démarrage d’un site avec Jekyll. Si vous avez déjà un site Jekyll, ignorez cette section et allez directement sur l’implémentation des collections.

Installer Rapidement Jekyll

Pour installer Jekyll, il y a deux exigences : - installer Ruby et RubyGems sur votre machine, - et ne pas être effrayé de mettre les mains dans le terminal.

Le dernier problème connu que vous pourriez rencontrer si vous faites tourner Jekyll sur Mac OSX serait de ne pas avoir mis à jour vos outils de ligne de commande X-Code. Vous les trouverez ici, dans la section téléchargements du portail des développeurs Apple. Vous aurez besoin d’un ID Apple pour accéder aux téléchargements.

Ces pré-requis étant posés, vous n’êtes plus qu’à 4 lignes à saisir dans le terminal pour faire tourner votre premier site web Jekyll.

Ouvrez votre fenêtre de terminal et lancez ces 4 commandes :

~ $ gem install jekyll
~ $ jekyll new testJekyll
~ $ cd testJekyll
~/testJekyll $ jekyll serve

Dans l’ordre, voici ce qui se passe ici :

1. Installation de Jekyll sur votre système
2. Création d’un nouveau répertoire plein de fichiers Jekyll passe-partout à personnaliser
   
3. Modification du répertoire de travail vers le testJekyll fraîchement créé
4. Lancement d’un serveur pour servir ces fichiers en local sur localhost:4000

Parmi l’ensemble des fichiers de structure placés dans le répertoire de travail, le premier fichier essentiel à paramétrer c’est config.yml.

config.yml est le fichier de configuration global de Jekyll. Dans ce fichier, vous pouvez spécifier : - les options de construction, - les options du serveur, - la déclaration des collections, - et régler des métadonnées valables sur tout le site en utilisant le front-matter YAML.

La capacité d’utiliser le front matter de YAML est une fonctionnalité très appréciable de Jekyll. Le terme « front-matter » provient en fait des pages liminaires dans le monde de l’édition. Dans les livres, les pages liminaires sont placées au début du livre pour contenir toutes les métadonnées associées à un livre : titre, auteur, éditeur, table des matières, et ainsi de suite. De même, nous utiliserons le front-matter en format YAML pour déclarer des métadonnées valables sur tout le site à l’intérieur du fichier config.yml et des métadonnées spécifiques aux pages dans les fichiers .markdown. Ces métadonnées peuvent ensuite être référencées comme des variables utilisant le moteur de gabarit Liquid utilisé par Jekyll.

C’est Quoi des Collections ?

Les Collections dans Jekyll sont des ensembles de documents qui ont les mêmes fonctionnalités que les posts. Les collections ont la puissance des posts, mais vous les tenez à portée de main. Une chose à noter à cette heure : à la différence des posts, les collections ne supportent pas la pagination, bien que les collections de documents puissent être publiées individuellement sous forme de pages. Elles peuvent être aussi restituées sous forme de listes en utilisant le moteur de gabarits Liquid intégré dans Jekyll. Les collections disposent de leur propre espace nom sur tout le site avec des métadonnées et des propriétés personnalisables.

Les Collections fonctionnent sur le principe du moteur Jekyll qui lira votre collection définie dans le fichier config.yml lors de la construction du site. Jekyll ajoute le document de la collection frontmatter YAML aux variables de gabarits globales du site, et restitue –si vous le souhaitez— chaque document dans sa propre page. Les collections peuvent s’utiliser pour n’importe quel type d’ensemble de documents que vous souhaiteriez organiser sur votre site.

De bons exemples de collections peuvent être les projets sur lesquels vous avez travaillés, la publication de la liste des organisateurs d’un événement, la constitution d’une bibliothèque d’albums « women in rock », la documentation d’une API, ou plus simplement une liste de petites notes sur vos données de santé ou toute autre thématique-clé, etc.

Pour démarrer sur un premier exemple, nous utiliserons une collection d’albums de musique.

Configurer les Collections

La première étape pour configurer les collections est d’indiquer à Jekyll que vous avez une collection dans le fichier \_config.yml.

    collections:
      - music

Maintenant, ajoutez un dossier à la racine du répertoire de votre projet avec le même nom que la collection. Assurez-vous de préfixer le dossier avec un souligné « _ ». Ajoutez quelques documents en format markdown dans le dossier de la collection.

Si vous choisissez de faire ainsi, vous pouvez spécifier de restituer une page pour chaque document en modifiant le fichier _config.yml comme suit.

    collections:
      music:
        output: true

Les Collections en Action

Maintenant que la collection est définie et une fois le contenu ajouté à la collection, ces collections peuvent être incluses sur n’importe quelle page dans le site Jekyll. Par exemple, les ajouts les plus récents de votre collection peuvent être affichés sur votre page d’accueil en utilisant la syntaxe Liquid. Tout front-matter YAML personnalisé déclaré dans chaque document peut aussi permettre de faire figurer le contenu.

{% for album in site.music limit:3 %}
<li>
<img src="{{ album.thumbnail-path }}" alt="{{ album.title }}"/>
<a href="{{ album.url }}">{{ album.title }}</a>
<p>{{ album.short-description }}</p>
</li>
{% endfor %}

Ceci fournit un moyen génial pour afficher des images, titres, etc. en rapport dans une liste de documents. Vous pouvez utiliser l’attribut intégré url pour faire un lien vers une page restituée de document.

Pour conclure

Jekyll est une motorisation pratique pour construire des petits sites statiques. Cela vaut la peine de l’envisager pour tous les sites web ayant besoin d’un backend robuste - pouvant aussi intégrer de la manipulation de data et de la recherche. Un point à garder en tête pour votre prochain projet.

Ceci étant dit, l’installation de Jekyll est rapide et dispose de quelques options configurables qui vous permettent de spécifier comment vous aimeriez faire fonctionner le site. Les pré-requis sont minimes et la fonctionnalité d’installation rapide vous donne un premier site tout à fait fonctionnel.

La fonctionnalité collection de Jekyll a une déclaration de configuration directe tout comme quelques attributs personnalisables, vous permettant de restituer vos documents à l’intérieur de leurs propres pages.

En utilisant les paramètres de configuration et le front-matter YAML, vous pourrez afficher vos documents en différents endroits du site. Jekyll excelle dans le domaine pour lequel il a été conçu, et la fonctionnalité des collections ouvre des portes pour tirer profit de sites avec plus de contenus.