Modélisation de contenu avec Jekyll

Ce n'est pas exactement un nouveau sujet, mais dernièrement, j'ai eu des raisons de revoir la compétence de modélisation de contenu dans le travail de mon équipe. Notre expérience a atteint un point où les limites de notre pratique commencent à devenir claires. Notre problème le plus courant est que les gens ont tendance à se lier eux-mêmes et leurs modèles mentaux à une plate-forme choisie et à ses conventions.

Au lieu d'enseigner aux gens comment modéliser du contenu, nous finissons par leur apprendre à modéliser du contenu dans Drupal ou à modéliser du contenu dans WordPress. Mais je préférerais que nous l'abordions en nous concentrant sur les meilleurs intérêts des utilisateurs, quelle que soit la plate -forme sur laquelle ledit contenu se retrouvera.

Lectures complémentaires sur SmashingMag :

• Créer un blog avec des pages Jekyll et GitHub
• Pourquoi les générateurs de sites Web statiques sont la prochaine grande chose
• Générateurs de sites Web statiques examinés : Jekyll, Middleman, Roots, Hugo
• Automatisation du développement basé sur un guide de style

Cette ligne de pensée m'a ramené à une idée qui m'obsède un peu, à savoir que lorsque nous devons créer un artefact pour communiquer certaines idées à un client, le processus se déroule presque toujours mieux lorsque cet artefact est aussi proche que possible. possible à un site Web réel au lieu d'une image d'un site Web ou d'un PDF plein de diagrammes.

Ainsi, la question que j'ai fini par me poser : existait-il un outil que je pouvais utiliser pour aider les gens à modéliser rapidement le contenu d'une manière indépendante de la plate-forme et à créer simultanément un artefact idéal pour communiquer l'intention à un client ou à une équipe ?

Une théorie de haut niveau de la modélisation de contenu

Détournons un peu avant d'entrer dans Jekyll. Je pense que vous pouvez supprimer toutes les conventions et le langage spécifique à la plate-forme de la discussion sur la modélisation de contenu et la définir comme un système en trois parties :

1. L'idée centrale est celle d'un objet : une unité de contenu qui tient ensemble sur un site. Par exemple, un article de blog ou une personne serait un objet sur un site.
2. Les objets ont des attributs qui les définissent . Un article de blog peut avoir un titre, un corps de contenu, un auteur. Une personne peut avoir un nom, une photo, une biographie.
3. Les objets ont des relations qui déterminent leur emplacement sur un site , et les mises en page ont une logique qui définit quels attributs d'un objet sont utilisés et où. Notre exemple d'objet de publication de blog est connecté à un objet personne car son auteur est une personne. Nous publions le nom de l'auteur et un lien vers son profil sur la page de publication, et nous publions sa biographie complète sur sa page de profil.

Je voulais créer un système qui respecte les idées de haut niveau que j'ai exposées, mais laisse à l'équipe la liberté de créer des attributs et des relations comme elle l'entend sans se soucier des idées spécifiques à certaines plateformes. Au lieu de cela, ils pourraient se concentrer sur la définition du contenu en fonction de ce qui convient le mieux aux utilisateurs . Et il s'avère que Jekyll a les fonctionnalités pour rendre cela possible.

Entrez Jekyll

Jekyll est un framework de blog statique. Et avant de vous diriger vers la section des commentaires, oui, je suis conscient qu'il est correct de le considérer comme une plate-forme à part entière. Cependant, il présente quelques avantages par rapport à quelque chose comme Drupal ou WordPress.

Jekyll prend la simplicité au sérieux. Il n'a pas de base de données, mais s'appuie plutôt sur des fichiers plats et sur certaines balises de modèles Liquid qui génèrent du code HTML ancien. Le liquide est limité, simple et extrêmement lisible par l'homme. J'ai découvert que je pouvais montrer à quelqu'un un modèle construit avec des balises Liquid et tant qu'il avait un peu d'expérience avec le code frontal, il comprenait ce que faisait le modèle.

Ce qui est bien, c'est que nous n'avons pas à montrer à quelqu'un comment faire fonctionner une base de données, comment y connecter ses modèles, comment configurer la zone d'administration de son CMS pour qu'elle fonctionne avec ses modèles, etc. Au lieu de cela, nous pouvons installer Jekyll et apprendre à démarrer un serveur. Si l'utilisateur utilise un Mac, il y a de fortes chances qu'il s'agisse d'un processus de deux minutes qui ne fonctionne que la première fois que nous l'essayons.

Jekyll n'impose pas non plus beaucoup de conventions dans la gorge de l'utilisateur. Vous avez la liberté de créer votre structure de fichiers et votre pipeline d'actifs préférés, d'établir vos propres relations entre les fichiers et d'écrire le balisage de la manière que vous préférez. Les quelques conventions qu'il possède sont facilement reconfigurables pour s'adapter à votre style.

Utiliser des collections pour créer et contenir des objets

Bien qu'il soit toujours considéré comme une fonctionnalité expérimentale, Jekyll a quelque chose appelé collections qui nous permettra de créer le système que je décris.

Fondamentalement, vous créez un dossier et nommez-le d'après le type d'objet que vous créez. Ensuite, vous ajoutez des fichiers à ce dossier, et chaque fichier représente un objet dans cette collection. Une fois que vous avez des objets, vous pouvez leur créer des attributs en utilisant YAML au début de chaque fichier. YAML est une syntaxe qui vous permet de définir des paires clé/valeur qui stockent facilement des informations.

Ce qui est bien avec ce système, c'est qu'il est incroyablement simple. Tout est lisible par l'homme et fonctionne d'une manière facile à apprendre pour un nouvel utilisateur. Plutôt que de créer beaucoup de documentation sur la façon dont quelqu'un devrait créer du contenu et des relations dans le système final, vous pouvez simplement le créer. Les concepteurs peuvent voir quels sont les objets et leurs attributs afin de pouvoir planifier leur système de conception. Les développeurs frontaux disposent d'un site Web fonctionnel pour concevoir leur balisage et leur CSS.

Parce qu'ils ne sont pas obligés d'utiliser un système ou une convention spécifique, ils peuvent simplement utiliser celui qu'ils préfèrent ou les conventions de la plate-forme finale pour le projet. Et les développeurs back-end peuvent facilement déterminer l'intention du concepteur lors du transfert de modèles et de logique dans le CMS qu'ils décident d'utiliser, car il est déjà écrit pour eux.

Construisons un site simple avec des objets et des relations

Si nous voulons essayer cette idée, nous devrons créer un site Jekyll simple, puis construire nos objets et nos relations. Si vous voulez voir le produit final, vous pouvez le récupérer à partir de ce référentiel GitHub. (Remarque : vous devrez utiliser le terminal pour une partie de cela, mais c'est une utilisation assez basique, je vous le promets.)

Installer Jekyll

Si vous êtes sur Mac, c'est assez facile. Ruby est déjà installé, il vous suffit d'installer Jekyll. Ouvrez le terminal et tapez :

 gem install jekyll

Cela installera la gemme Jekyll Ruby et ses dépendances. Une fois l'exécution terminée, c'est tout : vous avez Jekyll.

Configuration de votre site

Maintenant, nous devons démarrer un échafaudage Jekyll. Je stocke tous mes projets Web dans un dossier sur mon Mac appelé Sites , dans le dossier d'accueil. Je dois donc d'abord y accéder avec:

 cd ~/Sites

Ensuite, je peux générer un dossier avec les fichiers et la structure appropriés avec cette commande :

 jekyll new my-new-site

Vous pouvez remplacer "mon-nouveau-site" par ce que vous voulez appeler votre projet. Ce que vous obtiendrez est un dossier portant ce nom et tous les bons fichiers à l'intérieur.

Ouvrez le Finder et accédez à votre nouveau dossier pour voir ce qu'il contient. Vous devriez voir quelque chose comme ceci :

Comme nous n'avons pas besoin de tout ce que propose Jekyll, nous allons d'abord supprimer quelques fichiers et dossiers. Lançons /_includes , /_posts , /_sass , about.md et feed.xml .

Configuration

Nous allons maintenant configurer nos configurations à l'échelle du site. Ouvrez _config.yml . Il y a un tas de trucs d'introduction là-dedans. Je vais simplement supprimer cela et le remplacer par mes configurations préférées. Voici la nouvelle configuration pour ce projet :

 permalink: pretty collections: projects people

J'ai fait en sorte que mes URL ressemblent à /path/to/file/ au lieu de /path/to/file.html , ce qui n'est qu'une préférence personnelle. J'ai également constitué deux collections : projets et personnes . Toute nouvelle collection doit être ajoutée au fichier de configuration.

Maintenant, je peux créer des dossiers pour ces collections dans mon projet :

Les noms de dossiers doivent commencer par le caractère _ (trait de soulignement) pour que Jekyll sache quoi en faire.

Fabriquer des objets

Les premiers objets que nous fabriquerons seront nos hommes. Nous allons utiliser Markdown pour créer ces fichiers afin qu'ils soient agréables et propres tout en générant du code HTML sémantique approprié. Vous pouvez voir que j'ai fait quelques fichiers pour des personnages de l'histoire américaine (cela peut être lié ou non au fait que j'écoute Hamilton sans arrêt depuis un mois maintenant) :

Les attributs que nous mettrons dans notre fichier pour une personne seront :

 --- object-id: first-name: last-name: job: listing-priority: wikipedia-url: ---

Nous utiliserons l' object-id pour faire spécifiquement référence à l'un de ces objets plus tard. Nous diviserons le prénom et le nom afin de pouvoir sélectionner la combinaison à utiliser à différents endroits (si votre système l'exige) et nous utiliserons job pour définir ce qu'ils font. (J'évite 'title' car c'est déjà une variable que les pages de Jekyll ont par défaut.) J'ai également inclus un attribut pour la priorité de liste qui me permettra de trier chaque personne selon son caprice, mais vous pouvez aussi trier par certaines méthodes intégrées telles que alphabétique ou numérique. Enfin, nous avons un champ pour un lien vers la page Wikipédia de la personne.

Tout cela est contenu entre trois traits d'union en haut et en bas pour le définir comme front-matter YAML. Le contenu de chaque bio ira après le YAML et peut être une quantité et une structure arbitraires de HTML (mais nous utiliserons le formatage Markdown pour que tout reste beau et propre).

Un objet personne complètement rempli ressemble à ceci (le contenu est tronqué pour plus de clarté) :

 --- object-id: alexander-hamilton first-name: Alexander last-name: Hamilton job: 1st United States Secretary of the Treasury listing-priority: 1 wikipedia-url: https://en.wikipedia.org/wiki/Alexander_Hamilton --- Alexander Hamilton (January 11, 1755 or 1757 – July 12, 1804) was...

Et voici un objet de projet (le contenu est tronqué pour plus de clarté) :

 --- object-id: united-states-coast-guard title: United States Coast Guard featured: true featured-priority: 2 listing-priority: 1 architect-id: alexander-hamilton wikipedia-url: https://en.wikipedia.org/wiki/United_States_Coast_Guard --- The United States Coast Guard (USCG) is...

Celui-ci a quelques différences. J'ai défini un attribut en featured . Si un projet est présenté, il est répertorié sur la page d'accueil. Tous les projets seront répertoriés sur la page des projets. Nous avons également notre ordre de tri préféré défini pour chaque placement. Et nous avons inclus une référence à l' id de la personne qui a créé le projet, afin que nous puissions nous y référer directement plus tard.

Générer des pages à partir de nos objets

En modifiant mon fichier _config.yml , je peux créer des pages pour chacun de ces objets.

 permalink: pretty collections: projects: output: true people: output: true

Définir output: true sur chaque collection entraîne la génération d'une page pour chaque objet qu'elle contient. Mais comme nos objets n'ont pas de contenu dans leurs fichiers, ils ne produisent actuellement aucune donnée, ce qui signifie que nous n'obtiendrons que des pages vides. Construisons un modèle de mise en page pour le faire pour nous.

Ce fichier ira dans le dossier _layouts . Mais d'abord, nous avons un fichier default.html à gérer. Cela contiendra tout balisage cohérent dans tous nos fichiers HTML.

 <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>{{ page.title }}</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="/css/styles.css" /> </head> <body> <header role="banner"> ... </header> <div role="main"> <div class="container"> {{ content }} </div> </div> <footer role="contentinfo"> ... </footer> </body> </html>

Vous remarquerez une balise Liquid qui ressemble à ceci : {{ content }} . Chaque fichier rendu dans une page par Jekyll a besoin d'un modèle spécifié pour lui. Une fois que vous avez spécifié son modèle, le contenu de ce fichier est rendu à l'emplacement de la balise {{ content }} dans le modèle de mise en page. Maintenant, nous n'avons pas à répéter des choses qui seront sur chaque page.

Ensuite, nous allons créer un modèle de mise en page unique pour nos objets de personne. Cela ressemblera à ceci :

 --- layout: default --- <header class="intro person-header"> <h1>{{ page.first-name }} {{ page.last-name }}</h1> <h2>{{ page.job }}</h2> </header> <div class="person-body"> {{ page.content }} <a href="{{ page.wikipedia-url }}">Read more about {{ page.first-name }} {{ page.last-name }} on Wikipedia</a> </div>

Ce fichier spécifie que son code est inséré dans le modèle de mise en page par défaut, puis son balisage est rempli à partir des données des fichiers d'objet de personne.

La dernière étape consiste à s'assurer que chaque objet personne spécifie qu'il utilise le fichier de mise en page person.html . Normalement, nous insérerions simplement cela dans le YAML dans nos fichiers personnels comme ceci :

 --- object-id: first-name: last-name: job: listing-priority: wikipedia-url: layout: person ---

Mais je préfère que les données de mes fichiers objets ne contiennent que des attributs pertinents pour le modèle de contenu. Heureusement, je peux modifier mon fichier _config.yml pour gérer cela pour moi :

 exclude: - README.md permalink: pretty collections: projects: output: true people: output: true defaults: - scope: type: projects values: layout: project - scope: type: people values: layout: person

Maintenant, mon site sait que tout objet de la collection de projets doit utiliser le modèle de mise en page du projet et que tout objet de la collection de personnes doit utiliser la mise en page de la personne. Cela m'aide à garder mes objets de contenu agréables et propres.

Affichage d'objets sur une page de liste

Que nous choisissions ou non de générer des pages pour nos objets, nous pouvons les répertorier et les trier selon différents paramètres. Voici comment nous énumérerions tous nos projets sur une page :

 --- layout: default title: Projects --- <header class="intro"> <h1>{{ page.title }}</h1> </header> <div class="case-studies-body"> <ul class="listing"> {% assign projects = site.projects | sort: 'listing-priority' %} {% for project in projects %} <li> <h2><a href="{{ project.url }}">{{ project.title }}</a></h2> {{ project.content }} </li> {% endfor %} </ul> </div>

Ce que nous avons fait est de créer un <ul> pour mettre notre liste à l'intérieur. Ensuite, nous avons créé une variable sur la page appelée projects , et lui avons assigné tous nos objets de projet, et les avons triés par la variable listing-priority que nous avons créée dans chacun. Enfin, pour chaque projet dans notre variable de projects , nous produisons un <li> qui inclut les données des attributs de chaque fichier. Cela nous donne une liste hautement contrôlable de nos objets de projet avec des liens vers leurs pages uniques.

Sur la page d'accueil, au lieu d'afficher tous les projets, nous n'afficherons que nos projets en vedette :

 <ul class="listing"> {% assign projects = site.projects | where: "featured", "true" | sort: 'featured-priority' %} {% for project in projects %} <li> <h3>{{ project.title }}</h3> <a href="{{ project.url }}">Learn about {{ project.title }}</a> </li> {% endfor %} </ul>

Tout objet de projet dont l'attribut en featured est défini sur true s'affichera sur cette page et sera trié selon l'ordre de priorité spécial que nous avons défini pour les projets en vedette.

Ce sont des exemples assez simples de la façon de sortir et de trier des objets, mais ils démontrent les différentes capacités que nous pouvons créer pour organiser le contenu.

Liaison à un objet spécifique

La dernière fonctionnalité que nous allons créer est la liaison à un objet spécifique. C'est quelque chose que vous voudrez peut-être faire si vous liez un auteur à un article de blog ou quelque chose de similaire. Dans notre cas, nous allons rattacher une personne au projet auquel elle est généralement associée. Si vous vous souvenez, notre objet de projet a un attribut architect-id et nos gens ont chacun un attribut object-id . Nous pouvons associer la bonne personne à un projet spécifique en utilisant ces attributs.

Voici notre modèle de mise en page de projet :

 --- layout: default --- {% assign architect = site.people | where: "object-id", page.architect-id | first %} <header class="intro project-header"> <h1>{{ page.title }}</h1> <p>Architected by: <a href="{{ architect.url }}">{{ architect.first-name }} {{ architect.last-name }}</a></p> </header> <div class="project-body"> {{ page.content }} <a href="{{ page.wikipedia-url }}">Read more about {{ page.title }} on Wikipedia</a> </div>

La ligne 4 crée une variable appelée architect et recherche dans tous nos objets people tout object-id d'objet correspond à l'attribut architect-id d'un projet. Nous devons attribuer object-id afin qu'un seul résultat soit renvoyé, mais pour nous assurer que nous n'obtenons qu'une seule réponse et que nous nous y référons au lieu de notre liste d'un élément, nous devons définir | first | first à la fin de notre balise Liquide {% assign %} . Cela contourne une limitation de Jekyll où les objets dans les collections n'ont pas d'identifiants uniques pour commencer. Il existe une autre fonctionnalité appelée données qui permet des identifiants uniques, mais elle ne produit pas facilement des pages ou ne nous donne pas la possibilité de trier nos objets ; contourner les limites des collections était un moyen plus simple et plus propre d'obtenir les fonctionnalités souhaitées.

Maintenant que la page a un objet unique qui représente l'architecte de ce projet, nous pouvons appeler ses attributs avec des choses comme le prénom de l'architecte et l'URL de sa page Wikipedia. Voila ! Liaison facile aux objets par ID unique.

Emballer

Il existe d'autres fonctionnalités intéressantes qui peuvent être établies en fouillant plus en détail dans la documentation de Jekyll, mais ce que nous avons ici, ce sont les bases d'un bon prototype de modélisation de contenu : la possibilité de définir différents types d'objets, les attributs attachés à ces objets, et des identifiants qui nous permettent d'appeler des objets spécifiques de n'importe où. Nous obtenons également une logique très flexible pour la modélisation et la sortie de nos objets à divers endroits. Mieux encore, l'ensemble du système est simple et lisible par l'homme, et génère du HTML brut à utiliser ailleurs si nécessaire.

À des fins de communication, nous avons maintenant un prototype cliquable indépendant de la plate-forme (un vrai site Web) qui définira le système mieux qu'un PDF avec un tas de diagrammes ne le pourrait jamais. Nous pouvons modifier notre modèle de contenu à la volée au fur et à mesure que nous apprenons de nouvelles choses et que nous devons nous adapter. Nous pouvons faire entrer le concepteur et le développeur dans le système pour établir leurs modèles et leur architecture frontale, car il acceptera tout balisage et CSS qu'ils souhaitent utiliser. Nous pouvons même y intégrer des éditeurs de contenu en les configurant avec un accès via une interface graphique GitHub ou une plate-forme d'hébergement qui permet l'utilisation d'un éditeur visuel tel que Prose.io, GitHub Pages, CloudCannon ou Netlify.

Et rien de tout cela ne lie une personne à l'apprentissage de méthodes de travail spécifiques à la plate-forme, ce qui lui permet de travailler à la place à un niveau conceptuel axé sur les utilisateurs et non sur la technologie.