C’est la version sur laquelle vous lisez cette article 😊

Pour rappel, avant le site ressemblait à ça :

Pourquoi changer de solution ?

Au tout début je m’étais concentré sur la modification des feuilles de styles en m’appuyant sur Tailwind CSS (comme souhaité par Frank), puis sur la modification des templates Go.
Puis, je me suis rapidement arraché les cheveux sur le moteur de templates d’Hugo... En effet, ne le pratiquant pas régulièrement, j’étais systématiquement en train de consulter la documentation pour savoir comment réaliser des actions pourtant basiques : comment manipuler une variable, gérer les héritages, les inclusions, etc.
Bref, une perte de temps importante et une motivation se réduisant de jour en jour.

J’ai alors décidé de sauter le pas et de migrer vers Cecil, pour 2 raisons majeures :

1. Je connais la solution sur le bout des doigts (et pour cause puisque j’en suis le créateur ^^) ;
2. Et surtout je suis à l’aise, et donc efficace, avec le moteur de template Twig.

Comment ?

Après le "pourquoi ?" intéressons nous maintenant à la partie la plus intéressante de ce billet, à savoir le "comment ?" 😊

Le principe de génération du site, la structure des contenus et l’organisation des templates étant relativement proches entre Hugo et Cecil, j’ai décidé de procéder par itérations successives plutôt que de repartir d’une page blanche, selon la boucle suivante :

1. J’effectue une modification ;
2. Je lance un nouveau build ;
3. J’effectue les ajustements nécessaires (en m’appuyant sur les messages d’erreur retournés) ;
4. Je recommence jusqu’à ce que le build soit valide.

Gestion de contenu

Nous pouvons séparer les contenus en 2 catégories :

1. Les pages, c’est à dire les articles rédigés dans le format Markdown
2. Les assets, c’est à dire les illustrations et autres vidéos au sein des articles

Aussi, je me suis tout d’abord concentré sur la réorganisation de ces contenus :

1. Déplacement des fichiers *.md du dossier content/ de Hugo vers le dossier pages/ de Cecil
2. Renommage des fichiers dans la section post de manière à les préfixer avec la date de l’article (YYYY-MM-DD_Titre.md) et ainsi faciliter leur tri
3. Déplacement des fichiers médias dans le dossier dédié de Cecil (asset/)

Mise en forme et templates

Le changement de moteur de templates aura certainement été le plus gros du travail, mais qui aura permis d’optimiser le rendu, via :

• La rationalisation et la factorisation des templates de manière à ne pas/plus dupliquer du code
• La suppression des templates inutiles, c’est à dire disponibles en natif avec Cecil (tel que celui du flux RSS)

Dépendances et scripts

Cecil supportant nativement (entre autre) la minification des scripts et des feuilles de styles, il n’est plus nécessaire d’installer certaines dépendances requises par Hugo. J’ai pu de fait, réduire le fichier package.json au strict minimum : à savoir le support de Tailwind CSS et de All Contributors.

De plus, il existe des Themes Components pour Cecil, c’est à dire des thèmes utilitaires, dont PWA permettant de transformer n’importe quel site web généré avec Cecil en Progessive Web App.

Image de partage

L’image de partage sur les réseaux sociaux était créée de manière semi-automatique via l’API HTTP de manipulation d’image de Cloudinary, en paçant le lien (fabriqué à la main) dans le front matter de chaque post.

Même si ça fonctionnait plutôt bien en pratique, cette méthode était contraignante puisqu’il fallait recréer l’URL pour chaque nouvel article, en veillant à l’encoder correctement.

De plus le service de Cloudinary était sollicité à chaque affichage du post concerné, alors même que l’image n’était plus modifiée.

Aussi, j’ai délégué la construction de cette URL au template post/page.html.twig :

{% set cloudinary_url = 'https://res.cloudinary.com/%s/image/upload/f_auto,q_auto/w_1100,c_fit,co_white,g_north_west,x_80,y_120,l_text:poppins_80_ultrabold_line_spacing_-30:%s/%s'|format(site.cloudinary.account, page.title|url_encode|replace({'%2C':'%252C'}), 'jamstatic/twitter-card.png') %}
{% set image = asset(cloudinary_url, {filename: 'cards/%s.png'|format(page.id)}) %}

En pratique :

• Création d’une image « modèle » (en veillant à garder de la place pour y intégrer le titre du billet)
• Utilisation de la fonction asset() pour manipuler l’image générée par Cloudinary :
  1. Format automatique et qualité automatique
  2. Définition de la largeur maximum du texte avant retour à la ligne (1100 px) et positionnement du texte aux coordonnées 80:120
  3. Utilisation de la police de caractère Poppins 80 ultra bold interligne -30
  4. Remplacement des virgules présentes dans le titre par des espaces
  5. Encodage de l’URL obtenue
  6. Enfin, enregistrement de l’asset avec un nom de fichier "slugifié" afin d'être compatible avec les contraintes de nommage Windows, au format PNG

Exemple :

Conclusion

Pour conclure rapidement, je dirais que l’important ici n’est pas la solution utilisée pour générer le site : c’est la source de la donnée, le contenu, en l’occurrence les articles. Et, dans le cas de cette migration technique, ce qui a fait la différence c’est le fait que les articles ont été rédigés dans un format standardisé, Markdown, indépendant de la solution technique.

Billet initialement publié sur le blog d’Arnaud Ligny.

Quand je travaillais à enrichir la documentation de Cecil, je me suis dit qu’il serait pertinent d’offrir un moteur de recherche full text aux utilisateurs.

La documentation de Cecil est composée de moins de 10 pages : une par thématique (configuration, gestion des contenus, création des templates, etc.) et chacune d’elle contient de nombreuses sections, accessibles par des ancres.

Aussi, il est important que les résultats retournés par un moteur de recherche soient granulaires, c’est à dire qu’ils ciblent ces sections au sein d’une page.

Quelle solution technique ?

Google CSE

Dans un premier temps j’ai expérimenté le moteur de recherche personnalisé de Google (CSE) qui permet de présenter les résultats indexés par Google pour un site donné (comme avec le préfixe site:).
Si les résultats sont pertinents pour un site contenant de nombreuses pages, il ne semble pas possible de personnaliser les résultats en fonction de sections au sein d’une même page, ce qui ne correspondant pas à mon besoin.

Algolia

Aussi, après plusieurs comparatifs, j’ai finalement retenu la solution Algolia pour les raisons suivantes :

• Pertinence des résultats
• Tarifs abordables (dont un plan gratuit)
• Documentation riche
• Nombreuses bibliothèques de code open source

Étapes clefs

Je souhaitais que le champ de recherche soit disponible sur chacune des pages et qu’il montre immédiatement un extrait des résultats lors de la saisie d’un ou plusieurs mots clefs, et laissant le choix à l’utilisateur de sélectionner la section à consulter : j’ai donc opté pour l’approche Autocomplete (cf. la capture d’écran en début de billet).

Créer un index

Algolia s’appuie sur un index, c’est à dire une collection d’enregistrements dans laquelle la recherche va être effectuée et dont le résultat permet d’afficher un certain nombre d’informations et de pointer vers la page Web correspondante.

Cet index est une structure JSON relativement libre, composée de couples clef-valeur, permettant d’avoir de la matière dans laquelle chercher et également ajuster les critères de recherche.

Transmettre l’index

Algolia propose plusieurs méthodes afin de transmettre ou de mettre à jour l’index :

• à la main, via le dashboard, en uploadant le fichier JSON
• en ligne de command, via Algolia CLI
• programmatiquement, en PHP, en JavaScript, etc.

Paramétrer l’index

Le paramétrage de l’index, c’est à dire déterminer les attributs dans lesquels rechercher, le classement et l’ordonnancement, etc. est relativement simple à réaliser depuis le dashboard.

Je dis relativement car il peut être nécessaire d’effectuer quelques tests avant de maitriser les règles de priorisation des résultats.

Mise en œuvre

Dans le cas de la documentation de Cecil, il faut donc :

1. créer un fichier d’index au format JSON
2. le transmettre à application Algolia
3. afficher un champs de recherche avec auto-complétion

Création de l’index

Avec Cecil il est plutôt aisé de créer un fichier JSON puisque, par définition, c’est son job de générer des fichiers statiques 😊

Ainsi, l’objectif est de :

1. collecter le contenu des pages de la documentation (fichiers au format Markdown dans pages/documentation), converti en HTML
2. découper ce contenu de manière cohérente (l'objectif n’est pas de pointer sur la page, mais bien sur une section de la page), via un template Twig sur mesure
3. générer un fichier algolia.json grâce aux formats de sortie

Résultat cible

Le fichier d’index va ressembler à ça :

[
  {
    "objectID": "documentation/quick-start#download-cecil",
    "page": "Quick Start",
    "title": "Download Cecil",
    "description": "Download cecil.phar from your terminal:",
    "content": "...",
    "date": "2020-12-19T00:00:00+00:00",
    "href": "documentation/quick-start/#download-cecil"
  },
  ...
]

Création du template

Comme indiqué précédemment, dans le contexte de Cecil, pour créer ce fichier il est nécessaire de créer un template Twig qui va collecter les donner et les rendre au format JSON.

S’agissant de rechercher dans la documentation, j’aurais pu créer ce template dans le dossier « documentation » (layouts/documentation/list.algolia.twig).
Mais comme je souhaite potentiellement étendre la recherche à plusieurs types de contenus (tels que les « news ») je préfère créer un template applicable à l’ensemble des contenus du site, donc une liste par défaut : layouts/_default/list.algolia.twig.

Ainsi, au sein du template, il suffit de boucler sur les contenus de la section « documentation », à l’aide du tag for :

{% for p in site.pages|filter(p => p.section == 'documentation')|sort_by_weight %}
...
{% endfor %}

Ensuite, toute l’astuce consiste à « jouer » sur les header HTML, en l’occurence le « H3 » afin de découper le contenu d’une page en sous sections :

{% set sections = p.content|preg_split('/<h3[^>]*>/') %}

Le filtre Twig preg_split à été créé pour l’occasion afin de permettre le découpage d’une chaine de caractère en un tableau, selon une expression régulière.

De là, il suffit ensuite d’extraire les contenus cibles de chaque section, via de la manipulation de chaines de caractères, pour alimenter un « dataset » :

{
  "objectID": "Un ID unique",
  "page": "Le nom de la page de documentation",
  "title": "Le titre de section",
  "description": "Le premier paragraphe de la section (utilisé pour illustrer l’aperçu des résiltats)",
  "content": "Le contenu de la section, dans laquelle la recherche est effectuée",
  "date": "La date de la page, utilisée pour pondérer les résultats",
  "href": "Le lien vers la page de la documentation, combinée à une ancre afin d’emmener l’internaute à la bonne section",
}

Voir le template complet sur GitHub.

Associer ce template à un format de sortie

En l’état, Cecil ne sait pas qu’il faut utiliser ce template et surtout à quel type de contenu il doit être associé. C’est embêtant 😅

Pour régler ce soucis il suffit de compléter la configuration de la manière suivante :

output:
  formats:
    - name: algolia
      mediatype: 'application/json'
      filename: 'algolia'
      extension: 'json'
  pagetypeformats:
    homepage: ['html', 'atom', 'algolia']

Maintenant Cecil sait que :

1. Les pages dont la variable format a pour valeur le nom du format « algolia » peuvent utiliser un template de la forme <layout>.algolia.twig
2. Enregistrer le fichier généré sous filename.extension, soit « algolia.json »
3. La page de type homepage (listant toutes les pages du site) doit être générée dans le format « algolia » (en plus de « html » et « atom »)

Et voilà, l’index est maintenant généré et disponible à la racine du site généré : https://cecil.app/algolia.json.

Transmission de l’index

Comme indiqué précédemment, Algolia offre plusieurs méthodes d’envoi de l’index.

Dans un premier temps j’ai déposé manuellement le fichier généré localement directement depuis le dashboard : c’est un moyen simple et rapide de faire des tests d’intégrité de l’index.

J’ai ensuite cherché à automatisé cette procédure, et j’ai donc opté pour le client d’API JavaScript.
Cecil.app étant hébergé par Netlify, j’ai utilisé un plugin pour me simplifier la mise en oeuvre : Algolia Index Refresh Build Plugin :

[[context.production.plugins]]
  package = "netlify-plugin-refresh-algolia"
  [context.production.plugins.inputs]
    appId = "APP_ID"
    indexName = "INDEX"
    filePath = "_site/algolia.json"

Formulaire de recherche

La mise en œuvre est relativement simple :

1. intégrer un champ de saisi (élément input)
2. lui associer la bibliothèque Autocomplete.js

Champ de saisie :

<input type="text" id="search-input" placeholder="{% trans %}Search the Docs [Alt+S]{% endtrans %}" accesskey="s" />

Autocomplete.js :

// client Algolia
var client = algoliasearch('APP_ID', 'API_KEY');
// index dans lequel rechercher
var index = client.initIndex('INDEX');
// fonction de recherche
function newHitsSource(index, params) {
  return function doSearch(query, cb) {
    index
      .search(query, params)
      .then(function(res) {
        cb(res.hits, res);
      })
      .catch(function(err) {
        console.error(err);
        cb([]);
      });
  };
}
// association de la lib au champ "search-input"
autocomplete('#search-input', { hint: false }, [
  {
    source: newHitsSource(index, {
      // paramètres de mise en valeur des résultats suggérés
      hitsPerPage: 4,
      attributesToHighlight: ['description', 'page', 'title'],
      highlightPreTag: '<strong>',
      highlightPostTag: '</strong>',
      attributesToSnippet: ['description:25'],
      snippetEllipsisText: '…'
    }),
    // clef d'affichage principale (ici le titre de la section)
    displayKey: 'title'
  }
]).on('autocomplete:selected', function(event, suggestion, dataset, context) {
  // au clic sur une suggestion on envoie l'internaute vers la page#ancre correspondante
  window.location.href = '{{ url() }}' + suggestion.href;
});

Voir le template complet sur GitHub.

Et voilà ! 🎉

Notes :

1. Il s’agit ici de la version 0 de Autocomplete.js qui reste fonctionnelle mais commence à vieillir
2. La personnalisation de l’apparence des suggestions est un peu pénible car il faut arriver à « retrouver » les classes CSS générées à la volée via JavaScript, ce qui n’est pas toujours évident…

Conclusion

Je me suis bien amusé à créer ce moteur de recherche, et je suis plutôt satisfait de la fonctionnalité, qui est fonctionnelle et surtout très utile.

Pour tester, ça se passe par ici : https://cecil.app/documentation/

Billet initialement publié sur le blog d’Arnaud Ligny.

GitHub fourni l’outillage nécessaire pour générer un site statique et pour l’héberger – gratuitement – grâce à GitHub Pages et GitHub Actions.

Dans cet article j’explique comment mettre en pratique GitHub Pages et GitHub Actions, en utilisant Cecil comme générateur de site statique.

Qu’est-ce que GitHub Pages ?

GitHub Pages est une solution d’hébergement de pages web statiques permettant de créer rapidement un site web associé à un projet GitHub.\ Historiquement, cette branche dédiée d’un dépôt, utilise Jekyll par défaut pour générer à la volée des pages web à partir de son contenu (fichiers Markdown et HTML).

Aujourd’hui de nombreux développeurs ont abandonnés Jekyll au profit d’autres générateurs de site statique, plus riches en fonctionnalités, afin de profiter de cette solution d’hébergement gratuite.

GitHub Pages est très facile à utiliser, puisqu’il suffit de commiter des fichiers dans un dépôt GitHub pour obtenir un site web, mais reste limité et ne propose que les réglages suivants :

1. Choix de la branche (et du dossier : racine ou /docs) à utiliser
2. Possibilité de choisir un domaine personnalisé (via un enregistrement CNAME)
3. Activation de HTTPS

Comme je viens de l’indiquer, l’idée ici de s’appuyer sur le SSG de son choix : mais dans ce cas, comment automatiser la génération en cas de modification d’une page de contenu ou d’un template ? C’est là que GitHub Actions intervient ! 😀

Qu’est-ce que GitHub Actions ?

GitHub Actions est la solution de GitHub pour automatiser des workflows de type intégration ou déploiement continue.

Le principe est très proche de ce que propose des outils comme Jenkins, Travis CI ou encore GitLab CI.

En pratique c’est plutôt simple : un fichier de configuration permet de déterminer quelles actions déclencher, selon quels évènements, dans un ou plusieurs environnements donnés, dans un certain ordre et de produire un « livrable » ou un résultat (positif ou négatif).

Ce qui fait la puissance de GitHub Actions c’est à la fois la rapidité de mise à disposition de ses machines virtuelles et surtout, comme son nom l’indique, de ses (très nombreuses) Actions mis à disposition par la communauté sur la marketplace.

En pratique, comment faire ?

Le principe semble simple mais, en pratique, est-ce que c’est aussi facile à mettre en œuvre ?\ La réponse est oui bien sûr ! 😀

Comme je l’indiquais en introduction, je vais illustrer mon propos en expliquant comment automatiser la génération d’un site statique avec Cecil et comment le déployer.

Création du workflow

Les fichiers de configuration de workflow de GitHub Actions doivent être déposés dans un dossier spécifique à la racine du dépôt qui contient les fichiers source du site à générer :

.github/workflows/

De là il suffit de créer un nouveau fichier avec l’extension yml ou yaml (par exemple build-and-deploy.yml) qui sera automatiquement reconnu comme un nouveau workflow accessible depuis l’onglet « Actions » du dépôt.

Définition des tâches et des étapes

Avant de définir les tâches il est nécessaire de déterminer l’évènement déclencheur :

on:
  push:
    branches:
    - master

Ici on considère que la branche de production est master et que la génération doit être déclenchée à chaque modification de code (push).

En pratique nous devons définir 2 tâches (jobs) :

1. build : génération du site statique

C’est là que la marketplace montrent tout son intérêt. En effet, pour chacune des étapes (steps) ci-dessous, j’utilise une action clef en main :

1. Obtention du code source via checkout
2. Génération du site via Cecil-Action
3. « Mise de côté » des fichiers générés via upload-artifact

Note : la directive with permet de passer des options à l’action.

build:
  name: Build
  # Utilisation d'une image Linux Ubuntu
  runs-on: ubuntu-latest
  steps:

  - name: Checkout source
    uses: actions/checkout@v2
    with:
      # Inutile de récupérer tout l'historique : la dernière version suffit
      fetch-depth: 1

  - name: Build site with Cecil
    uses: Cecilapp/Cecil-Action@v3
    with:
      # Pour éviter les conflits, utilisation d'un nom spécifique
      config: 'cecil.yml'

  - name: Upload site to Artifacts
    uses: actions/upload-artifact@v2
    with:
      name: _site
      path: _site
      # La tâche ne sera pas exécutée si aucun fichier n'est généré
      if-no-files-found: error

2. deploy : déploiement des fichiers générés

1. Récupération des fichiers générés via download-artifact
2. Déploiement du site via GitHub-Pages-deploy

deploy:
  name: Deploy
  # La tâche 'deploy' est exécutée après la tâche 'build'
  needs: build
  runs-on: ubuntu-latest
  steps:

  - name: Download site from Artifacts
    uses: actions/download-artifact@v2
    with:
      name: _site
      path: _site

  - name: Deploy site to GitHub Pages
    uses: Cecilapp/GitHub-Pages-deploy@v3
    env:
      # Accès en écriture à la branche cible (`gh-pages`)
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    with:
      # Adresse e-mail valide sur GitHub
      email: arnaud@ligny.org

Note : par défaut GitHub-Pages-deploy utilise le dossier _site comme source et le déploie dans la branche gh-pages.

Paramétrage de GitHub Pages

Enfin, il reste à activer GitHub Pages au sein du dépôt via Settings > Pages.

1. Sélectionner la branche cible gh-pages (ainsi que le dossier /)
2. Puis le domaine (si vous souhaitez le personnaliser)
3. Et enfin activer HTTPS (si le domaine de référence est personnalisé)

Et voilà comment générer et déployer automatiquement un site web statique, hébergé gratuitement ! 🎉

Remarques :

• Dans cet article j’ai utilisé Cecil Action mais j’aurais également pu effectuer la même démonstration avec une action Hugo ou Eleventy ;
• Si vous souhaitez tester par vous même, en moins d’une minute, je vous invite à essayer avec le template Single-GitHub-Page.

Billet initialement publié sur le blog d’Arnaud Ligny.

En début d’année ma chérie terminait la campagne Ulule de son projet Paysages à vélo et se posait la question de continuer la vente de ses créations via une boutique en ligne.

Elle m’a alors sollicité pour l’aider à concevoir et construire cette boutique. Elle hésitait entre une solution clef en main telle que Shopify ou une solution basée sur un framework e-commerce tel WooCommerce.
Néanmoins, la première solution reste onéreuse pour un petit projet (peu de ventes) et la seconde demande beaucoup d’énergie y compris pour un petit catalogue.

Je lui ai alors proposé de créer un site web statique avec Cecil auquel nous brancherions la solution e-commerce Snipcart afin de dynamiser les interactions utilisateur.

Pourquoi un site statique ?

Je suis un fervent promoteur de l’approche statique pour la diffusion de sites web de contenu pour les raisons suivantes (entre autres) :

• Performance : une fois généré, le site n’a pas plus besoin d’être interprété par le serveur, juste d’être servi ;
• Simplicité : pas de base de données à maintenir car les données sont stockées dans des fichiers plats (Markdown + YAML) ;
• Portabilité : peut être hébergé sur n’importe serveur web et peut donc être migré facilement selon les besoins.

Dans le cas de ce projet j’ai donc utilisé mon propre générateur de site statique : Cecil.

Pourquoi Snipcart ?

Snipcart n’est pas une solution e-commerce clef en main mais plutôt un « checkout » (tunnel d’achat) à ajouter à n’importe quel site web.

Il est donc nécessaire d’avoir préalablement créé un site catalogue pour charger les articles (produits) dans sa boutique Snipcart, puis de placer un bouton d’ajout au panier sur chaque fiche produit.

Le reste, à savoir le panier et les étapes de la commandes (saisie de l’adresse de facturation, choix du mode de livraison, paiement, etc.), est injecté automatiquement via JavaScript par le composant Snipcart.

Intérêt de cette approche et de Snipcart en particulier :

• Indépendance concernant la gestion du catalogue ;
• Peu ou pas de développement spécifique, principalement de la personnalisation ;
• Tarif honnête (2% des ventes) ;
• Sécurisation des transactions portée par la solution de paiement (ici Stripe).

Mise en œuvre

Création du catalogue

Le catalogue de Paysages à vélo est très simple : il s’agit de proposer moins d’une dizaine d’affiches dans 2 formats d’impression (A3 et A5).
En pratique nous avons 6 modèles composés d’1 variant « format ».

Les attributs et le texte de la fiche produit sont définis dans un fichier Markdown (avec un « front matter ») :

pages/products
|_ index.md
|_ 1.pink-gravel.md
|_ 2.purple-cargo.md
|_ 3.yellow-longtail.md
|_ 4.blue-folding-bike.md
|_ 5.ultra-violet-gang.md
|_ 6.lemon-lovers.md

Les produits partagent les mêmes caractéristiques de base, qui peuvent donc être mutualisées à la racine de la section products via le fichier pages/products/index.md.
Les attributs sont définis via des variables au format YAML :

---
cascade:
  price: 23
  variants:
  - name: Format
    options:
    - value: A3
      html: "Affiche A3 - 23 €"
      price: 0
    - value: A5
      html: "Carte A5 - 8 €"
      price: -15
---

J’ai utilisé la variable spéciale cascade qui permet de faire hériter à toutes pages de la section les variables qu’elle contient :

• price : le prix de référence
• variants : qui caractérise les déclinaisons pour chacun des produits, en l’occurrence le format d’impression
  • options :
    • value : la valeur du format (ex : « A3 »)
    • html : le texte affiché dans la liste déroulante
    • price : le prix modifié par rapport au prix de référence (qui peut être négatif)

Ensuite chacun des produits est caractérisé via son propre fichier Markdown, par exemple pages/products/1.pink-gravel.md :

---
title: "Pink gravel"
description: "Femme ridant en toute liberté au pieds des montagnes."
name: "#01 Pink gravel"
image: "/images/products/01-Pink-gravel-A3_S.png"
gallery:
- "/images/products/01-Pink-gravel-A5_S.png"
- "/images/products/01-Pink-gravel-ZOOM_S.png"
published: true
---
**Gavarnie, Hautes-Pyrénées.**  
**Femme ridant en toute liberté au pieds des montagnes.**

_Impression numérique sans bordure sur papier couché premium semi mat 200 g (carte A5 300 g). 
Les affiches sont toutes signées à la main._

Templates et intégration Snipcart

Liste des produits

La volumétrie du catalogue étant très faible il n’est pas nécessaire de construire une arborescence complexe : afficher l’ensemble des produits sur la page d’accueil est suffisant.

Ainsi le template Twig layouts/index.html.twig liste l’ensemble des « pages » contenus dans la section products triées par « poids » inverse (donc la dernière création en première position) :

{% extends 'page.html.twig' %}

{% block content %}
<div class="hero">
  {{~ page.content ~}}
</div>
<div class="products">
  {%- for product in site.pages.all|filter_by('section', 'products')|sort_by_weight|reverse ~%}
    {%~ include 'components/product.html.twig' with {'product': product, 'home': true} only ~%}
  {%- endfor ~%}
</div>
{% endblock %}

Fiche produit

La fiche produit (un composant Twig réutilisable) va afficher :

1. Les informations : nom, description, photos, etc.
2. Le choix du format (options du variant format), la saisie de la quantité souhaitée et le bouton « Ajouter au panier »

Concentrons nous sur le cœur de la fiche produit, à savoir l’ajout au panier :

<div class="product__details">
  {%- if product.variants is defined ~%}
  <div>
    {%- for variant in product.variants ~%}
      {%- if variant.options is defined ~%}
    <label for="{{ productId }}-{{ variant.name|lower }}">{{ variant.name }}</label>
    <select id="{{ productId }}-{{ variant.name|lower }}" class="{{ variant.name|lower }}">
        {%- for option in variant.options ~%}
      <option value="{{ option.value }}">{{ option.html }}</option>
        {%- endfor ~%}
    </select>
      {%- endif ~%}
    {%- endfor ~%}
  </div>
  {%- endif ~%}
  <div>
    <label for="{{ productId }}-qty">Quantité</label>
    <input type="number" id="{{ productId }}-qty" class="qty" min="1" max="10" value="1" />
  </div>
  {%~ include 'components/add-item.html.twig' with {'productId':productId,'product':product} only ~%}
</div>

Cette portion du template layouts/components/product.html.twig est composée de 3 parties :

1. La liste déroulantes des formats, en faisant une boucle sur l‘ensemble des variants disponibles (ici uniquement format), puis une autre boucle sur l’ensemble des options (A3 et A5) ;
2. Le champ de saisi de la quantité ;
3. Le bouton d’ajout au panier (représenté par le composant add-item.html.twig).

C’est le composant bouton qui porte les attributs permettant l’ajout du produit au panier Snipcart.

Intégration Snipcart

L’intégration de Snipcart est simple, et nécessite :

1. La feuille de style de référence ;
2. Un ou plusieurs boutons d’ajout au panier, portant les attributs du produit : identifiant, URL, nom, prix, etc. ;
3. Une balise <div> invisible (permettant affichage du panier) portant la clef d’API Snipcart ;
4. L’applicatif à proprement parlé via un fichier JavaScript.

<link rel="stylesheet" href="https://cdn.snipcart.com/themes/v3.0.11/default/snipcart.css" />

<button class="snipcart-add-item"
  data-item-id="product-1"
  data-item-url="/"
  data-item-name="Product #1"
  data-item-price="10.99"
>Add to cart</button>

<div hidden id="snipcart" data-api-key="MzMxN2Y0ODMtOWNhMy00YzUzLWFiNTYtZjMwZTRkZDcxYzM4"></div>

<script src="https://cdn.snipcart.com/themes/v3.0.11/default/snipcart.js"></script>

• Démo : https://codepen.io/thatfrankdev/pen/xxwRXQw?editors=1000
• Template de Paysages à vélo : layouts/components/add-item.html.twig

Personnalisation du tunnel d’achat

J’ai également pris le temps de personnaliser le tunnel d’achat à la fois au niveau du rendu graphique et des étapes.

Personnalisation du rendu

Concernant le rendu graphique, ce n’est pas le plus commode à réaliser : il est en effet nécessaire d’inspecter l’ensemble des composants HTML afin d’identifier les classes CSS, de les dupliquer et de les modifier selon ses besoins.

Par exemple, pour remplacer la police de caractère :

.snipcart {
  font-family: 'Roboto Condensed', sans-serif;
}

La feuille de style Sass de Paysages à vélo disponible sur GitHub.

Remarque : depuis la version 3.2, Snipcart a introduit la notion de « Theming » qui facilite grandement la personnalisation via des propriétés CSS.

Personnalisation des textes

Les textes de l’interface de Snipcart sont disponibles en français (à laquelle j’ai d’ailleurs apporté ma contribution) sans paramétrage particulier (autre qu’en définissant l’attribut lang de la balise <html>) mais si vous souhaitez personnaliser les textes, ça reste possible en chargeant son propre fichier de langue :

document.addEventListener('snipcart.ready', function() {
  fetch('/snipcart/{{ language }}.json')
    .then(response => response.json())
    .then(translation => Snipcart.api.session.setLanguage('{{ language }}', translation))
});

Personnalisation des formulaires

Snipcart permet également de modifier et d’enrichir les étapes du tunnel d’achat via des templates Vue.js :

<div hidden id="snipcart" data-api-key="{{ site.snipcart.apikey }}" data-templates-url="/snipcart/templates.tpl"></div>

Ainsi, dans le cas de Paysages à vélo j’ai :

1. Modifié l’affichage des lignes du panier afin d’y indiquer le format d’impression sélectionné à côté du nom du produit ;
2. Désactivé la suggestion d’adresse (qui n’est pas très fiable sur le territoire français) ;
3. Ajouté un champ de saisi d’un message cadeau.

Par exemple, dans le cas du champ de saisi du message cadeau, le code ressemble à ça :

<shipping-address section="bottom">
  <fieldset class="snipcart-form__set">
    <hr class="snipcart-form__separator" />
    <!-- Gift message -->
    <div class="snipcart-form__field">
      <snipcart-label class="snipcart__font--tiny" for="Message cadeau">Message cadeau</snipcart-label>
      <snipcart-input name="Message cadeau"></snipcart-input>
      <p class="snipcart__font--tiny snipcart-form__footer">
        (Votre message sera écrit à la main sur une carte, ajoutée au colis)
      </p>
    </div>
  </fieldset>
</shipping-address>

Si vous voulez en voir plus le code source est disponible sur GitHub.

Gestion de contenu (CMS)

La configuration du site, les fiches produit et les pages de contenu sont administrables à la main en éditant les fichiers correspondant, ce qui est suffisant dans la plupart des cas.

Néanmoins il peut s’avérer plus commode et plus agréable de pouvoir s’appuyer sur un CMS : dans le cas de Paysages à vélo, j’ai retenu Forestry pour sa simplicité de mise en œuvre et d’utilisation.

De plus Forestry offre un fonctionnalité de prévisualisation, en contexte, très efficace !

Conclusion

J’ai pris beaucoup de plaisir à réaliser ce petit site e-commerce, principalement grâce à Snipcart qui m’a permis d’être libre sur la création du site web catalogue tout en offrant des options de personnalisation du tunnel d’achat relativement simples à mettre en œuvre (j’aurais d’ailleurs pu également parler de la possibilité de personnaliser les frais de port via webhook).

Et surtout : l’utilisatrice du site est autonome sur la gestion des contenus, la création de nouveaux produits et la gestion des commandes, ce qui est finalement le plus important pour la réussite d’un site e-commerce ! 🛒😊

Enfin, je vous invite à :

• Étudier le code source du projet si vous souhaitez en savoir plus et vous inspirer ;
• Jeter un œil à mon générateur de site statique : Cecil ;
• Consulter le site officiel de Snipcart.

Le contexte

Tout débute par un client. Une entreprise qui gère des documents et des articles sur tout ce qui concerne les textes légaux sur le droit du travail dans les sociétés françaises. Elle existe depuis des décennies et comme toutes les entreprises de média et de documentation, elle produit beaucoup de contenu chaque année.

Au fil des années, par la création de plusieurs sites web, ils ont une accumulation de divers technologies et langages. Le client souhaite aller de l'avant, réduire la dette technique et simplifier toute son infrastructure. Et réduire les coûts si possible.
Il désire donc basculer une bonne partie des sites actuels sur des sites statiques.

Mais avant d'investir de l'énergie humaine et de l'argent dans cette grosse migration, il est indispensable de tester les possibilités des solutions, vérifier que la solution matche bien avec le besoin et les enjeux business.

Choix des générateurs et du CMS Headless

Côté CMS, le choix est déjà arrêté sur Craft CMS. C'est un CMS qui propose une très bonne expérience pour l'édition et surtout, il permet un mode headless avec des fonctionnalités très intéressantes par défaut. On y retrouve notamment: un mode prévisualisation, une API GraphQL et des webhooks. Parfait pour fonctionner avec un site statique.

Le mode prévisualisation offre une bonne expérience aux responsables du contenu. Il est très important pour une complète adoption par l'équipe de pouvoir éditer du contenu et vérifier le rendu immédiatement.

Comme le mode prévisualisation est un prérequis, cela élimine déjà tous les GSS (générateur de site statique) pur HTML (Hugo, Eleventy, etc.) sur lequel on ne bénéficie pas de cette fonctionnalité.
On s'oriente donc sur deux solutions qui offrent la possibilité de fonctionner dans ce mode. C'est donc Nuxt.js et Next.js qui sont retenus.

Gastby aurait pu être utilisé aussi grâce à la nouvelle route API mais nous souhaitons conserver des process de build assez rapide. D'expérience, je connais bien Gatsby et je sais qu'il est le moins performant — ce prototype précède l'annonce de la version 3.0 annoncée comme plus rapide.

Pour être 100% honnête, cet article a mis de côté Gastby au profit de Next.js dès le départ.

Commençons avec Next.js

Nous commençons avec Next.js, et nous avons hâte de découvrir le mode incrémental. La vitesse de publication d'une nouvelle version du site est également un point important. En effet, Next.js a implémenté deux modes intéressants dans les dernières versions : le mode incrémental et la régénération des pages.

Néanmoins ces deux fonctionnalités et le mode prévisualisation ne sont pas disponibles dans le mode entièrement statique (export HTML). Donc pour Next.js, le mode hybride est obligatoire et demande donc un serveur Node.js pour le faire tourner. Pas de soucis aujourd'hui, car Vercel est très accessible en termes d'hébergement et Netlify propose aussi la possibilité de faire tourner Next.js en mode hybride sur son service.

Génération des 11 000 pages et premier blocage

Durant le développement, je travaillais avec un échantillon d'une centaine de pages. Jusque là, tout va bien. Je fais mon développement, j'ajoute les pages, la pagination. Tout fonctionne parfaitement.

Il est temps de tester avec les 11 000 pages. Et là, patatras ! L'API a du mal à suivre les requêtes. Eh oui, 11 000 pages, c'est autant de requêtes pour générer chaque page dans un temps très court. Évidemment, à ce stade, rien n'est optimisé du côté du CMS mais c'est un premier blocage dans la génération des pages.

Pour optimiser les appels vers l'API, je fais un système de cache qui permet d'utiliser les fichiers du cache au lieu d'appeler l'API. Je génère le cache juste avant le build.
Tout fonctionne parfaitement. Les 11 000 pages prennent entre 5 et 8 minutes pour être créées.

La surprise ou le blocage qu'on attendait pas

Bon OK, le temps de build des 11 000 pages est un petit peu long. Si on doit attendre à chaque fois entre 5 et 10 minutes pour avoir une nouvelle version en ligne, ce n’est pas top.

Mais là où nous avons été surpris, c'est quand nous avons testé le déploiement sur Vercel.
Une chose que j'avais oubliée, c'est que 11 000 pages, c'est entre 400 et 500 Mb. Et en upload, ça prend du temps. Beaucoup de temps !

Clairement, au début, j'ai cru a un bug. J'ai coupé le déploiement au bout de 39 minutes. Oui, vous avez bien lu, 39 minutes. Et non, ce n’était pas un bug : j'ai testé sur Netlify, via FTP avec une connexion fibre, ça prend bien une bonne quarantaine de minutes !

Le constat est simple. Impossible de faire du full statique sur un très grand nombre de pages. Le statique ne s'y prête pas du tout. D'autant que les futurs sites doivent atteindre le double, voire le triple en quantité de pages.

La régénération incrémentale à la rescousse

C'est alors que la fonctionnalité de régéneration incrementale nous est apparu comme la solution ultime ! Next.js est en effet capable de générer une page sous forme statique lors de la visite. Générer ou régénérer.

On peut utiliser le mode fallback de la fonction getStaticPaths avec la valeur true ou blocking pour afficher une page non générée lors de la phase de build.

Ensuite, vous donnez un tableau vide comme valeur paths de la fonction getStaticPaths pour ne générer aucune page lors du build. Les pages seront générées à la demande en cas de visite.

Résultat, un temps de génération entre deux et quatre minutes pour un site statique hybride de 10 991 articles !

Cerise sur le gâteau, en utilisant le paramètre revalidate, on peut régénérer la page (temps en secondes) sans relancer un build. Cela veut dire qu'en cas de mise à jour de contenu, il n'est pas nécessaire de relancer un build !

La solution retenue

Bien que Nuxt.js ne propose pas de mode hybride comme Next.js pour le moment, nous sommes allés au bout du prototype. Nous avons fait la même application en mode full statique, car nous ne souhaitons pas utiliser le mode SSR (Server Side Rendering). Et comme vous devez vous en douter, nous avons rencontré les mêmes soucis de temps de build et de déploiement.

Nous avons hâte de découvrir plus en détail la version 3 de Nuxt.js avec le moteur Nitro, qui doit normalement permettre un mode hybride.

Donc pour le moment, Next.js est retenu pour la migration des premiers sites. On utilisera le mode hybride avec une génération des pages à la demande en utilisant un fallback en blocking pour être 100% SEO compatible.

L'idée de générer au build les X derniers articles pour accélérer le chargement des articles récents est évoqué. Nous n’excluons pas que certaines pages très anciennes ne soient peut-être jamais visitées et donc jamais générées.

Finalement, pour remplir le périmètre requis pour le projet : le mode prévisualisation, un processus de publication simple et automatique, aucune gestion de serveur et certaines pages accessibles uniquement par des abonnés ; Next.js semble être pour le moment la meilleure solution.

Prototype privé

Le projet est confidentiel et le code privé. Je ne peux pas fournir les données pour faire des tests.

L’émergence de solutions dédiées au déploiement automatisé de sites statiques est principalement l’apanage de sociétés américaines (Netlify, Vercel, Amazon, Microsoft, Digital Ocean, etc.). La bataille a commencé outre-atlantique pour s’arroger les parts de marché, maintenant que Netlify revendique plus d’un million d’utilisateurs. Il existe des hébergeurs en France, mais pas uniquement dédié à du déploiement automatisé de statique sur des CDNs.

Les offres dédiées Jamstack sont un terreau d’innovation, on a vu ainsi arriver les développements atomiques (une URL pour chaque commit), les intégrations au workflow Git avec mise à disposition d’un lien de prévisualisation lors de la soumission d’une modification sur le dépôt Git, l’ajout simplifié de fonctions Lambda, etc.

Matthias et Hubert nous confient que le statique ne représente pas plus de 5% des projets actuellement chez les hébergeurs plus généralistes, et rappellent que le besoin applicatif représente encore leur cœur de leur activité. Les documentations respectives des ces services sont générées avec Hugo et les deux hébergeurs permettent de pousser via Git. L’automatisation et l’expérience utilisateur n’est pas aussi poussée mais le workflow est similaire. On commence néanmoins à réfléchir à l’amélioration de la DX (Developer Experience), via l’amélioration des outils en ligne de commande dans un premier temps.

L’UX n’est cependant pas le premier facteur de choix des entreprises françaises, qui veulent avant tout pouvoir héberger au plus près de leurs utilisateurs quand elles visent le marché français.

Il est difficile de comparer des services spécialisés qui focalisent leurs efforts sur le frein à l’adoption et qui se content de recopier des fichiers statiques. Les services plus génériques qui gèrent de l’infrastructure et des serveurs ont beaucoup d’autres aspects à gérer, ne serait-ce que pour s’assurer de la sécurité de leur infrastructure.

Hubert précise que des fonctionnalités très prisées comme la prévisualisation automatisée de branche Git sont possibles pour des sites statiques chez Clever Cloud à condition de connaître leur API. Ce genre de fonctionnalité est beaucoup plus complexe à mettre en place pour des applications dynamiques.

Matthias confesse que l’importance de la Developer Experience (DX) est grandissante dans la communauté et que le déploiement de sites Jamstack est quelque chose qu’on voit se développer aussi chez des acteurs majeurs comme Amazon Web Services, Microsoft Azure, Digital Ocean ou Cloudflare récemment.

Il n’est pas aisé de pour nos hébergeurs français plus modestes de rivaliser avec les géants du secteur. Force est de constater q’il est plus facile aujourd’hui de déployer un projet statique chez les "gros". Les outils en ligne de commande, les APIs, les outils de monitoring continuent d’être au centre de l’attention des hébergeurs traditionnels, c’est leur cœur de métier. Il y a bien d’autres paramètres à prendre en compte, comme par exemple la qualité et la réactivité d’un support technique à visage humain, qui accompagnent les clients pour s’assurer de répondre à leurs besoins au plus vite.

Les gros acteurs comme AWS ne sont pas non plus à l’abri de pannes, comme on a pu le voir encore recemment.

Chez Clever Cloud, on peut déjà déployer des fonctions en mode PaaS (Platform as a Service), voire des functions as a service (FaaS) avec support de Web Assembly. Lors du développement de sa documentation en mode Jamstack Alwaysdata a pu expérimenté le besoin en fonctions dynamiques comme l’envoi de mail, un besoin qu’il est toujours possible de combler en développant soi-même la fonction manquante ou en se reposant sur des services et des API externes.

Arnaud souligne qu’il est peut-être plus rassurant pour des entreprises de pouvoir stocker leurs fonctions métier dans son Cloud privé afin de maîtriser son environnement. "La valeur ajoutée de notre métier c’est l’accompagnement et la gestion de la complexité" commente Matthias.

Cette complexité est aussi présente chez des acteurs comme AWS, et on est pas à l’abri pour autant d’un certain degré d’enfermement propriétaire lorsqu’on développe son application pour tourner sur ces plate-formes.

Les problématiques de protections des données, la volonté de ne pas dépendre d’entreprises étrangères qui ne sont pas soumises aux mêmes règles fiscales, des choix éthiques liés aux politiques énergétiques sont autant de critères qui entrent de plus en plus dans le processus de décision.

Le déploiement automatisé systématique c’est très pratique dans plein de cas, mais au prix de quel coût énergétique ? Il reste encore aux différents outils (CMS, plate-forme de déploiement) à donner plus de maîtrise (et de métriques) pour nous permettre de pouvoir estimer correctement l’empreinte énergétique de son workflow et de l’infrastructure utilisée.

Dans ce premier épisode de Génération Statique Frank Taillandier et Arnaud Ligny reçoivent Nicolas Goutay, expert performance web, actuellement développeur chez Orbit, conférencier et organisateur des meetups Jamstack parisiens. Fort d’une expérience avec React et Gatsby, le coût des frameworks JavaScript côté client a poussé Nicolas à privilégier des outils plus légers et plus adaptés aux sites de contenus.

Introduction

Jamstatic a été lancé avec la volonté de partager autour de la génération de sites statiques, nous suivons avec attention cet écosystème depuis près de 2015.

Près de 80 articles ont été publiés depuis sur le site web, plusieurs meetups ont eu lieu notamment sur Paris. Au vu des nombreuses discussions sur le Slack, nous avons décidé de nous essayer au format podcast, afin de partager toujours plus sur le développement de sites web modernes et performants.

Bataille d'égo de CEO

La dernière Jamstack Conf a eu lieu en ligne, on en retiendra surtout la joute verbale entre Matt Biilmann le CEO de Netlify, à l’origine de l’appellation Jamstack, et Matt Mullenweg, le CEO d’Automattic venu défendre WordPress. Richard McManus de The New Stack revient sur cet échange qui ne manquait pas de piquant. Pour se démarquer et faire augmenter l'adoption de leur plate-forme pour le déploiement de sites Jamstack, la stratégie de Netlify est d’attaquer les faiblesses bien connues de WordPress, notamment en matière de maintenance et de sécurité, mais c’était sans compter sur le répondant de Matt Mullenweg qui a très bien défendu l’approche intégrée de WordPress.com, qui répond justement à cette problématique, tout en gardant un CMS open source.

L'API de WordPress pour le blog de Gatsby

Gatsby, un des deux frameworks React majeurs qui permet de générer des applications web, a d’ailleurs annoncé avoir finalement opté pour WordPress en mode headless pour son blog. Ils permettent ainsi à plus de 130 contributeurs de rester dans leur zone de confort, tout en contournant les tarifs de CMS leaders sur le marché comme Contentful, qui dans sa formule actuelle à $489 dollars n’intègre que 25 utilisateurs. Une stratégie moins frontale et plus intelligente de Gatsby qui par la même occasion montre qu’on peut très bien avoir un site React en front tout en gardant son WordPress en back et en requétant les données en GraphQL.

Les annonces de la première Next.js conf

L’autre framework React qui a le vent en poupe c’est Next.js. La première conférence du framework hybride qui permet de faire du statique et du SSR a eu lieu fin octobre.

Beaucoup d’annonces de la part de Vercel, notamment la mise à disposition d’un outil de monitoring de métriques de performance (les Core Web Vitals) mesurées depuis leur CDN auprès des utilisateurs, sans avoir à ajouter la moindre ligne de JS à son site.

Ces métriques poussées par Google permettent de démontrer la performance de sites développés avec Next.js et déployés sur les CDN de Vercel. Ils ont d’ailleurs aussi à l’occasion sorti un premier exemple de site e-commerce et annonce bientôt supporter de s'interfacer avec l'API de Shopify. Quand on connaît l’importance de la performance sur les taux de conversions en e-commerce, on se dit que la bataille va faire rage dans ce secteur. On notera que la plate-forme de déploiement Gatsby Cloud permet aussi de mesurer son score Lighthouse standard, des indicateurs "un peu fourre-tout", selon Nicolas.

Également développé en partenariat avec les équipes de Google, Next.js dispose maintenant d’un composant Image qui va grandement aider les développeurs dans la gestion des images responsive pour les servir dans des formats optimisés sur leurs CDN. Gatsby dispose déjà d’un composant image qui retaille les images au build et les charge automatiquement au scroll. On voit que la concurrence est rude entre les deux frameworks et que c’est la performance ressentie côté utilisateur qui est moteur dans ces innovations. C’est une très bonne chose pour le web et pour faciliter le travail les développeurs qui ont maintenant à leur disposition des abstractions dont le but est d’éviter de servir des images non optimisées.

Devant la popularité croissante de Next.js, Netlify n’a d’autre choix pour retenir les développeurs que de devoir supporter le SSR et le mode preview via des fonctions lambda. Ils offrent désormais quelques cours en ligne dont un pour apprendre les bases de Next.js. Le framework semble au centre de toutes les attentions en ce moment. L'enjeu n'est pas négligeable pour Netlify, puisque Vercel est un concurrent direct. Nous parlerons plus en détail du déploiement et de l'hébergement de sites statiques dans le prochain épisode.

Gatsby simplifie la génération de pages

Gatsby de son côté n'est pas en reste et continue de progresser, le framework vient d'annoncer une nouvelle API de routing basée sur le système de fichiers… à la Next.js ou Nuxt.js. Votre fichier /about.js sera servi en tant que /about/. Nicolas précise que Gatsby demande un peu plus d'investissement initial mais que le résultat final sera similaire.

Nuxt.js de plus en plus statique

Nuxt.js, est désormais capable de générer un site entièrement statique et permet de requêter le système de fichiers grâce à son API de contenu très simple d’utilisation, avec rechargement à chaud, insertion de composants Vue dans le Markdown, un queryBuilder, une recherche textuelle, et bien plus…

Le projet initié par les deux frères Chopin, Alexandre et Sébastien, a annoncé sa première levée de fonds et propulse maintenant des sites majeurs comme lequipe.fr. On se réjouit de la progresssion du framework Vue.js.

Stocker ses contenus sous forme de fichiers Markdown, JSON, YAML, est très courant et c’est une bonne chose que tous les framework JS continuent de faciliter le travail à ce niveau-là. Frank rappelle que des CMS basés sur Git comme Forestry interagissent avec votre dépôt et proposent une interface de rédaction épurée ainsi que la possibilité de modéliser ses contenus, via du front matter ou des fichiers de données. Une flexibilité vraiment appréciable, et accessible au plus grand nombre.

Des frameworks bien pratiques, de plus en plus versatiles, capables de travailler avec des fichiers locaux comme avec des API distantes. Ces frameworks JavaScript facilitent le développement par composition, ce paradgime explique en partie leur adoption de plus en plus massive.

Hugo de mieux en mieux outillé pour le JavaScript

Enfin Hugo, le générateur de loin le plus rapide pour transformer ses fichiers source en site web, continue d'intégrer des outils issus de l'écosystème JavaScript, après la transpilation via Babel, la gestion de dépendances npm, on peut aussi maintenant empaqueter son JavaScript à la vitesse de la lumière avec esbuld. Les développeurs peuvent découper leurs projets en modules réutilisables et bénéficier d'un bundler lui aussi bien plus rapide que webpack ou parcel.

Tailwind 2.0

La version 2.0 de Tailwind CSS est sortie.Le site fait peau neuve pour l'occasion, il est développé avec Next.js, déployé sur Vercel avec une recherche propulsée par Algolia.

Eleventy en route vers le million de téléchargements

De son côté, mine de rien Eleventy le générateur volontairement simple de Zach Leatherman se rapproche doucement du million de téléchargements npm, l’engouement est réel chez les développeurs front adeptes des choses bien faites, et souhaitant garder un contrôle total sur le JavaScript livré. C'est d'ailleurs ce qui a plu à Nicolas Goutay, qui détaille l'approche plus légére privilégiée pour développer le nouveau site d'Orbit, avec Eleventy, Tailwind CSS et Alpine.js.

Comment ne pas faire subir le coût des frameworks à ses visiteurs ?

Dans son article sur https://orbit.love/blog/towards-a-lightweight-jamstack (prochainement disponible en français), Nicolas rappelle que l'expérience de développement proposée par les frameworks JavaScript se fait au détriment de la performance expérimentée par vos visiteurs.

Nicolas a longtemps utilisé React pour beaucoup de projets en agence. Très attentif à la performance finale ressentie par les visiteurs, Nicolas sait que cela demande d'implémenter beaucoup de bonnes pratiques: la gestion des images, l'implémentation de Service Workers, le rendu côté serveur. "Encore faut-il en avoir le temps, l'expertise et la connaissance" précise Nicolas. Gatsby s'est positionné comme un framework React qui peut se connecter à n'importe quelle source de données via son API GraphQL et qui implémente les bonnes pratiques de webperf par défaut, générant une Progressive Web App en sortie.

Gatsby peut aussi précharger les pages dès qu'un visiteur s'apprête à cliquer sur un lien, ce qui va donner une impression d'instantanéité du chargement de la page. C'est ce parti-pris sur la performance qui a plu à Nicolas, qui fait que le développeur est incité à servir un site optimisé.

Nicolas rappelle néanmoins que la taille du JavaScript livré sur le site a un impact énorme sur l'expérience utilisateur (et de plus en plus sur le SEO). Même 30 kilobits de JavaScript vont impacter le temps que met un site à être interactif. Cela peut se mesurer en terme de “clics rageux” (rage clicks) où les utilisateurs croient pouvoir interagir avec la page qui semble chargée, alors que le navigateur est toujours en train d'interpréter le code JavaScript embarqué.

Tout le monde ne dispose pas du dernier modèle de téléphone ultra-puissant et un site comme celui du Washington Post peut mettre près de 40 secondes à s'afficher sur un téléphone d'entrée de gamme.

Even worse, the Washington Post.

This video is 30 seconds long, because that's how long it took the Redmi to load an article. The iPhone did it in 1-2 seconds. pic.twitter.com/gfaK676SHo

— Josh W. Comeau 🎃 (@JoshWComeau) October 31, 2020

On surveillera le First Input Delay dans ses métriques, même si comme le dit Nicolas "cela reste une approximation synthétique et imparfaite". Idéalement testez sur autre chose que le dernier iPhone avec une connexion 4G qui dépote.

Tout le monde ne maintient pas une application comme Facebook, Airbnb, ou Twitter. Si pour les applications, l'utilisation de frameworks ne fait plus débat, elle demande donc de peser le pour et le contre quand il s'agit de développer des sites de contenu avec peu d'interactivité côté client.

Malgré son appétence pour React, Nicolas a décidé de s'affranchir de ce coût non négligeable pour les utilisateurs finaux et s'est intéressé à Eleventy, pour se recentrer sur le contenu, l'accessibilité et la performance.

Les langages de templating proposés par les générateurs sont néanmoins moins versatiles que React ou Vue. On utilisera des fichiers partiels pour tendre vers un développement par composition, mais c'est une expérience de développement différente.

Le changement de philosophie peut se résumer à qui pilote, en React c'est le JavaScript, avec Alpine.js ce sont les fichiers HTML, dans lequel on ajoute des attributs qui permettent de piloter l'interactivité.

Le code du site d'Orbit est open source, vous pouvez donc aller voir comment Nicolas a utilisé Alpine pour ajouter de l'interactivité à certaines parties de l'interface comme la navigation, l'inscription à la newsletter ou les extraits de code.

L'approche est très rafraichissante, elle permet de se recentrer sur une des primitives du web, le HTML, et de pouvoir soigner la qualité du code servi à l'utilisateur — Nicolas Goutay

Mozilla adopte cette approche légère sur https://extensionworkshop.com/.

On notera que certains sites Eleventy utilisent les Web Components et que GitHub a développé un framework pour embarquer des Web Components dans les applications Ruby on Rails. Là encore, il faudrait dédier une émission complète sur ce sujet. C'est quelque chose à surveiller de près.

Il est possible d'utiliser Vue avec Eleventy, c'est d'ailleurs ce qu'a fait Zach Leatherman sur netlify.com.

Le statique moderne est toujours en plein évolution, beaucoup d'outils dans le seul but de produire des sites à la fois modernes, accessibles et performants.

La discussion continue sur Slack et Twitter…

Intervenants

• Frank Taillandier, Customer Success Manager chez Forestry.io, initiateur de la communauté jamstatic.fr
• Arnaud Ligny, consultant technique web & e-commerce, créateur du générateur de site statique Cecil
• Nicolas Goutay, développeur web chez Orbit, organisateur des meetups Jamstack Paris, et de la conférence francophone We Love Speed

Le temps de compilation d’un site est un critère parmi tant d’autres. Si ces premiers tests comparatifs de performance pure ne sont pas représentatifs de ce que à quoi vous pouvez vous attendre dans le contexte de vos projets, ils vous donneront quand même un premier ordre d’idée. Partir sur un framework a un coût en temps de compilation. Jekyll n’est intrinsèquement pas plus lent qu’Eleventy, tout dépend de votre projet. Gatsby sera le plus pénalisant sur de gros sites, Next.js est le framework qui s’en sort le mieux, et Hugo l’emporte haut la main et demeure intouchable dès qu’il s’agit de vitesse de compilation.

Il y a tant de générateurs de sites statiques (SSG). C'est fatiguant de devoir décider par où commencer. Bien qu'une abondance d'articles utiles puisse aider à se repérer dans les options (populaires), ils ne facilitent pas la décision comme par magie.

Je me suis efforcé de faciliter cette décision. Un de mes collègues a construit une fiche d'évaluation du générateur de site statique. Elle donne un très bon aperçu de nombreux choix de SSG populaires. Ce qui manque, c'est la façon dont ils fonctionnent réellement dans la pratique.

Tous les générateurs de sites statiques ont en commun le fait qu'ils prennent des données en entrée, les font passer par un moteur de template et produisent des fichiers HTML. Nous appelons généralement ce processus « la compilation ».

Il y a trop de nuances, de contexte et de paramètres à considérer pour pouvoir comparer les performances des différents générateurs pendant le processus de compilation pour les afficher sur une feuille de calcul - et c'est ainsi que commence notre test de comparaison des temps de compilation des générateurs de sites statiques les plus courants.

Il ne s'agit pas seulement de déterminer quel générateur est le plus rapide. Hugo a déjà cette réputation. Je veux dire, ils l'écrivent sur leur site web - Le framework le plus rapide au monde pour le développement de sites web - donc ça doit être vrai !

Il s'agit d'une comparaison des temps de compilation de plusieurs SSG populaires et, plus important encore, d'analyser en détail ces temps de compilation. Choisir aveuglément le plus rapide ou discréditer le plus lent serait une erreur. Voyons ensemble pourquoi.

Les tests

Le processus de test est conçu pour démarrer de manière simple - avec seulement quelques générateurs populaires et un format de données simple. Une base sur laquelle on pourra s'appuyer pour tester d'autres générateurs et affiner les données. Pour le moment, le test comprend six des générateurs les plus populaires :

• Eleventy
• Gatsby
• Hugo
• Jekyll
• Next
• Nuxt

Chaque test utilise l'approche et les conditions suivantes :

• La source de données pour chaque génération est constituée de fichiers Markdown avec un titre front matter et un corps de texte (contenant trois paragraphes de contenu) générés de manière aléatoire.
• Le contenu ne contient pas d'images.
• Les tests sont exécutés en série sur une seule machine, ce qui rend les valeurs réelles moins pertinentes que la comparaison relative entre les lots.
• La sortie est un texte en clair sur une page HTML, exécutée par le starter par défaut, en suivant le guide de démarrage respectif de chaque générateur.
• Chaque test est un essai à froid. Les caches sont effacés et les fichiers Markdown sont régénérés pour chaque test.

Ces tests sont considérés comme des tests de référence. Ils utilisent des fichiers Markdown de base et produisent du HTML non stylisé dans la sortie intégrée.

En d'autres termes, le résultat est techniquement un site web qui pourrait être déployé pour la production, bien que ce ne soit pas vraiment un scénario de la vraie vie. Cependant, cela permet une première comparaison entre ces frameworks. Les choix que vous faites en tant que développeur utilisant l'un de ces frameworks impacteront les temps de compilation de différentes manières (généralement en les ralentissant).

Par exemple, contrairement au monde réel, nous testons des générations à froid. Dans la vraie vie, si vous avez 10 000 fichiers Markdown comme source de données et que vous utilisez Gatsby, vous allez utiliser le cache de Gatsby, ce qui réduira considérablement les temps de génération (jusqu'à près de la moitié).

On peut en dire autant des générations incrémentielles, qui sont liées à des passages à chaud par rapport aux passages à froid, dans la mesure où elles ne génèrent que les fichiers qui ont changé. Pour le moment, nous ne testons pas l'approche incrémentale dans ces tests.

Les deux types de générateurs de sites statiques

Avant cela, considérons d'abord qu'il existe en réalité deux types de générateurs de sites statiques. Appelons-les basique et avancé.

• Les générateurs de base (qui ne sont pas basiques sous le capot) sont essentiellement une interface en ligne de commande (CLI) qui prend des données en entrée et produit du HTML, et peut souvent être étendue pour traiter divers ressources (ce que nous ne faisons pas ici).
• Les générateurs avancés offrent quelque chose en plus de la sortie d'un site statique, comme le rendu côté serveur, des fonctions serverless et l'intégration d'un framework. Ils ont tendance à être configurés pour être plus dynamiques par défaut.

J'en ai délibérément choisi trois de chaque type dans ce test. Les trois premiers à tomber dans le panier de base sont Eleventy, Hugo et Jekyll. Les trois autres sont basés sur un framework frontend et sont livrés avec des quantités d'outils variés. Gatsby et Next sont bâtis sur React, tandis que Nuxt est construit par dessus Vue.

Mon hypothèse

Appliquons la méthode scientifique à cette approche car la science est amusante (et utile) !

Mon hypothèse est que si un générateur est avancé, alors il fonctionnera moins vite qu'un générateurs de base. Je pense que les résultats en témoigneront, car les générateurs avancés ont davantage de coûts fonctionnels que les générateurs de base. Ainsi, il est probable que nous voyons les deux groupes de générateurs - de base et avancés - regroupés ensemble, dans les résultats avec des générateurs de base se déplaçant beaucoup plus rapidement.

Permettez-moi de développer un peu plus cette hypothèse.

Linéaire et rapide

Hugo et Eleventy domineront les tests avec des volumes de données plus petits. Ce sont des processus (relativement) simples dans Go et Node.js, respectivement, et leur temps de génération devrait le refléter. Bien que les deux générateurs soient moins rapides au fur et à mesure que le nombre de fichiers augmente, je m'attends à ce qu'ils restent en tête, bien que Eleventy soit peut-être un peu moins linéaire à l'échelle, simplement parce que Go a tendance à être plus performant que Node.

Lent, puis rapide, mais toujours lent

Les générateurs avancés, ou liés à un framework, démarreront et sembleront lents. Je soupçonne qu'un test sur fichier unique contient une différence significative - des millisecondes pour les tests de base, contre plusieurs secondes pour Gatsby, Next et Nuxt.

Les générateurs basés sur un framework font chacun appel à webpack pour la génération, ce qui entraîne une quantité importante de frais fonctionnels, quelle que soit la quantité de contenu qu'ils traitent. C'est le contrat tacite que nous passons en utilisant ces outils (nous y reviendrons plus tard).

Mais, à mesure que nous ajouterons des milliers de fichiers, je pense que nous verrons l'écart entre les deux catégories se réduire, même si le groupe avancé restera plus loin derrière d'une manière significative.

Dans le groupe des générateurs avancés, je m'attends à ce que Gatsby soit le plus rapide, uniquement parce qu'il n'a pas de composant côté serveur dont il faut se soucier - mais c'est juste une intuition. Next et Nuxt ont peut-être optimisé cela au point que, si nous n'utilisons pas cette fonctionnalité, cela n'affectera pas les temps de génération. Et je pense que Nuxt battra Next, uniquement parce que Vue a un peu moins d'impact que React.

Jekyll : le vilain petit canard

Ruby est tristement célèbre pour sa lenteur. Il est devenu plus performant avec le temps, mais je ne m'attends pas à ce qu'il rivalise avec Node, et certainement pas avec Go. Et pourtant, dans le même temps, il n'a pas le bagage d'un framework.

Au début, je pense que nous verrons Jekyll comme étant assez rapide, peut-être même impossible à distinguer de Eleventy. Mais au fur et à mesure que nous arriverons aux milliers de fichiers, la performance en prendra un coup. Mon sentiment est qu'il peut y avoir un moment où Jekyll devient le plus lent des six. Nous allons pousser jusqu'à la barre des 100 000 pour en être sûrs.

Les résultats sont arrivés

Le code de ces tests se trouve sur GitHub. Il y a aussi un site qui montre les résultats relatifs.

Après de nombreuses itérations pour établir les bases sur lesquelles ces tests pourraient être effectués, j'ai fini par réaliser une série de 10 tests dans trois ensembles de données différents :

• Basique : Un seul fichier, pour comparer les temps de génération de base
• Petits sites : De 1 à 1024 fichiers, en doublant le nombre de fichiers à chaque fois (pour faciliter la détermination de l'échelle linéaire des générateurs)
• Grands sites : De 1 000 à 64 000 fichiers, en doublant le nombre de fichiers à chaque passage. Au départ, je voulais aller jusqu'à 128 000 fichiers, mais j'ai rencontré des problèmes avec certains des frameworks. 64 000 ont fini par suffire pour donner une idée de la manière dont les différents acteurs allaient évoluer avec des sites toujours plus importants.

Synthèse des résultats

Certains résultats m'ont surpris, alors que d'autres étaient prévisibles. Voici les points les plus importants :

• Comme prévu, Hugo est le plus rapide, quelle que soit la taille du site. Ce à quoi je ne m'attendais pas, c'est qu'il loin devant tous les autres générateurs, même sur une génération de base (il n'est pas non plus linéaire, mais nous reviendrons sur ce point.)
• Les groupes de générateurs de base et avancés sont assez évidents quand on regarde les résultats pour les petits sites. C'était prévu, mais il était surprenant de voir que Next est plus rapide que Jekyll avec 32 000 fichiers, et plus rapide que Eleventy et Jekyll avec 64 000 fichiers. Il est également surprenant que Jekyll soit plus rapide que Eleventy avec 64 000 fichiers.
• Aucun des générateurs ne suit une échelle linéaire. Next.js est celui qui s'en rapproche le plus cependant. Hugo donne l'apparence d'être linéaire, mais c'est seulement parce qu'il est beaucoup plus rapide que les autres.
• Je pensais Gatsby serait le plus rapide parmi les générateurs avancés, et je me suis dit que c'était celui qui se rapprocherait le plus des générateurs de base. Mais Gatsby s'est avéré être le plus lent, produisant la courbe la plus exponentielle.
• Bien que cela ne soit pas spécifiquement mentionné dans l'hypothèse de départ, l'échelle des différences était plus grande que je ne l'aurais imaginé. Pour un seul fichier, Hugo est environ 170 fois plus rapide que Gatsby. Mais à 64 000 fichiers, il est plus proche - environ 25 fois plus rapide. Cela signifie que, si Hugo reste le plus rapide, il a en fait la forme de croissance exponentielle la plus spectaculaire parmi le lot. Il semble simplement linéaire à cause de l'échelle du graphique.

Qu'en conclure ?

Lorsque j'ai partagé mes résultats avec les créateurs et les mainteneurs de ces générateurs, j'ai généralement eu la même réponse. Pour paraphraser :

Les générateurs qui prennent plus de temps à générer en font davantage. Ils apportent plus aux développeurs, alors que les générateurs plus rapides (c'est-à-dire les outils "de base") concentrent leurs efforts en grande partie sur la conversion des modèles en fichiers HTML.

Nous sommes d'accord.

Pour résumer : La mise à l'échelle des sites Jamstack est difficile.

Les défis qui se présenteront à vous, développeur, au fur et à mesure que vous que la taille de votre site augmentera, varieront en fonction du site que vous essayez de construire. Ces données ne sont pas saisies ici car elles ne peuvent l'être - chaque projet est unique d'une certaine manière.

Ce qui compte vraiment, c'est votre niveau de tolérance à l'attente en échange de l'expérience de développement.

Par exemple, si vous allez générer un grand site à forte charge d'images avec Gatsby, vous allez le payer avec des délais de génération plus longs, mais on vous donne aussi un immense ensemble de plugins et une base sur laquelle construire un site solide, organisé et basé sur des composants. Faites de même avec Jekyll, et il vous faudra beaucoup plus d'efforts pour rester organisé et efficace tout au long du processus, même si vos générations peuvent être plus rapides.

Au boulot, je développe généralement des sites avec Gatsby (ou Next, selon le niveau d'interactivité dynamique requis). Nous avons travaillé avec le framework Gatsby pour construire un noyau sur lequel nous pouvons rapidement créer des sites web très personnalisés, riches en images, avec une abondance de composants. Nos temps de génération augementent au fur et à mesure que les sites se développent, mais c'est à ce moment que nous devenons créatifs en mettant en place des micro frontend, en déchargeant le traitement des images, en mettant en place des aperçus de contenu, ainsi que de nombreuses autres optimisations.

De mon côté, je préfère travailler avec Eleventy. En général, je ne fais qu'écrire du code, et mes besoins sont beaucoup plus simples. (J'aime me considérer comme un bon client pour moi-même.) J'ai le sentiment d'avoir plus de contrôle sur les fichiers en sortie, ce qui me permet d'obtenir plus facilement les performances de 💯 côté client, et c'est important pour moi.

En fin de compte, il ne s'agit pas seulement de ce qui est rapide ou lent. Il s'agit de savoir ce qui fonctionne le mieux pour vous et combien de temps vous êtes prêt à attendre.

Conclusion

Ce n'est que le début ! L'objectif de cet effort était de créer une base sur laquelle nous pouvons, ensemble, comparer les temps de génération relatifs des générateurs de sites statiques les plus populaires.

Quelles sont vos idées ? Quels sont les faiblesses du processus actuel ? Que pouvons-nous faire pour améliorer ces tests ? Comment pouvons-nous les rendre plus proches des scénarios du monde réel ? Devrions-nous transférer le traitement sur une machine dédiée ?

Voilà les questions auxquelles j'aimerais que vous m'aidiez à répondre. Parlons-en.

Nicolas Hoizey partage ici sa vision de la Jamstack et le fait que celle-ci n’est performante que si vous faites véritablement en sorte qu’elle le soit. À noter que depuis la parution de son article, Netlify a supprimé les majuscules de Jamstack afin de moins insister sur l'acronyme à l'origine de cette appelation qui suscite encore trop souvent une incompréhension. Encore heureux qu'en 2020 on puisse encore générer du HTML sans passer par un framework JS !

La Jamstack se présente souvent comme un excellent moyen de fournir des sites performants. C'est même le premier avantage répertorié sur jamstack.wtf, un guide¹ pour "comprendre le concept de Jamstack simplement, de manière à encourager d'autres développeurs à adopter ce workflow". Mais trop de sites Jamstack sont encore trop lents.

Vous avez peut-être vu les diatribes fréquentes d'Alex Russell à propos de Gatsby :

Looking across the full set of traces, modern Gatsby seems to produce pages that take 2-3x as long as they should to become interactive.

This is not OK. Gatsby/NPM/React regressively tax access to content.

In less generous moments, I'd go as far as to say it's unethical.

— Alex Russell (@slightlylate) October 17, 2019

Gatsby est une cible facile (parmi tant d'autres) car il n'est actuellement pas optimisé pour être performant par défaut, malgré ce qui est présenté. Il est possible de corriger cela, notamment avec ce plugin, et je pense que de bons développeurs React peuvent améliorer les choses, mais cela devrait être le cas par défaut, et non après coup.

Eleventy est très différent, comme Zach Leatherman nous le rappelle dans Eleventy’s New Performance Leaderboard :

Eleventy n'effectue aucune optimisation particulière pour rendre vos sites plus rapides. Cela ne vous empêchera pas de créer un site lent. Mais Eleventy n’ajoute rien qui ralentisse votre site.

Le problème avec la plupart des sites Jamstack lents est qu'ils chargent tout un tas de JavaScript. N'oubliez pas que tout code JavaScript ajouté doit être envoyé au navigateur, qui nécessitera davantage de ressources pour le traiter. Cela impactera inéxorablement les performances.

Parfois, la génération côté serveur suffit pour obtenir des données depuis une API et servir le HTML à tous les visiteurs, ce qui est nettement plus performant.

Par exemple, swyx a écrit Clientside Webmentions à propos de l’implémentation de Webmention avec Svelte. Tout article faisant la promotion de Webmention et facilitant son adoption est le bienvenu ! Mais même si c’est une bonne démo de Webmention et Svelte, je ne recommanderais pas de le faire côté client.

Privilégier le côté serveur

Je préfère le faire sur le serveur.

Cela permet :

• D'appeler l’API webmention.io seulement au moment de générer le site, ce qui devrait être moins fréquent que la consultation des pages par les visiteurs.
• De mettre en cache le résultat des requêtes à webmention.io et l’horodatage de la dernière, afin que la prochaine requête demande uniquement les nouvelles webmentions.

Cela sollicite moins webmention.io, avec une unique requête simple par génération, alors que le client effectue une requête bien plus volumineuse (voire plusieurs, avec pagination) pour chaque page vue.

Par exemple :

• Mon site web a reçu 75 Webmentions en avril 2020. Je l’ai probablement généré une centaine de fois durant la même période, ce qui correspond à 100 requêtes à Webmention.io avec des réponses peu volumineuses.
• Pendant la même période, 3 746 pages de mon site web ont été vues (sous estimé, je continue à utiliser Google Analytics 🤷‍♂️), ce qui équivaudrait à 3 746 requêtes à Webmention.io avec des réponses volumineuses.

Utiliser la génération côté serveur pour récupérer les Webmentions offre de multiples avantages :

• La performance pour les utilisateurs est largement meilleure, avec du HTML déjà compilé sur le serveur et servi de manière statique.
• Beaucoup moins d’appels d’API, ce qui requiert beaucoup moins de temps de compilation et d’énergie.
• Tout le monde devrait savoir qu'Aaron Parecki propose l’impressionnant service webmention.io gratuitement, et la majorité des utilisateurs de Webmention l’utilisent aujourd’hui, et ne pas surcharger son API donne bien meilleure conscience.

Améliorer le côté client, s’il est indispensable

Si vous savez que vous recevez beaucoup de Webmentions très utiles que vous devez afficher à vos visiteurs, vous pouvez améliorer la liste générée côté serveur via le côté client.

Mais rappelez-vous que chaque JavaScript ajouté à la page a un coût, donc les quelques Webmentions supplémentaires doivent être vraiment utiles.

Alors, au lieu de le faire pour chaque page vue :

• Essayez d’attendre un peu après la génération du site avant de faire les appels API côté client. Garder l’horodatage de génération du site côté client via JavaScript, et attendez une heure, une journée, en fonction de la fréquence des Webmentions. Vous pouvez même utiliser l’« âge » de la page pour moins requêter webmention.io pour le contenu plus ancien, qui reçoit probablement moins de Webmentions, comme l’a fait Aaron Gustafson pour les appels côté serveur dans son plugin Jekyll.
• Gardez une trace des appels API, pour un utilisateur, dans le localStorage ou l’IndexDB, afin que vous ne répétiez pas ces appels tout de suite. Vous pouvez même utiliser un Service Worker pour mettre en cache les requêtes et leur horodatage.

Les appels à l’API uniquement côté client ont parfois plus de sens

Je suis d’accord que les Webmentions ne sont pas le cas d’usage le plus complexe pour expliquer que la plupart du temps vous devez appeler les API côté serveur au moment de la génération plutôt que côté client :

• Les Webmentions à afficher sont les mêmes pour tous les visiteurs.
• Ne pas générer les plus récentes n’est sûrement pas un problème.

Alors oui je comprends bien que de nombreux autres cas d’usage rendent les appels côté client nécessaires, ou meilleurs que ceux côté serveur.

Ce que je dis c’est que ça ne devrait pas être le cas par défaut.

Promouvoir la AJMstack Mstack

C’est aussi quelque chose que je n’aime pas vraiment dans la tendance actuelle de la Jamstack, promouvoir JavaScript et les API bien plus que le balisage (NDT : « balisage » peut se traduire par « Markup » en anglais).

Voici pour l’exemple ce que vous pouvez voir sur jamstack.wtf (simplifié) :

Comme suggéré par Yann, j’aimerais commencer par utiliser cette meilleure présentation :

Cela rend plus évident qu’il s’agit d’une pile de choses, très utile pour une « pile » (NDT : « stack » peut être traduit « pile » en français).

Mais j’aimerais suggérer cette modification :

Bien sûr, cela se lit AJMstack au lieu de Jamstack, donc je parie que je n’aurais pas de succès dans la promotion… 🤷‍♂️

Mais au final ça semble plus adéquat, et cela montre que JavaScript fait le lien entre les APIs et le balisage.

Cela permet de présenter cela comme une excellente plate-forme d’amélioration progressive, car nous pouvons commencer avec du bon vieux (ai-je entendu « ennuyeux » ?) HTML…

Voici la Mstack :

Assurez-vous déjà que cette « couche » soit au top, et ensuite améliorez-la avec du JavaScript et des APIs au besoin.

Cet article vous propose de vous mettre la main à la pâte et après avoir vu comment importer un ou plusieurs modules dans votre site, nous développerons notre propre module!

Initialiser votre projet en tant que module

Pour initialiser votre projet en tant que module, vous devez faire reférence à une URL de dépôt Git.

Partons du principe que votre projet Hugo est déjà sur GitHub à l'adresse https://github.com/chez-moi/mon-depot.

Dans un terminal, à la racine de votre projet, lancez :

hugo mod init github.com/chez-moi/mon-depot

☝️ Cette commande génère un fichier go.mod à la racine du projet. Il ressemble à quelque chose comme :

module github.com/chez-moi/mon-depot

go 1.15

Un fichier go.sum est également généré, mais ne nous en préoccupons pas pour le moment.

Importer un dépôt distant

Prenons un exemple simple et ajoutons à notre projet les icônes mis à disposition par l'équipe de Bootstrap dans le dépôt https://github.com/twbs/icons.

La déclaration se fait dans votre fichier de configuration à l'aide du mot clé module et de sa liste d'imports:

module:
  imports:
    - path: github.com/twbs/icons

Maintenant lancez la commande hugo et vous pouvez remarquer que le fichier go.mod comporte une nouvelle ligne:

module github.com/chez-moi/mon-depot

go 1.15

require github.com/twbs/icons v1.0.0 // indirect

C'est bien, mais cela ne dit pas à Hugo ce qu'il doit faire de ces fichiers.

Grâce à la clé mounts, relative à notre import de Bootstrap, donnons plus de directives à Hugo :

module:
  imports:
    - path: github.com/twbs/bootstrap
      mounts:
        - source: icons
          target: assets/icons

Comme pour les imports, on peut utiliser plusieurs mounts, pour le moment nous contenterons d'un seul avec les paramètres suivants:

• le paramètre source désigne la location des fichiers dans le dépôt distant. Ici nous voulons juste le réperetoire icons situé à la racine du dépôt.
• le paramètre target désigne l'endroit où Hugo doit monter les fichiers dans notre systéme de fichier Hugo unifié.

Une fois le montage effectué, nous pouvons accéder aux icônes SVG situées dans ce dossier comme à n'importe quel autre fichier de notre projet :

{{ with resources.Get "icons/cart.svg" }}
  <div class="w-4 fill-current">
    {{ .Content | safeHTML }}
  </div>
{{ end }}

Et voilà !

Nous pouvons afficher cette icône de panier SVG sans avoir à la recopier dans notre projet.

Dans l'éventualité où vous voulez personnaliser cette icône de panier nous pouvons compter sur le système de fichiers unifié d'Hugo !

Tout ce que nous avons à faire est de créer un fichier d'icône du même nom et de le placer au même emplacement assets/icons/cart.svg dans notre projet pour qu'il soit utilisé à la place de l'icône de panier de Bootstrap.

Ou si nous voulions, nous pourrions aussi importer le fichier d'un autre dépôt distant pour une simple icône 🤪 :

- path: github.com/refactoringui/heroicons
    mounts:
    - source: src/solid/shopping-cart.svg
      target: assets/icons/cart.svg
- path: github.com/twbs/icons
    mounts:
    - source: icons
      target: assets/icons

☝️ Ici nous importons deux dépôts, chacun avec son propre point de montage.

Mise à jour

Et si le dépôt distant est mis à jour ? Par défaut lors du premier import Hugo va télécharger la dernière version publiée, à défaut le commit de tête de la branche par défaut. C'est pour cela qu'Hugo a ajouté v1.0.0 à la fin du require dans le fichier go.mod.

Si github.com/twbs/icons sort une version v1.1.0 et que vous souhaitez faire la mise à jour :

hugo mod get -u github.com/twbs/bootstrap

Cette commande mettra votre fichier go.mod à jour avec la dernière version publiée.

Cibler une version

Si maintenant vous souhaitez utiliser une version bien précise d'un dépôt Git, ciblez son tag (prenons un autre dépôt pour cet exemple):

hugo mod get github.com/twbs/bootstrap@v3.4.1

Si vous souhaitez utiliser un commit bien précis, pointez vers son hash avec @ comme ceci :

hugo mod get github.com/twbs/bootstrap@394812b61d4dc80bfb2e090de925ae0dfc4cc29b

Créer un module Hugo

Bon c'est intéressant de savoir importer n'importe quel dépôt et d'intégrer ses fichiers dans notre projet, mais la vraie puissance vient de l'utilisation de modules Hugo complets, qui peuvent gérer des fichiers de modèles, des assets, des fichiers de données, voire des fichiers de contenu !

Et quel meilleur moyen d'apprendre que de créer nous-mêmes notre propre module ?

Créons pour l'exemple un petit module d'icônes. Pour cela nous voulons :

1. Importer les fichiers SVG d'un dépôt distant
2. Créer une page qui liste toutes les icônes disponibles
3. Utiliser notre propre fichier partiel icon pour faciliter l'affichage de n'importe quelle icône du projet.

Créons d'abord un dossier sur notre ordinateur et nommons-le assets/hugo-icons pour éviter tout conflit avec un dossier assets/icons existant.

1. Les imports

Nous avons tout d'abord besoin de lister les imports des fichiers de notre module dans un fichier config.yaml.

En effet, n'importe quel projet Hugo, que ce soit un site web, un thème ou un composant peut importer d'autres modules ou d'autres dépôts. Il n'y a pas de limite dans l'arborescence de dépendances, les modules sont une vraie de gestion de dépendences !

Nos imports seront très similaires à ce que nous avons vu plus haut, la seule différence est que nous importons les fichiers dans un dossier différent pour éviter tout conflit :

# config.yaml
module:
  imports:
    - path: github.com/twbs/bootstrap
      mounts:
        - source: icons
          target: assets/hugo-icons/icons

2. La page de listing

Pour cela nous avons besoin de deux fichiers :

1. Un fichier de contenu ;
2. Un fichier de modèle pour qu'Hugo puisse effectuer le rendu de notre fichier.

Puisque nous utilisons la directive mounts, nous n'avons pas besoin de nous respecter l'arborescence classique d'un projet Hugo. Nous sommes libres d'organiser les fichiers de notre module comme bon nous semble :

• page/layout.html
• page/content.md

Mettons à jour notre fichier config.yaml, vous pouveez noter que les paramètres mounts se situent à la racine de notre map module.

Les points de montage ne sont en effet pas réservés aux seuls imports. Vous pouvez attribuer des points de montage au module en question à l'aide de sa propre directive mounts :

# config.yaml
module:
  mounts:
    - source: page/index.md
      target: content/hugo-icons-listing.md
      lang: en
    - source: page/template.html
      target: layouts/_default/hugo-icons-listing.html
  imports: [...]

Nos deux fichiers eux ressemblent à ça :

# page/index.md
---
title: Liste des icônes
layout: hugo-icons-listing
---

{{/* page/template.html */}}
{{ define "main" }}
  {{ range resources.Match "hugo-icons/icons/*.svg" }}
    <div style="fill:currentColor;width:3rem;margin:1rem 0">
    {{ .Content | safeHTML }}
    </div>
  {{ end }}
{{ end }}

3. Le fichier partiel

Plaçons notre fichier dans partials/icon.html et déclarons un nouveau point de montage :

# config.yaml
module:
  mounts:
    [...]
    - source: partials
      target: layouts/partials/hugo-icons
  imports:
  [...]

Ici nous choississons de monter notre fichier dans un répertoire nommé pour éviter tout conflit avec un fichier partiel icon existant. Les utilisateurs pourront ainsi appeler {{ partial "hugo-icons/icon" "cart" }} en toute sécurité.

Notre fichier partiel :

{{/*
  icon
  Affiche l'icône correspondant à la chaîne passée comme contexte

  @author @regisphilibert

  @context String (.)

  @access public

  @example - Go Template
    {{ partial "hugo-icons/icon" "cart" }}
*/}}

{{- with resources.Get (print "hugo-icons/icons/" .) -}}
  {{- .Content | safeHTML -}}
{{- end -}}

Finitions de notre module

Notre module comporte maintenant les fichiers nécessaires. Il nous faut encore ajouter quelque chose de très important à sa configuration: sa compatibilité avec les versions d'Hugo.

Nous utilisons la fonction resources.Match introduite dans Hugo 0.57.0. Quant au montage dans les sous-dossiers, il n'est supporté que depuis Hugo 0.64.0.

Il nous faut donc indiquer que notre module ne marchera qu'avec une version d'Hugo au moins égale à 0.64.0 ou sinon… patatra !

# config.yaml
module:
  hugoVersion:
    # La version extended (Sass) n'est pas requise
    extended: false
    # Il n'y a pas de version maximale
    max: ""
    # Par contre il y a une version minimale
    min: "0.64.0"

Notre fichier config.yaml final :

module:
  hugoVersion:
    min: "0.64.0"
  mounts:
    - source: page/index.md
      target: content/hugo-icons-listing.md
      lang: en
    - source: page/template.html
      target: layouts/_default/hugo-icons-listing.html
    - source: partials
      target: layouts/partials/hugo-icons
  imports:
    - path: github.com/twbs/icons
      mounts:
        - source: icons
          target: assets/hugo-icons/icons

Vous pouvez consulter le dépôt de notre module d'exemple pour cet article.

Conclusion

Les modules Hugo sont la méthode à priviléger dès qu'il s'agit d'importer des fichiers issus de n'importe quel dépôt Git public dans vos projets et de contrôler leur versionnement.

Et maintenant que vous savez comment créer un module Hugo, vous devriez vous en servir pour gérer les composants réutilisables de vos projets et les publier pour enrichir l'écosystème d'Hugo. :smile:

Ressources complémentaires

• Documentation officielle
• Les modules Hugo pour les nuls
• Maîtriser les modules Hugo

Webmention est un standard web pour les mentions et les conversations sur le web, un puissant élément constitutif d'un réseau fédéré croissant de commentaires, d'appréciations, de rediffusions et d'autres riches interactions sur le web social décentralisé. — IndieWeb.org

C'est un outil très cool qui vous permet d'avoir des interactions sociales quand vous hébergez votre propre contenu. Max Böck a écrit un excellent article qui détaille son implémentation, Indieweb statique 2e partie : utiliser les Webmentions. Il a également crée un starter pour Eleventy, eleventy-webmentions, un modèle de départ avec un support basique des webmentions.

Alors pourquoi écrire cet article ? Malheureusement pour moi j'ai commencé à développer mon site avec le blog de base pour Eleventy et j'avais déjà terminé quand j'ai découvert eleventy-webmentions. J'ai dû lutter pour développer pleinement cette fonctionnalité, car je débute encore avec Eleventy. J'ai donc voulu partager en détail les étapes que j'ai dû mener à bien, en espérant que ça aide davantage d'entre vous à rejoindre l'IndieWeb.

Le but de cet article est d'ajouter les webmentions à un site Eleventy, après coup. Les fichiers, les dossiers, et l'architecture du site sont les mêmes que dans eleventy-base-blog, mais vous pouvez vous en servir comme point de départ pour un site Eleventy. Simplement faites attention aux endroits où votre architecture pourrait différer.

Le code de cet article est un mélange de l'article de Max Böck, son site perso, du modèle d'amorçage eleventy-webmentions, du site de Zach Leatherman, et des modifications effectuées pendant ma propre implémentation. Je leur suis très reconnaissante pour leur travail, car je n'aurais jamais pu arriver à ce résultat sans eux.

Étape 1 : s'inscrire sur webmentions.io

Il nous faut d'abord s'inscrire sur webmention.io, le service tiers qui nous permet de profiter du pouvoir des webmentions sur les sites statiques.

1. Configurer IndieAuth de manière à ce que webmention.io sache que vous êtes bien le propriétaire de votre domaine. Suivez les instructions données sur leur site.
2. Allez sur webmention.io.
3. Entrez l'URL de votre site web dans le champ "Web Sign-In" , et cliquez sur "Sign in".

Si la validation est réussie, vous devriez être redirigé·e vers le tableau des webmentions où sont affichées deux balises <link> que vous devez insérez dans la balise <head> de votre site web :

<!-- _includes/layouts/base.njk -->
<link rel="webmention" href="https://webmention.io/<your.domain>/webmention" />
<link rel="pingback" href="https://webmention.io/<your.domain>/xmlrpc" />

Vous disposez aussi d'un token d'API personnel. Nous voulons pouvoir le stocker de manière sécurisée dans nos variables d'environnement locales. Installez dotenv pour définir et accéder facilement à vos variables d'environnement :

npm install dotenv

Créez un fichier .env à la racine de votre projet et ajoutez votre token d'API pour webmention.io.

WEBMENTION_IO_TOKEN=v07r370k3n1c1.

N'oubliez pas d'ajouter votre fichier .env dans votre fichier .gitignore. Tant que nous y sommes, ajoutons également le dossier _cache qui sera crée lors du premier rapatriement des webmentions :

_cache/
_site/
node_modules/
.env

Vous aimeriez probablement récupérer quelques webmentions. Si vous utilisez Twitter, Bridgy est un excellent moyen de récupérer vos mentions depuis Twitter. Assurez d'abord qu'un lien vers votre site web est présent dans votre profil, puis connectez-le.

Comment tout ça va marcher

Quand nous lançons une génération avec NODE_ENV=production, nous allons récupérer les nouvelles webmentions publiées depuis la fois précédente. Celles-ci seront sauvées dans le fichier _cache/webmentions.json. Ces mentions proviennent de l'API de webmention.io.

Lors de chaque génération, pour chaque page :

• Depuis le cache des webmentions _cache/webmentions.json, ne garder que les webmentions qui correspondent à l'URL de la page en cours (dans mon cas, celle de l’article de blog).
• Faire appel à la fonction webmentionsByType pour les filtrer par type (par exemple des likes ou des réponses)
• Utiliser la fonction size pour calculer le nombre de mentions par type
• Afficher le total avec le type de mention sous forme d'entête (ex: "7 réponses")
• Afficher la liste des mentions de ce type (par exemple sous forme d'avatar avec un lien vers le profil Twitter pour chaque like.)

Récupération des webmentions

Tout d'abord, nous devons ajouter notre nom de domaine en tant que propriété dans notre fichier _data/metadata.json. Ajoutons-y également l'URL racine qui nous sera utile par la suite :

// _data/metadata.json
{
  //...other metadata
  "domain": "example.com",
  "url": "https://example.com"
}

Ensuite, installons quelques dépendances supplémentaires :

npm install lodash node-fetch

Et mettons à jour notre script de build pour y préciser la variable d'environnement NODE_ENV dans notre package.json :

// package.json
{
  // …config
  "scripts": {
    "build": "NODE_ENV=production npx eleventy",
    // scripts…
}

Nous pouvons maintenant nous concentrer sur la partie récupération. Oui, je sais que le fichier qui suit est beaucoup trop long, mais je pense qu'il n'est pas facile à comprendre hors contexte. Voici les grandes étapes qui constituent le code :

1. Lire les mentions depuis le cache enregistré dans _cache/webmentions.json.
2. Si notre environnement est production, récupérer les nouvelles webmentions depuis la dernière génération. Les fusionner avec celles en cache et sauvegarder le fichier de cache. Retourner les mentions ajoutées.
3. Si notre environnement n’est pas production, retourner les mentions depuis le cache.

// _data/webmentions.js
// Déclaration des dépendances
const fs = require('fs')
const fetch = require('node-fetch')
const unionBy = require('lodash/unionBy')
const domain = require('./metadata.json').domain

// Charger les variables d'environnement avec `dotenv`
require('dotenv').config()

// Définir l'emplacement du cache et les paramètres d'appel de l'API
const CACHE_FILE_PATH = '_cache/webmentions.json'
const API = 'https://webmention.io/api'
const TOKEN = process.env.WEBMENTION_IO_TOKEN

async function fetchWebmentions(since, perPage = 10000) {
  // Avertir et s'arrêter là si le nom de domaine et le token d'API ne sont pas définis
  if (!domain || !TOKEN) {
    console.warn('>>> Impossible de récupérer les webmentions : domaine ou token manquant')
    return false
  }

  let url = `${API}/mentions.jf2?domain=${domain}&token=${TOKEN}&per-page=${perPage}`
    if (since) url += `&since=${since}` // ne récupérer que les nouvelles webmentions

  const response = await fetch(url)
  if (response.ok) {
    const feed = await response.json()
    console.log(`>>> ${feed.children.length} nouvelles webmentions récupérées depuis ${API}`)
    return feed
  }

  return null
}

// Fusionner les nouvelles webmentions avec celles du cache, unique par id
function mergeWebmentions(a, b) {
  return unionBy(a.children, b.children, 'wm-id')
}

// sauvegarder les webmentions combinnées dans le fichier de cache
function writeToCache(data) {
  const dir = '_cache'
  const fileContent = JSON.stringify(data, null, 2)
  // créer le dossier de cache s'il n'existe pas déjà
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir)
  }
  // écrire les données dans le fichier de cache JSON
  fs.writeFile(CACHE_FILE_PATH, fileContent, err => {
    if (err) throw err
    console.log(`>>> webmentions mise en cache dans ${CACHE_FILE_PATH}`)
  })
}

// Lire le contenu du cache à partir du fichier JSON
function readFromCache() {
  if (fs.existsSync(CACHE_FILE_PATH)) {
    const cacheFile = fs.readFileSync(CACHE_FILE_PATH)
    return JSON.parse(cacheFile)
  }

  // Pas de cache trouvé.
  return {
    lastFetched: null,
    children: []
  }
}

module.exports = async function () {
  console.log('>>> Lectures des webmentions depuis le cache…');

  const cache = readFromCache()

  if (cache.children.length) {
    console.log(`>>> ${cache.children.length} webmentions chargées depuis le cache`)
  }

  // Ne télécharger les nouvelles webmentions qu'en production
  if (process.env.NODE_ENV === 'production') {
    console.log('>>> Vérification de nouvelles webmentions...');
    const feed = await fetchWebmentions(cache.lastFetched)
    if (feed) {
      const webmentions = {
        lastFetched: new Date().toISOString(),
        children: mergeWebmentions(cache, feed)
      }

      writeToCache(webmentions)
      return webmentions
    }
  }

  return cache
}

Filtres pour la génération

Maintenant que nous avons rempli notre cache de webmentions, il nous faut pouvoir l'utiliser. Nous devons pour cela générer les fonctions, les filtres, qu'Eleventy va utiliser pour générer nos fichiers.

D'abord, j'aime bien séparer les filtres de la configuration principale d'Eleventy pour ne pas trop la surcharger. Le fichier dédié aux filtres va définir chacun de nos filtres dans un objet. Les clés seront les noms de filtres et les valeurs seront les fonctions de filtres. Ajouter nos nouvelles fonctions de filtres dans le fichier _11ty/filters.js :

// _11ty/filters.js
const { DateTime } = require("luxon"); // Déjà présent dans eleventy-base-blog

module.exports = {
  getWebmentionsForUrl: (webmentions, url) => {
    return webmentions.children.filter(entry => entry['wm-target'] === url)
  },
  size: (mentions) => {
    return !mentions ? 0 : mentions.length
  },
  webmentionsByType: (mentions, mentionType) => {
    return mentions.filter(entry => !!entry[mentionType])
  },
  readableDateFromISO: (dateStr, formatStr = "dd LLL yyyy 'at' hh:mma") => {
    return DateTime.fromISO(dateStr).toFormat(formatStr);
  }
}

Maintenant pour pouvoir utiliser ces nouveaux filtres, dans notre fichier .eleventy.js, nous devons boucler sur les clefs de cet objet de filtres, pour ajouter chaque filtre à la configuration d'Eleventy :

// .eleventy.js
// ...Autres imports
const filters = require('./_11ty/filters')

module.exports = function(eleventyConfig) {
  // Filters
  Object.keys(filters).forEach(filterName => {
    eleventyConfig.addFilter(filterName, filters[filterName])
  })

  // Autres configs...

Afficher les mentions

Nous sommes maintenant fin prêts à tout assembler et à afficher nos webmentions. Je les positionne à la fin de chaque article de blog, donc dans mon fichier _includes/layouts/post.njk, j'ajoute une nouvelle section pour les webmentions. Ici, nous déclarons une variable nommée webmentionUrl qui contient l’URL complète de la page, puis nous la passons dans le fichier partiel webmentions.njk :

<!-- _includes/layouts/post.njk -->
<section>
  <h2>Webmentions</h3>
  {% set webmentionUrl %}{{ page.url | url | absoluteUrl(site.url) }}{% endset %}
  {% include 'webmentions.njk' %}
</section>

Nous pouvons maintenant écrire notre fichier de modèle pour les webmentions. Dans cet exemple, j’affiche des liens, des retweets et des réponses. Je commence par définir toutes les variables dont j’aurais besoin dans quelques instants :

<!-- _includes/webmentions.njk -->
  <!-- Filtrer les webmentions du cache pour n’inclure que celles relatives à l’URL de l’article en cours -->
  {% set mentions = webmentions | getWebmentionsForUrl(metadata.url + webmentionUrl) %}
  <!-- Définir les reposts comme des mentions de type `repost-of`  -->
  {% set reposts = mentions | webmentionsByType('repost-of') %}
  <!-- Calcul du total de reposts -->
  {% set repostsSize = reposts | size %}
  <!-- Définir les likes comme des mentions de type `like-of`  -->
  {% set likes = mentions | webmentionsByType('like-of') %}
  <!-- Calcul du total de likes -->
  {% set likesSize = likes | size %}
  <!-- Définir les réponses comme des mentions de type `in-reply-to`  -->
  {% set replies = mentions | webmentionsByType('in-reply-to')  %}
  <!-- Calcul du total de réponses -->
  {% set repliesSize = replies | size  %}

Une fois nos variables définies, nous pouvons afficher ces données. Ici je vais seulement m'attarder sur la partie "réponses", libre à vous d'aller voir comment je gère les autres types de webmentions dans ce gist.

L'affichage des réponses est un peu plus complexe que de simplement afficher une photo et un lien. Je fais appel à un autre template ici pour afficher chaque webmention. Nous affichons le nombre total de réponses et affichons le mot "Réponse" au pluriel si nécessaire. Puis nous bouclons sur les webmentions de type réponse et les affichons à l'aide d'un nouveau fichier partiel Nunjucks :

<!-- _includes/webmentions.njk -->
<!-- …définition des variables… -->
{% if repliesSize > 0 %}
<div class="webmention-replies">
  <h3>{{ repliesSize }} {% if repliesSize == "1" %}Reply{% else %}Replies{% endif %}</h3>

  {% for webmention in replies %}
    {% include 'webmention.njk' %}
  {% endfor %}
</div>
{% endif %}

Nous pouvons afficher les réponses à l'aide de ce nouveau fichier partiel pour chaque réponse. Si l'auteur de la webmention a une photo de profil, nous l'affichons, sinon nous affichons un avatar. Même chose pour le nom, nous l'affichons s'il existe, sinon nous affichons "Anonyme". Notre filtre readableDateFromISO nous aide à afficher la date de publication dans un format plus sympathique pour les humains, enfin nous affichons le texte de la webmention :

<!-- _includes/webmention.njk -->
<article class="webmention" id="webmention-{{ webmention['wm-id'] }}">
  <div class="webmention__meta">
    {% if webmention.author %}
      {% if webmention.author.photo %}
      <img src="{{ webmention.author.photo }}" alt="{{ webmention.author.name }}" width="48" height="48" loading="lazy">
      {% else %}
      <img src="{{ '/img/avatar.svg' | url }}" alt="" width="48" height="48">
      {% endif %}
      <span>
        <a class="h-card u-url" {% if webmention.url %}href="{{ webmention.url }}" {% endif %} target="_blank" rel="noopener noreferrer"><strong class="p-name">{{ webmention.author.name }}</strong></a>
      </span>
    {% else %}
      <span>
        <strong>Anonymous</strong>
      </span>
    {% endif %}

    {% if webmention.published %}
      <time class="postlist-date" datetime="{{ webmention.published }}">
        {{ webmention.published | readableDateFromISO }}
      </time>
    {% endif %}
  </div>
  <div>
    {{ webmention.content.text }}
  </div>
</article>

Sautons courageusement dans l’inconnu…

Ça fonctionne ? Nous allons enfin pouvoir tester. Commencez par lancer la commande npm run build pour générer une liste initiale de webmentions qui sera sauvegardée dans le fichier _cache/webmentions.json. Puis lancer votre serveur de développement local pour vérifier que ça marche ! Bien entendu, vous devrez au moins avoir une webmention associée à un article pour voir quelque chose. 😁

Vous pouvez voir le résultat de ma propre implémentation sur mon site. Bon courage ! Dites moi si vous trouvez des anomalies ou des erreurs dans cet article !

Poursuivez en ajoutant des Microformats

Keith Grant a un excellent article Ajouter le support de Webmention à un site statique. Lisez la section "Amélioration à l'aide des Microformats" pour plus d'explication et d'exemple.

Ressources additionnelles

• La totalité du code source de mon site est sur Github. Il évoluera avec le temps, j'en suis sûre, regardez donc attentivement ce commit qui contient l'ensemble de mes changements pour l'ajout des webmentions.
• Comment ajouter le support de dotenv sur Netlify est abordé dans cette réponse sur Stack Overflow.
• Comment définir un job cron via Github Actions pour régénérer périodiquement mon site sur Netlify (afin de récupérer et d'afficher les nouvelles webmentions) est détaillé dans Programmer des déploiements Netlify avec les GitHub Actions.

Comme nous l'avons déjà vu dans différents articles dont celui sur la mise en cache des fichiers partiels, jusqu'ici le moteur de templating d'Hugo se concentrait principalement sur la génération de fichiers. Résultat : même si les fichiers partiels étaient très utiles pour afficher tout un tas de trucs, jusqu'à récemment, ils ne permettaient pas de retourner une valeur typée.

Tout a changé à partir de la version 0.55.0 d'Hugo qui a introduit l'instruction return dans l'API de la fonction partial ! Les partiels sont tout à coup devenus des fonctions réutilisables qui peuvent être appelées par des fichiers de modèles plus conventionnels.

Dans cet article, nous aborderons les bases de cette fonctionnalité avant de nous plonger dans des cas d'utilisation bien précis.

Avant return

Avant l'arrivée de l'instruction return, quand les partiels ne savaient qu'imprimer du contenu, beaucoup de gens se reposaient malgré tout sur eux pour créer des bouts de code réutilisables qui avaient d'autres buts. Par exemple vous pouviez transformer l'URL relative d'une image pour la préfixer avec votre domaine S3:

# layouts/partial/FormatURL.html
{{- $S3Domain := site.Params.s3Domain -}}
{{- printf "%s/%s" $S3Domain . | safeHTMLAttr -}}
# layout/_default/single.html
{{- with .Params.image -}}
<img src="{{ partial "FormatURL.html" . }}" />
{{ end }}

Ici la notation {{- -}} nous assure que rien d'autre ne sera affiché aux côtés de la chaîne de l'URL : ni espace, ni retour à la ligne, etc.

On pourrait même aller plus loin et afficher des données au format JSON à l'appel du partiel :

# layouts/partial/GetSEOData.html
{{- with . -}}
  {{- $title := .Title -}}
  {{- $description := .Summary -}}
  {{- with .Params.seo.title -}}
    {{- $title = . -}}
  {{- end -}}
  {{- with .Params.seo.description -}}
    {{- $description = . -}}
  {{- end -}}
  {{- dict "title" $title "description" $description | jsonify -}}
{{- end -}}

# layouts/partial/head.html
{{ $seo := partial "GetSEOData.html" . | transform.Unmarshal }}
{{ with $seo }}
  # seo tags...
{{ end }}

Mais ces astuces se limitaient à des types de données basiques comme les chaînes de caractères, les nombres ou des tableaux (associatifs) de celles-ci. Il n'y avait aucun moyen de facilement retourner un objet complexe comme une page ou un fichier, encore moins une collection de pages.

Puis vint Hugo 0.55.0 , l'instruction return et les partiels de fonction!

Quelques points à retenir

Avant de nous plonger dans le code, il y a certaines choses à faire et à ne pas faire que nous devons passer en revue.

🚫 Pas de return dans les clauses

{{ if gt .Params.temperature 70 }}
  {{ return 😎 }}
{{ end }}

Ici ☝️ la valeur .Params.temperature sera ignorée et c'est 😎 qui sera systématiquement retourné. Un partiel retournera simplement ce qui suit une instruction return et ce où qu'elle soit positionnée dans le code.

{{ with .Params.temperature }}
  {{ return . }}
{{ end }}

Même chose ici ☝️, return doit se trouver à la racine et ne peut pas être appelé dans une instruction imbriquée.

🚫 Pas de multiples instructions return

{{ if gt .Params.temperature 70 }}
  {{ return 😎 }}
{{ else }}
  {{ return ⛸️ }}
{{ end }}

Cet exemple ne marchera pas, car les retours multiples ne sont pas supportés.

👍 Une unique variable retournée

On tire donc des exemples précédents la règle générique : une variable retournée unique à la racine.

Le meilleur moyen de se conformer à cette règle est de porter notre attention sur l'unique variable retournée.

La variable retournée c'est votre base de départ, celle que vous allez manipuler et éventuellement retourner.

1. 🍽️ Affecter une valeur de départ,
2. 🔪 la travailler,
3. 💁‍♂️ et la retourner à la fin.

{{ $emoji := ⛸️ }}
{{ if gt .Params.temperature 70 }}
  {{ $emoji = 😎}}
{{ else if gt .Params.temperature 100 }}
  {{ $emoji = 🥵}}
{{ end }}
{{ return $emoji }}

Quel que soit le nombre de lignes, d'espaces ou de retours à la ligne dans votre code, la seule valeur produite par votre partiel c'est cet emoji unique qui suit le mot magique return.

{{< notice info >}} Tout comme pour if, with, range et leurs amis, ce qui suit return n'a pas besoin d'être entre parenthèses.

{{ return gt .Params.temperature 50 }}

☝️ Cette notation est valide et retournera un booléen. {{< /notice >}}

🤙 Appeler nos partiels de fonction

Comme pour n'importe quel autre partiel on écrit :

Emoji: {{ partial "emoji.html" . }}

Là où ça devient intéressant c'est qu'on peut stocker la valeur retournée !

{{ $emoji := partial "emoji.html" . }}

📏 Quelques conventions

Du moins celles que j'ai adoptées…

Pour bien distinguer mes partiels classiques de ceux qui retournent des valeurs de tous types, j'ai pris pour habitude de ranger ces derniers dans le dossier layouts/partials/func/. Cela a au moins le mérite de les isoler des partiels plus conventionnels, sans avoir non plus à avoir à taper beaucoup plus de caractères lors de leur appel.

{{ partial "func/emoji.html" . }}

Hugo part du principe que par défaut l'extension de votre fichier partiel est .html. Vu que j'utilise toujours l'extension html pour mes fichiers partiels, je peux omettre de l'écrire et ainsi gagner cinq précieux caractères :

{{ partial "func/emoji" . }}

Enfin, j'aime bien utiliser la casse CamelCase ainsi qu'un verbe autant que possible :

{{ partial "func/GetEmoji" . }}

Et voilà mon code Hugo est tout beau :

{{ with partial "func/GetEmoji" . }}
  Emoji: {{ . }}
{{ end }}

Coder nos partiels de fonction

Bien, la partie théorique était intéressante, maintenant il est temps de faire craquer quelques articulations et de nous mettre à taper au clavier ! Ensemble nous allons essayer de répondre à un besoin de base : lister les termes des taxonomies de nos projets Hugo de manière efficace.

Cette opération n'est pas forcément très intuitive. Une taxonomie et ses termes occupent une place à part entière dans un projet Hugo, mais vu depuis le contexte d'une page, ce n'est qu'une liste de chaînes de caractères dans votre Front Matter :

---
title: Une nuit au Louvre
tags:
  - Art
  - Paris
  - Musée
---

Pour les lister sous forme de liens cliquables, vous devez construire vous même ces dits liens, en vous basant sur ces chaînes transformées en URLs ou en récupérant l'objet page à l'aide de .GetPage ou .Site.Taxonomies.

Ce serait bien si ce travail pénible pouvait être fait dans un partiel de fonction réutilisable et non dans les fichiers de modèles de nos contenus.

Quant à l'appel de ce type de partiel, il devrait être aussi concis que cela :

{{ range .Params.tags }}
  {{ with partial "func/GetTagPage" . }}
    <a href="{{ .RelPermalink }}">{{ .Title }}</a>
  {{ end }}
{{ end }}

🙌 ⌨️ C'est parti

{{/* 1. */}}
{{ $tag := false }}
{{/* 2. */}}
{{ with index site.Taxonomies.tags (urlize .) }}
  {{/* 3. */}}
  {{ with .Page }}
    {{/* 4. */}
    {{ $tag = . }}
  {{ end }}
{{ end }}

{{/* 5. */}
{{ return $tag }}

1. Nous commençons par initialiser notre variable retournée à sa valeur par défaut
2. site.Taxonomies.tags retourne une collection de tous les tags du site avec leur objet .Page. Le point représente le contexte de notre partiel, ici le nom de notre tag, que nous transformons en URL pour correspondre à sa clef dans site.Taxonomies.tags.
3. Nous avons de fortes chances de tomber sur une .Page, mais with ajoute une vérification supplémentaire et nous permet en plus de changer de contexte.
4. Nous stockons le tag de la page dans notre variable retournée.
5. 🎉

👍 Beau boulot !

Et pour les autres taxonomies comme les categories? Hors de question de copier/coller tout cela dans un nouveau partiel pour remplacer site.Taxonomies.tags par site.Taxonomies.categories. 🙅‍♀️

Nous voulons pouvoir écrire ceci :

{{ range .Params.categories }}
  {{ with partial "func/GetTermPage" (dict "taxonomy" "categories" "term" .) }}
    <a href="{{ .RelPermalink }}">{{ .Title }}</a>
  {{ end }}
{{ end }}

Gestion des arguments

Jusqu'à maintenant nous n'avons passé qu'un seul argument à nos partiels de fonction, où le contexte ne contenait qu'un élément. Mais ici, il nous en faut deux : la taxonomie et son terme. Notre contexte devra donc être un tableau associatif qui contiendra les deux.

Nous mettons donc notre partiel à jour :

{{ $return := false }}

{{/* 1. */}}
{{ $taxonomy := "tags" }}
{{ with .taxonomy }}
  {{ $taxonomy = . }}
{{ end }}

{{/* 2. */}}
{{ with $term := .term }}
  {{ with index site.Taxonomies $taxonomy }}
    {{ with index . (urlize $term) }}
      {{ with .Page }}
        {{ $return = . }}
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

{{/* 3. */}}
{{ return $return }}

1. Maintenant que nous passons un argument term, nommer notre variable retournée $term pourrait prêter à confusion. Appelons la maintenant $return pour bien marquer que c'est la variable retournée.
2. Si aucun argument .term n'est présent, la variable retournée devrait rester vide. Avant d'aller plus loin, nous faisons appel à with pour nous assurer que .term est bien défini et nous stockons cette valeur initiale afin de pouvoir y accéder quelque que soit notre contexte. Ces quelques lignes sont d'ailleurs une très bonne illustration de changements de contexte !
3. 🎉

Mise en cache !

OK très bien, mais je veux une fonction qui liste les tags d'une page et qui me renvoie un tableau de tableaux associatifs qui contiennent chacun des données structurées comme .URL et .Name. De cette façon, si je veux passer de .RelPermalink à .Permalink dans le futur, je peux le faire dans ma variable retournée plutôt que dans chaque fichier de modèle où je souhaite afficher ces liens.

C'est l'occasion idéale de voir comment appeler un partiel de fonction depuis un partiel de fonction et mettre en cache sa valeur. :sweat_smile:

#layout/partials/func/GetTags.html
{{/* 1. */}}
{{ $return := slice }}
{{/* 2. */}}
{{ with .Params.tags }}
  {{ range . }}
    {{/* 3. */}}
    {{ with partialCached "func/GetTerm" (dict "taxonomy" "tags" "term" .) "tags" . }}
      {{/* 4. */}}
      {{ $tag := dict "URL" .RelPermalink "Name" .Title }}
      {{/* 5. */}}
      {{ $return := $return | append $tag }}
    {{ end }}
  {{ end }}
{{ end }}

{{/* 6. */}}
{{ return $return }}

1. Nous voulons être sûrs de pouvoir parcourir la valeur de notre variable retournée à l'aide de la fonction range. Afin de nous assurer de retourner un tableau (slice), nous initialisons notre variable avec un tableau vide.
2. La fonction range ne bronchera pas avec un tableau vide, mais tout autre type de valeur entraînerait une erreur de génération. Il est donc toujours plus sage de tester à l'aide d'un with, sauf si vous êtes vraiment sûrs de retourner un tableau.
3. Nous appelons notre précédent partiel de fonction, mais cette fois nous le mettons en cache. Pour les variantes, nous utilisons les deux valeurs de ses arguments.
4. Nous sauvegardons le tout dans un tableau associatif à des fins de lisibilité. Puisque notre $tag est déclaré dans le contexte de notre boucle range, il ne pourra pas entrer en conflit avec un autre $tag comme par exemple le prochain tag de la liste.
5. Nous utilisons la fonction append pour ajouter notre tableau associatif $tag au tableau que nous retournons.
6. 🎉

Maintenant dans notre modèle nous pouvons écrire :

# layouts/_default/single.html
{{/* 1. */}}
{{ range partial "func/GetTags" $ }}
  {{/* 2. */}}
  <a href="{{ .URL }}">{{ .Name }}</a>
{{ end }}

1. Nous avons que la valeur retournée par notre partiel de fonction maison est à coup sûr un tableau, vide ou non. Nous pouvons donc utiliser range sans problème.
2. Nous pouvons maintenant utiliser les clefs personnalisées de nos tableaux associatifs.
3. C'est tout !

Des améliorations possibles ?

Bien entendu ! Nous pourrions :

• Exclure certains tags du tableau retourné par la fonction GetTags
• Transformer GetTags en GetTerms, afin de pouvoir l'utiliser pour n'importe quelle taxonomie.
• Trouver la bonne variante de notre partiel de fonction GetTags et utiliser partialCached.
• Développer bien plus de partiels de fonction pour répondre à d'autres besoins !

Conclusion

Après avoir vu les bases, nous avons pu développer deux partiels de fonction qui nous aideront grandement dans la maintenance de l'affichage des taxonomies de notre site.

Et si nous avons besoin d’afficher seulement certains articles ou bien tous les articles mais en excluant certains tags ? Cela se passera dans la fonction GetTags et pas ailleurs ! Et si dans une prochaine version Hugo introduit un moyen plus efficace de gérer les termes d’une taxonomie ? Nous ajusterons notre fonction GetTerm !

Avec ses partiels de fonction, Hugo répond enfin à la séparation des problématiques de templating et de gestion des données, en permettant la réutilisabilité et le typage de données !

Est-ce que je vous ai déjà dit que c'était une de mes fonctionnalités préférées dont je vais abuser en 2020 ?

Si vous avez un retour d’expérience ou des questions à propos des partiels de fonction, ou que voulez simplement partager les partiels que vous avez développé suite à lecture de cet article, laissez un commentaire ou un bout de code !

De mon point de vue de commercial, bien qu'ils soient de bonne compagnie, les développeurs ont souvent du mal à expliquer les concepts techniques, les solutions et les bénéfices, en des termes simples. Principalement à cause du fait qu'ils parlent surtout un langage technique et qu'ils prennent leurs connaissances trop souvent pour acquises.

C'est génial quand vous faites partie d'une équipe de développement web. Vous utilisez leurs explications comme fil directeur et faites des recherches sur le sujet.

Mais ça ne marchera pas avec vos clients.

Donc, comment pouvez-vous mieux communiquer sur la Jamstack à vos clients. Déjà commencer par limiter le jargon métier et transformez les fonctionnalités techniques en des gains potentiels pour le business.

Les bénéfices de la Jamstack

Je ne vais pas vous embêter avec les définitions et tout le tralala (on a déjà fait ça dans un autre article, allez donc le consulter), mais je dirai ceci : bien que la Jamstack représente une nouvelle manière de développer des sites web et qui présente bien des avantages par rapport à la stack traditionnelle, ce mouvement rassemble une large communauté avec un grand nombre d'outils et de services qui vous seront du plus grand secours à cet égard.

Avec les possibilités des navigateurs actuels, les générateurs de site statique, les CMS headless, les APIs et les CDNs vous pouvez donc développer des sites et des applications qui ne sont pas liées à une technologie ou un framework spécifique. C'est en soi aisément le plus gros avantage que la Jamstack apporte à votre client.

Toutefois, vous échiner à expliquer pourquoi ces détails techniques comptent, ne vous aidera pas beaucoup dans vos discussions avec des prospects et des clients. Il se peut même qu'ils se sentent dépassés, perdus et frustrés.

Focalisez-vous plutôt sur comment cela pour être bénéfique pour leur activité. En général, cela se résume à des revenus ou à une meilleure expérience pour eux, leur développeurs et leur audience.

De meilleures performances

Plus de la moitié des gens abandonnent leur visite sur un site s'il met plus de trois secondes à se charger. Cela se traduit par des pertes de revenu directes, une baisse des conversions et une mauvaise expérience utilisateur. — ThinkWithGoogle

La rapidité de votre site Web peut faire gagner ou perdre des visites engagées qui sont plus susceptibles d'être exploités à des fins commerciales, que vous recherchiez des ventes, des clics publicitaires et/ou une augmentation du trafic. De plus, aujourd'hui, les gens du monde entier s'attendent à ce que les marques offrent une expérience de site Web rapide et sans friction sur de multiples appareils.

C'est là que se trouve le premier grand argument de vente de la Jamstack : de meilleures performances. En proposant des pages statiques sur CDN, vous améliorez la vitesse de chargement des pages et les performances de votre site Web. La vitesse est devenue un facteur de classement extrêmement important. Pour votre client, cela signifie une meilleure optimisation pour les moteurs de recherche, ce qui peut conduire à un meilleur classement dans les résultats de recherche naturels et à plus de trafic.

D'autre part, plus de trafic signifie plus d'opportunités de transformer vos visiteurs en prospects. Étant donné que le taux de conversion des prospects est étroitement lié à la performance du site Web (tel que cité ci-dessus), le fait d'avoir une page Web livrée plus rapidement influence directement les revenus des clients.

Sécurité accrue et mise à l'échelle plus facile

Personne ne veut avoir un site Web sujet à des failles de sécurité majeures. En proposant des pages statiques, vous réduisez considérablement la surface des attaques malveillantes et des exploits potentiels. De plus, en cas d'augmentation inattendue du trafic, vous pouvez faire en sorte que le CDN sur lequel vos fichiers sont hébergés compense de manière transparente.

Pour votre client, cela signifie beaucoup moins de temps de maintenance de développement et moins de temps de récupération suite à un piratage potentiel. En d'autres termes, une réduction des coûts.

Hébergement

Nous avons un potentiel de croissance du chiffre d'affaires grâce à l'amélioration de nos performances. Ensuite, nous réalisons des économies de coûts grâce à une réduction du temps de développement consacré à la maintenance, à la sécurité et aux problèmes de performance. Enfin, les coûts d'hébergement de vos clients diminueront considérablement car l'hébergement sur CDN pour les fichiers statiques est beaucoup moins cher que l'hébergement traditionnel.

Expliquer la Jamstack au client

Lorsqu'on traite avec des clients, le défi de communiquer clairement et efficacement les avantages, les buts et les bénéfices peut parfois s'avérer accablant. D'autant plus si votre client n'est pas un expert en technologie.

Alors, comment communiquez-vous tous les avantages avec votre client ?

Posez des questions et informez vos clients

Commencez par poser beaucoup de questions à votre client afin de comprendre sa motivation, ses objectifs commerciaux, ses compétences techniques et marketing. Demandez-leur quels outils, applications ou technologies ils utilisent à la maison et au travail. Écoutez les retours d'information. C'est un peu comme construire la personnalité d'un acheteur pour un seul client.

Ensuite, mettez votre client à niveau pour qu'il puisse lui aussi comprendre de quoi vous parlez. Comment ? Aidez votre client à comprendre la Jamstack dans une langue qu'il comprendra beaucoup plus facilement (rappelez-vous que c'est pour cela que vous avez posé beaucoup de questions).

Faites des analogies entre les technologies que connaît déjà votre client et vos solutions. Par exemple, si vos clients connaissent WordPress, comparez les avantages et les inconvénients de WordPress et dites pourquoi les générateurs de site statique sont une excellente alternative et à quel point ces deux approches sont différentes ou similaires.

Faîtes des études de cas

Les études de cas sont l'un des moyens les plus efficaces de transformer des prospects hésitants en clients. Utilisez des études de cas de vos précedents travaux, non pas pour montrer, mais pour aider vos prospects et clients à réaliser qu'il existe une solution Jamstack élégante à leur problème. Plus vous pouvez aligner votre étude de cas sur les problèmes auxquels votre client est confronté, plus l'étude de cas aura d'impact.

Si vous n'en avez pas, utilisez Internet. De cette façon, vous familiariserez votre client avec la Jamstack, ses possibilités et ses inconvénients, et vous le rendrez plus ouvert à cette idée.

Donnez-leur des options, laissez-les choisir

Si vous avez su tirer parti de vos discussions préalables pour éduquer le client et le familiariser avec la Jamstack, une fois que vous aurez commencé à travailler sur la solution technique, donnez à votre client une voix dans le choix de la décision technique. Faites en sorte qu'ils se sentent entendus et valorisés. Sollicitez continuellement leurs commentaires et impliquez-les dans le processus. Cela suscitera alors un plus grand intérêt et une plus grande responsabilité partagée de la part des clients.

En résumé…

La plupart du temps, les clients veulent la lune avec leur budget. Cependant, ce que le client veut et ce dont il a besoin sont souvent deux choses complètement différentes. Jamstack est fondamentalement un ensemble d'outils proposé donc assurez-vous que c'est le meilleur ensemble d'outils pour votre client avant de le proposer.

C'est votre travail de vous assurer qu'ils obtiennent ce dont ils ont besoin et de comprendre la logique et la technologie sous-jacente.

Les fichiers partiels sont parmi les modèles de fichiers les plus utilisés pour la maintenance de sites Hugo. C'est eux qui nous permettent d'isoler nos composants, inclusions, ou autres morceaux de code et même plus récemment nos fonctions.

Nous n'allons pas revenir dans cet article sur les bases des partiels comme leur contexte que nous avons déjà détaillé auparavant.

Nous allons voir comme tirer parti au mieux des fonctionnalités de ces fichiers, bien au-delà des inclusions habituelles. Nous verrons comment Hugo peut mettre en cache vos fichiers partiels pour réduire le temps de génération, comment les utiliser comme des fonctions, nous verrons enfin quelles sont les meilleures pratiques à adopter en termes d'organisation et de commentaires pour nous assurer de leur pérennité.

Entrons dans le vif du sujet sans plus attendre avec la solution dédiée à la mise en cache des fichiers partiels : partialCached

Pourquoi utiliser partialCached ?

Comme vous le savez peut-être déjà, le but d'un fichier partiel est de permettre de refactoriser les parties de code utilisées souvent dans vos modèles.

Si comme moi vous avez horreur de copier-coller des bouts de code un peu partout dans vos projets, vous devez avoir beaucoup recours aux fichiers partiels !

Le rendu du code de votre fichier partiel peut être identique sur une majorité des pages et quelque peu différent pour certaines, ou bien il peut être complètement différent d'une page à l'autre. Ce deuxième scénario bénéficiera rarement des bienfaits d'une mise en cache, concentrons-nous donc ici sur le premier.

Songez à l'entête de page de votre site par exemple.

Votre entête de page affichera presque toujours le même balisage. Même logo, même lien vers la page d'accueil, même menu de navigation, même liens vers vos comptes sur les réseaux sociaux. Il sera affiché sur chacune des pages de votre site.

Si votre projet Hugo nécessite la création de milliers de fichiers HTML, alors, à chaque génération Hugo va devoir inspecter mille fois la configuration de votre menu, celle de vos profils sociaux pour au final générer le même balisage.

Avec partialCached vous pouvez dire à Hugo que ce bout de code ne bouge jamais et qu'il peut donc l'inspecter une seule fois, le mettre en cache et le réutiliser :

{{ partialCached "header.html" . }}

C'est 999 fois où Hugo n'aura pas à interpréter le code de votre fichier partiel. En fonction de la complexité de votre menu de navigation, vous venez de potentiellement gagner pas mal de précieuses millisecondes ⏱️!

Mais notre entête de page est-il vraiment identique sur toutes les pages ?

Non, car il est fort probable que les liens du menu principal soient soulignés ou mise en forme pour indiquer aux visiteurs où ils se trouvent actuellement sur le site.

Le code de notre menu Hugo contient souvent quelque chose comme :

<nav>
{{ range .Site.Menus.main }}
  <a
    class="{{ if eq $currentPage.Section .Page.Section }} active {{ end }}"
    href="{{ .URL }}"
  >
    {{ .Name }}
  </a>
{{ end }}
</nav>

Le code ci-dessus parle quasiment de lui-même. Notre projet comporte un menu principal avec cinq entrées, chacune pointant vers une section du site. Pour rendre active l'entrée Blog du menu lorsqu'on se trouve sur une page de la section Blog, nous comparons la section de la page visitée ($currentPage.Section) avec celle de l'entrée de menu (.Page.Section).

Avec le {{ partialCached "header.html" . }} actuel, Hugo va maintenant évaluer une seule fois la condition de ce if et appliquer son résultat à toutes les pages suivantes générées, et ce quelle que soit leur section.

Heureusement il y a les variantes de partiel.

Les variantes de partiel

Nous savons que notre entête va seulement être modifié cinq fois, en fonction de la .Section de la page courante. Nous devons donc dire à Hugo de mettre en cache une différente variante du partiel en fonction de ce facteur.

Contrairement à la fonction partial, les arguments de partialCached ne se limitent pas au contexte.

Pour nos cas d'utilisation, il est clair que la variante est la .Section de la page courante, nous pouvons donc écrire ceci :

{{ partialCached "navigation.html" . .Section }}

🎉 C'est 995 fois où Hugo n'aura pas à interpréter le code de ce partiel.

Bien. Cela fait une variante en moins, mais quid si quelque chose d'autre doit changer et que ce n'est pas lié à la section ?

Par exemple sur mon site, les liens sociaux sont bien en vue sur la page de contact, du coup sur cette page ils ne sont pas affichés "en double" dans l'entête.

Le code ressemble à ça :

{{ if ne .Layout "contact" }}
  {{ range site.Socials }}
    {{/* vous voyez l'idée */}}
  {{ end }}
{{ end }}

Nous avons donc maintenant besoin de deux variantes, la variante .Section et la variante Est-ce la page de contact ?.

Heureusement pour nous, le nombre de variantes n'est pas limité, alors allons-y gaiement :

{{ partialCached "navigation.html" . .Section "contact" }}

OK, c'était simplement à des fins de clarté et de lisibilité mais soyons réaliste, vous aurez vraisemblablement besoin de quelque chose de plus "dynamique" :

{{ $layout := cond (eq .Layout "contact") "contact" "other" }}
{{ partialCached "navigation.html" . .Section $layout }}

🎉 C'est maintenant 994 fois où Hugo n'aura pas à interpréter le code de ce partiel.

Haussons le niveau d'un cran 💪

Plongeons-nous maintenant dans quelque chose d'un peu plus complexe.

Notre blog possède un emplacement pour afficher les auteurs d'un article. Il y a trois auteurs pour le site, cet emplacement pourra donc en lister un seul, ou alors une combinaison d'entre eux en fonction de la liste d'auteurs présente dans le front matter de l'article. On peut dire avec certitude que sur nos mille articles, beaucoup partageront la même liste d'auteurs.

Ici, la variante idéale serait donc de passer notre liste d'auteurs dans un ordre défini, et nous serions tentés de pouvoir écrire :

{{ partialCached "authors-box.html" . .Params.authors }}

Malheureusement à l'heure actuelle, les variantes passées en argument de la fonction partialCached doivent être des chaînes de caractères 🤷.

Pour respecter ce prérequis, nous devons transformer cette liste en chaîne de caractères avant de la passer en option, et la manière la plus sûre de le faire, comme souvent, c'est d'utiliser la fonction printf avec le bon verbe.

Personnellement j'aime bien %x, car il va générer la représentation d'une valeur en chaîne hexadécimale, quelque que soit le type de structure.

Admettons que nous ayons :

authors:
  - Bud Parr
  - Frank Taillandier
  - Régis Philibert

{{ $variant := printf "%x" .Params.authors }}

🖨️👇 [42756420506172724672616e6b205461696c6c616e6469657252c3a9676973205068696c6962657274]

Nous avons maintenant une chaîne de caractères que nous pouvons passer comme variante du partiel :

{{ with .Params.authors }}
  {{ $authors := sort . }}
  {{ $variant := printf "%x" $authors }}
  {{ partialCached "authors-box.html" . $variant }}
{{ end }}

Grâce à cela, nous sommes maintenant assurés qu'Hugo ne génèrera qu'une seule variante par combinaison d'auteurs, soit 7 au maximum.

Et les langues ? 🇫🇷🇬🇧

Dans un contexte multilingue, si nous repensons à notre partiel pour l'entête de page, il se pourrait que nous y trouvions aussi un sélecteur de langue et que nous soyons tentés d'ajouter une autre variante :

{{ partialCached "navigation.html" . .Section .Lang }}

Mais ce n'est pas la peine de le faire, car par défaut Hugo va générer autant de caches de partiels que de langues déclarées. Dans notre cas de figure, Hugo va donc calculer le balisage de notre entête dix fois.

Améliorer votre temps de génération ⏱️

Pour les sites que vous avez développé vous-même, il est relativement facile d'aller inspecter votre dossier partials et d'identifier ceux qui pourraient être mis en cache. Mais pour les projets dont vous avez hérité ou que vous avez développé il y a moment, il existe deux options que vous pouvez passer à la ligne de commande: hugo --templateMetrics --templateMetricsHints.

La première option même utilisée seule est déjà très utile puisqu'elle vous affiche le détail des durées de génération. Cependant tout ne peut pas être mis en cache, seulement les fichiers partiels.

Ces options vous aideront à identifier les principaux goulots d'étranglement, cependant vous devriez tout le temps garder ces trois points en tête:

1. Le niveau de complexité de votre fichier partiel et sa durée de génération ajoutée au temps total.
2. La comparaison entre le nombre de fois où un partiel sera traité et son potentiel de variantes.
3. L'adaptation de votre code de façon à ce qu'il puisse être mis en cache (identifier tôt les variantes vous dispensera de pas mal de refactorasition)

Conclusion

Lorsque vous créez ou maintenez un projet Hugo, vous devez toujours garder en tête que chaque ligne de code peut réduire potentiellement le temps de génération. Laissez Hugo faire le gros du travail seulement quelques fois et non systématiquement!

Allez donc jeter un œil à vos fichiers partiels, créez vos propres variantes, et économisez du temps et de l'argent en vous reposant autant que possible sur partialCached !

L'agence Bejamas s'est spécialisée dans le développement de sites Jamstack. Après avoir testé différentes solutions, elle se penche dans cet article sur les différences entre les CMS basés sur Git et ceux basés sur des APIs. L'article a le mérite de donner un aperçu des avantages et des inconvénients des deux types de plates-formes. Dans les faits la dichotomie n'est pas aussi binaire qu'on pourrait le penser. En effet, rien n'empêche un CMS qui communique avec l'API d'une plate-forme Git de vous permettre d'accéder à votre tour à ces contenus via une API de votre cru. Générer des fichiers JSON, les générateurs actuels comme Hugo ou Eleventy font ça très bien. On peut considérer que les CMS basés sur des APIs offrent un confort d'utilisation en fournissant une API et sa documentation par défaut. Une iso fonctionnalité demandera naturellement un effort supplémentaire si vous devez développer vous-même votre API. À vous de peser le pour et le contre de l'approche DIY, qui peut soit dit en passant tout à fait être réutilisable de projet en projet. Il vous faut aussi prendre en compte dans l'équation votre workflow éditorial, la taille de votre site (et donc le temps nécessaire à la génération d'une nouvelle version) ainsi que votre fréquence de publication. Autant de paramètres qui doivent peser dans le choix d'un headless CMS. On rappellera que les CMS headless ne présentent aucun des inconvénients des CMS traditionnels, que ce soit en terme de workflow de développement, de performance ou de sécurité, et qu'ils offrent plus de flexibilité et une meilleure productivité, une fois l'investissement initial consenti.

Alors que le monde est en train de migrer vers le cloud, les systèmes de gestion de contenu (CMSs), en tout cas les plus populaires, sont encore embourbés dans des technologies et des architectures qui ont plus de 20 ans. Ils n'en sont pas moins fonctionnel pour autant.

WordPress par exemple (qui date du début des années 2000) est utilisé à l'heure actuelle par 34% des sites web. Dans le même temps, il y a une forte demande d'innovation, et le souhait d'une meilleure expérience numérique pousse beaucoup d'entreprises à accélérer leur rythme de développement et à se tourner vers les outils de développement d'interfaces client modernes, ceci afin de créer des sites plus légers, plus performants et plus sécurisés.

Mais il faut bien que le contenu de votre site web vive quelque part, n'est-ce pas ?

Bienvenue dans le monde des CMS headless. Plutôt que de lister quelques uns des headless CMS de cet écosystème — ce que nous avons déjà fait de manière opiniâtre — dans cet article, nous allons couvrir les différences, les défis, et les bénéfices de l'utilisation des CMS basés sur Git et de ceux accessibles par défaut via une API. ¹

Les CMS basés sur Git

Avec un CMS basé sur Git, les changements sont d'abord enregistrés dans votre dépôt Git, ce qui ensuite peut produire une nouvelle génération de votre site. Sans entrer trop dans les détails, sachez juste que vous allez travailler principalement avec des fichiers stockés dans votre dépôt Git. Voyons quels sont les avantages et les inconvénients de ce type de CMS.

Pour

• Pas de verrou propriétaire sur vos contenus.
• Gestion de version de tous les contenus par défaut.
• Tous les contenus étant disponibles sous forme de fichiers texte, les développeurs peuvent continuer d'utiliser leurs outils habituels.
• Facilite l'annulation de changements.
• C'est l'approche la plus homogène pour la plupart des développeurs web, qui utilisent déjà un workflow basé sur Git.
• Facile à configurer.

Contre

• Si vous avez plusieurs sites ou applications qui récupèrent des contenus depuis un même CMS, ce n'est pas forcément la meilleure solution.
• Si votre site a une quantité très importante de contenus, vous préférerez peut-être regarder du côté d'une base de données.
• Si vous prévoyez des mises à jours en continu, des articles publiés chaque minute par exemple, la génération et le déploiement continu n'est pas la meilleure option.
• Moins d'options de modélisation de contenu et de formatage.

Les CMS API-first

Avec les CMS dotés d'une API par défaut, vous avez accès à une API, généralement une API REST ou GraphQL, qui sert le contenu. Donc, vous récupérez vos données de la façon dont elles sont structurées mais c'est à vous de choisir le framework ou le langage que vous allez utiliser pour travailler avec ces données.

Pour

• C'est la meilleure solution si vous maintenez plusieurs applications et sites web qui récupèrent le même contenu structuré.
• Facile à utiliser avec de multiples terminaux client.
• Beaucoup d'options disponibles pour vous permettre de personnaliser le CMS.
• Vous avez des quantités très importantes de données à gérer.

Contre

• Pas de gestion de version dans Git, ni d'intégration dans le workflow de développement.
• Va souvent de paire avec une limitation de stockage ou d'utilisation de l'API. Peut revenir cher si vous ne calculez pas bien votre coût.
• Dépendance aux développeurs pour des gros changements.

Maintenant que nous savons tout cela, regardons de plus près les bénéfices et les défauts de ces systèmes que vous devriez gardez en tête lors du choix du headless CMS pour votre prochain projet.

Les bénéfices des CMS basés sur Git

La gestion de version multi-objets

Les plates-formes de CMS traditionnelles comme Drupal, Kirby, ou Wordpress proposent un gestion de version limitée, soit elle surveillent les graphes d'un unique objet soit elles maintiennent des structures de données bancales.

Cette approche ne pose pas de problèmes pour des besoins de gestion de contenu basiques — par exemple un blog ou un site web très simple, mais elle est loin d'offrir une expérience numérique multi-fichiers, qui est une nécessité pour la plupart des marques de nos jours.

Bien souvent, il existe une relation entre le contenu et le code (CSS ou JavaScript) et cela doit être pris en compte. Surveiller les modifications unitaires ne suffit pas.

La possibilité de restaurer la version précédente d'un fichier peut suffire pour un besoin éditorial basique mais pas pour la majorité des scénarios dans la vraie vie comme des audits d'accessibilité, un renouvellement d'identité de marque, et de futurs développements qui demandent un CMS plus sophistiqué.

C'est pourquoi une approche de gestion de version des différents types de fichiers, comme celle utilisée par les développeurs est nécessaire. De plus Git est aujourd'hui le système de gestion de version le plus populaire pour surveiller les changements dans le code source et on comprend aisément pourquoi l'expérience numérique actuelle nécessite à la fois des composants techniques et du contenu.

Dépôt distribué

Contrairement aux CMS traditionnels, Git permet aux développeurs d'avoir leurs propres dépôts locaux et intermédiaires, tous issus d'un dépôt parent.

La gestion de version distribuée et le flux de développement sont simples et rapides.

Avec un système basé sur Git, les développeurs peuvent travailler en local tout en faisant parti du CMS. Ainsi ils peuvent continuer d'utiliser au quotidien leurs outils de prédilection, sans restriction aucune.

Ramifications

Grâce aux branches de Git, vous pouvez créer un nombre illimité d'environnements, ce qui facilite en général pas mal le développement.

Les développeurs ainsi que les auteurs peuvent expérimenter et travailler en parallèle sur des fonctionnalités majeures et des améliorations du site.

NdT: la conférence de Shawn Erquhart explique en détail pourquoi les CMS basés sur Git sont des outils plus puissants qu'il n'y paraît.

Les bénéfices des CMS basés sur des APIs

Atteindre les consommateurs sur des terminaux variés

Beaucoup de personnes se tournent aujourd'hui vers des appareils à commande vocale comme Amazon Echo et Google Home pour écouter les actualités, faire leurs achats en ligne, définir des rappels, rechercher sur le web, etc.

Les plate-formes traditionnelles de gestion de contenu, ne peuvent fournir ce type d'expérience utilisateur, contrairement aux CMS qui fournissent une API de contenu. Les marques doivent donc développer une API pour ces terminaux pour les faire communiquer avec leur système.

Vous pouvez alors fournir différentes expériences sur absolument n'importe quel périphérique sans restriction aucune.

Meilleure intégration pour le marketing

Dans un environnement basé sur une API de contenu, les marques peuvent greffer leurs applications marketing préférées comme des outils d'automatisation, un CRM ou des services d'analyse. Elles peuvent aussi décider à tout moment de ne plus les intégrer. Cela donne la possibilité aux marques d'adapter rapidement leur stratégie digitale comme elles l'entendent.

Rediffusion du contenu plus rapide

Avec les CMS basés sur des APIs, tous vos contenus sont stockés en un unique point central qui permet aux marques de publier leurs contenus sur différents canaux. Les créateurs de contenus écrivent donc une seule fois et peuvent les rediffuser sur chaque canal ou terminal. Dans le monde omnicanal d'aujourd'hui, c'est un gros avantage et un énorme gain de temps car il éviter à avoir à créer séparément des contenus pour chaque canal.

Les défis posés par les CMS basés sur Git

Adopter des mesures spécifiques pour le SEO

Faute de solution dédiée, l'amélioration du SEO avec Git dépendra de vous. Pour bénéficier d'une meilleure visibilité, vous devrez vous assurer de la compatibilité mobile de votre site, de la génération de sitemap, de l'insertion des balises meta et open graph.

Les limitations de GitHub Pages

GitHub Pages est gratuit mais ne supporte par défaut que quelques plugins Jekyll, si vous utilisez un autre générateur ou que vous utilisez d'autres plugins, il est toujours possible de générer vos contenus localement, via GitHub Actions ou autre plate-forme d'intégration continue ².

Les défis posés par les CMS basés sur des APIs

Une grande dépendance aux développeurs web

Créer plusieurs interfaces client personnalisées, représente un travail supplémentaire pour votre équipe. Cela demandera donc une communication constante entre les équipes marketing et celles de développements dès que des modifications devront être apportées. ³

(Pour certains) la prévisualisation de contenu est problématique

Les CMS d'APIs de contenu proposent des interfaces d'administration qui permettent aux éditeurs d'entrer leur contenu. Toutefois, tous les CMS ne permettent pas une prévisualisation avant publication, même chose pour la gestion des brouillons qui devra être ajoutée manuellement. Ne pas pouvoir juger du rendu utilisateur final est souvent un inconvénient qui laisse peu de place à l'erreur.

Les coûts

Vous devrez gardez en tête les coûts induits par l'utilisation des CMS qui proposent des APIs de contenu, même ceux qui sont open source. Cela inclut les coûts d'infrastructure (hébergement, CDNs, etc. pour les CMS à héberger soi-même) mais aussi les coûts de développement, de maintenance et de sécurité, puisque vous travaillerez avec une interface d'administration entièrement personnalisée.

Alors quel CMS headless devez vous choisir ?

Ce n'est pas une question à laquelle il est facile de répondre. Par exemple, nous nous sommes rendus compte que si vous n'avez pas besoin de créer des centaines d'articles ou de pages, et régénérer le site constamment, les CMS basés sur Git sont une bien meilleure option.

Bien entendu, cela dépend surtout de vos besoins. C'est à l'ensemble de votre équipe (marketing et développement) de bien comprendre la taille, le budget et le temps (oui c'est aussi un facteur de décision) consacré au projet, en plus de toutes les technologies à l'œuvre derrière.

Liste de plate-formes CMS basées sur Git

• Forestry - https://forestry.io
• Netlify CMS - https://www.netlifycms.org
• TinaCMS - https://tinacms.org
• Publii - https://getpublii.com
• Prose - http://prose.io
• Crafter CMS - https://craftercms.org

Liste de plates-formes CMS basées sur des APis

• Sanity - https://sanity.io
• Dato CMS - https://www.datocms.com/
• Strapi - https://strapi.io
• Storyblok - https://www.storyblok.com/
• Prismic - https://prismic.io
• Contentful - https://www.contentful.com
• Ghost - https://ghost.org
• Cloud CMS - https://www.cloudcms.com
• Directus - https://directus.io
• Rooftop - https://www.rooftopcms.com

Développer un site multilingue avec un générateur de site statique est à la portée de tous dès lors que l'on dispose d'un langage de templating, de données structurées et d'un système permettant de contrôler les URLs, ce que proposent la plupart des générateurs de sites statiques.

Il existe beaucoup d'articles sur le sujet, comme celui que nous avons publié sur la gestion d'un site multilingue avec Eleventy. Hugo dispose d'une documentation très claire sur le sujet, de nombreux articles en font de même pour Jekyll.

Notre but ici est de rediriger depuis une page écrite dans une langue donnée vers les traductions disponibles pour cette même page. Si aucune traduction n'existe pour une page, alors nous redirigerons vers la page d'accueil dans la langue demandée.

Ici, nous utilisons Eleventy, mais l'approche serait similaire avec d'autres générateurs de site statique.

Pour parvenir à nos fins, il nous faut :

1. Pouvoir boucler sur les différents langages utilisés sur le site
2. Nous assurer que chaque contenu dispose d'une clé locale dont la valeur correspond au code de langue utilisé pour ce même contenu. Si vous avez besoin de vous rafraîchir la mémoire, relisez comment faire avec les fichiers de données de répertoire avec Eleventy.
3. Définir une clé commune unique nommée translationKey pour relier les traductions d'un contenu entre elles.

Les langues du site

Nous allons commencer par créer un tableau des langues utilisées par notre site. J'ai pour habitude de définir un objet languages dans le fichier de données ./src/_data/site.js.

module.exports = {
  title: "Webstoemp",
  description:
    "Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.",
  url: "https://www.webstoemp.com",
  baseUrl: "/",
  author: "Jerôme Coupé",
  authorTwitter: "@jeromecoupe",
  buildTime: new Date(),
  languages: [
    {
      label: "english",
      code: "en",
    },
    {
      label: "français",
      code: "fr",
    },
  ],
};

À l'aide de ce tableau nous allons pouvoir parcourir les différentes langues de notre site et comparer la valeur du code de langue avec celui de la locale définie dans nos fichiers de contenu.

Ajout des clés de traduction

Maintenant il nous faut créer une relation explicite entre les différentes traductions d'un même contenu. Avec un générateur de site statique qui stocke les données dans des fichiers, nous pouvons utiliser une même clé dans le front matter YAML de ces fichiers. Cette clé de traduction est une chaîne de caractère qui doit être unique pour chaque contenu.

Par exemple, pour connecter entre elles nos pages de contact dans différentes langues, nous pouvons utiliser :

./src/en/pages/about.njk

---
permalink: "/{{ locale }}/about/index.html"
translationKey: "about-page"
---

./src/fr/pages/about.njk

---
permalink: "/{{ locale }}/a-propos/index.html"
translationKey: "about-page"
---

Nous pouvons appliquer le même principe à nos documents de collections, par exemple pour les articles de blog :

./src/en/bogposts/2019-09-12-my-awesome-blogpost.njk

---
title: "My awesome blogpost"
translationKey: "awesome-blogpost"
---

./src/fr/bogposts/2019-09-12-mon-magnifique-article-de-blog.njk

---
title: "Mon magnifique article de blog"
translationKey: "awesome-blogpost"
---

Nous disposons maintenant d'une relation explicite entre les traductions de nos contenus en différentes langues.

Coder notre sélecteur de langue

Voici le détail de ce que nous allons faire avec ce petit morceau de code:

1. Boucler sur toutes les langues déclarées de notre site
2. Définir la page d'accueil comme valeur par défaut de translatedUrl, valeur qui sera remplacée lorsqu'une traduction de contenu est trouvée.
3. Dans cette boucle, parcourir tous les contenues du site. Eleventy nous fourni une méthode très pratique avec collections.all.
4. Pour chaque contenu parcouru, vérifier si la clé translationKey correspond et si sa locale correspond au code de langue en cours. Si une correspondance est trouvée, alors définir translatedUrl avec l'URL de ce contenu.
5. Utiliser les valeurs de translatedUrl pour créer les liens de notre sélecteur de langue.

{# Boucler sur les langues du site #}
{% for lgg in site.languages %}
  {% if loop.first %}<ul class="c-lggnav">{% endif %}

  {# Définir translatedUrl à la page d'accueil de cette langue par défaut #}
  {% set translatedUrl = "/" + lgg.code + "/" %}

  {# Définir la classe de la langue active #}
  {% set activeClass = "is-active" if lgg.code == locale else "" %}

  {# Parcourir tous les contenus du site #}
  {% for item in collections.all %}

    {# Pour chaque contenu, vérifier si
    - la valeur de sa translationKey correspond à celle du contenu en cours
    - sa locale correspond au code de langue parcourue #}
    {% if item.data.translationKey == translationKey and item.data.locale == lgg.code %}
      {% set translatedUrl = item.url %}
    {% endif %}

  {% endfor %}

  <li class="c-lggnav__item">
    <a class="c-lggnav__link  {{ activeClass }}" href="{{ translatedUrl }}">{{ lgg.label }}</a>
  </li>

  {% if loop.last %}</ul>{% endif %}
{% endfor %}

Et voilà, mission accomplie avec un effort minime. Ces boucles seront déclenchées pour chaque page de site. Comme Eleventy a de toute façon déjà créé collections.all et qu'il est assez performant en entrée-sortie, l'impact sur le temps de génération du site devrait être assez faible, même pour de gros sites.

Si vous avez besoin d'ajouter un CMS headless à votre site web, vous avez le choix entre deux approches : soit le contenu est versionné dans votre dépôt Git, soit il est accessible via une API tierce.

Dans les deux cas, les créateurs de contenu ont accès à une interface graphique, mais ce qui se passe en coulisses quand du contenu est crée, modifié ou effacé est totalement différent.

Les CMS headless basés sur Git

Les CMS basés sur Git comme Netlify CMS ou Forestry vont sauvegarder votre contenu dans des fichiers texte et les sauvegarder dans votre dépôt Git. C'est l'approche que je préfère pour les raisons suivantes :

• code et contenu partagent le même workflow
• le contenu est versionné par Git avec un historique clair
• le contenu stocké sous forme de fichiers texte (markdown, YAML, JSON, etc.) est extrêmement portable

Les APIs de CMS headless

Les CMS basés sur des APIs comme Contentful ou DatoCMS vont sauvegarder vos contenus dans le Cloud et vont le rendre accessible via une API. GraphQL est en passe de devenir une façon populaire d'interroger et de tirer parti de ces APIs. Selon moi, cette approche présente de l'intérêt lorsque :

• le contenu est destiné à être publié sur différentes plateformes
• vos modèles de données sont hautement relationnels

Structure du projet

Eleventy(11ty), qui est en passe de devenir mon générateur de site statique de prédilection, est à même de pouvoir travailler avec les deux approches de façon assez élégante et avec un minimum d'efforts.

Qui aurait pensé faire une requète sur une API GraphQL et utiliser les données retournées pour générer des pages statiques serait aussi simple ?

DatoCMS est un CMS headless que je recommande à mes clients. Son prix est raisonnable, il propose des options suffisantes et reste très flexible, il gère élégamment l'internationalisation, et propose une bonne expérience utilisateur et de développement.

Si cet article est écrit pour DatoCMS, cette méthodologie est appliquable à tout CMS headless offrant une API GraphQL.

Voici l'arborescence de fichiers classique avec laquelle nous allons travailler dans Eleventy :

+-- src
  +-- _data
    +-- blogposts.js
  +-- _includes
    +-- layouts
      +-- base.njk
  +-- blogposts
    +-- entry.njk
    +-- list.njk
+-- .eleventy.js
+-- .env
+-- .env.example
+-- package-lock.json
+-- package.json

Configuration de DatoCMS

Après avoir crée notre compte, nous avons besoin d'un modèle de données et de quelques entrées dans DatoCMS. J'ai crée un modèle de données nommé blogposts avec une série de champs et quelques entrées.

Nous pouvons alors utiliser notre token d'API pour nous connecter à l'explorateur de l'API GraphQL afin de visualiser les requêtes et les options disponibles, ainsi que le JSON qui nous est retourné.

Une fois encore, la plupart des CMS headless avec une API GraphQL offrent cette fonctionnalité d'une manière ou d'une autre.

Configuration d'Eleventy

Nous allons devoir nous authentifier au serveur GraphQL de DatoCMS avec notre token d'API. Nous pouvons utiliser dotenv pour le stocker dans un fichier .env que nous ajouterons à notre fichier .gitignore pour éviter qu'il ne soit stocké dans notre dépôt Git. Après avoir installé le paquet, nous créons le fichier .env à la racine du projet et y ajoutons le token de l'API de DatoCMS :

DATOCMS_TOKEN="fak3t0k3n3c52750d04b3d92383b1d"

Ensuite, il nous faut ajouter la ligne suivant au début de notre fichier de configuration .eleventy.js :

require("dotenv").config();

Étant donné que ce fichier est traité très tôt par Eleventy, notre token sera accessible dans tous nos templates via process.env.DATOCMS_TOKEN.

Utilisation des fichiers de données JavaScript

Au lieu d'aller piocher nos données à l'aide de collections et de fichiers Markdown avec du front matter en YAML, nous allons utiliser les fichiers de données JavaScript d'Eleventy. Nous utiliserons le fichier src/_data/blogposts.js pour nous connecter à la content delivery API de DatoCMS lors de la génération du site, afin d'exporter un fichier JSON contenant tous les articles de blog avec les champs dont nous avons besoin. Le contenu de ce fichier sera accessible dans nos templates via l'objet blogposts.

Eleventy sera alors en mesure d'utiliser ce fichier JSON pour générer les pages de détail et d'index de notre blog.

Çi-dessous, le fichier complet nécessaire pour récupérer tous nos articles de blog, qui se base sur le code de la requête en Vanilla JS donné en exemple dans la documentation de DatoCMS.

Afin de miniser les dépendances, j'ai privilégié l'utilisation de node-fetch à celle d'Appolo et consorts.

Par défaut l'API GraphQL de DatoCMS limite à 100 le nombre d'enregistrements retournés par requête (merci à Dan Fascia pour sa remarque). Si notre blog comporte plus de 100 entrées, il va donc nous falloir faire plusieurs requêtes et concaténer les résultats pour récupérer l'intégralité de nos articles de blog.

// paquets requis
const fetch = require("node-fetch");

// token de DatoCMS
const token = process.env.DATOCMS_TOKEN;

// récupération des articles de blog
// voir https://www.datocms.com/docs/content-delivery-api/first-request#vanilla-js-example
async function getAllBlogposts() {
  // nombre maximal d'enregistrements retournés par requête
  const recordsPerQuery = 100;

  // nombre d'enregistrements à ignorer (démarre à 0)
  let recordsToSkip = 0;

  // Devons nous faire une nouvelle requête ?
  let makeNewQuery = true;

  // Tableau pour stocker les articles de blog
  let blogposts = [];

  // Effectuer des requpêtes jusqu'à ce que makeNewQuery passe à faux
  while (makeNewQuery) {
    try {
      // Initialisation du téléchargement
      const dato = await fetch("https://graphql.datocms.com/", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Accept: "application/json",
          Authorization: `Bearer ${token}`
        },
        body: JSON.stringify({
          query: `{
            allBlogposts(
              first: ${recordsPerQuery},
              skip: ${recordsToSkip},
              orderBy: _createdAt_DESC,
              filter: {
                _status: {eq: published}
              }
            )
            {
              id
              title
              slug
              intro
              body(markdown: true)
              _createdAt
              image {
                url
                alt
              }
              relatedBlogs {
                id
              }
            }
          }`
        })
      });

      // Enregistrment de la réponse JSON lorsque la promesse est résolue
      const response = await dato.json();

      // Gestion des erreurs DatoCMS
      if (response.errors) {
        let errors = response.errors;
        errors.map((error) => {
          console.log(error.message);
        });
        throw new Error("Aborting: DatoCMS errors");
      }

      // mise à jour du tableau des articles avec les données retournées par la réponse en JSON
      blogposts = blogposts.concat(response.data.allBlogposts);

      // itération des valeurs pour la prochaine requête
      recordsToSkip += recordsPerQuery;

      // Vérification du nombre d'enregistrements retourné
      // S'il y en a moins de 100, on arrête de faire des requêtes
      if (response.data.allBlogposts.length < recordsPerQuery) {
        makeNewQuery = false;
      }
    } catch (error) {
      throw new Error(error);
    }
  }

  // mise en forme de l'objet blogposts
  const blogpostsFormatted = blogposts.map((item) => {
    return {
      id: item.id,
      date: item._createdAt,
      title: item.title,
      slug: item.slug,
      image: item.image.url,
      imageAlt: item.image.alt,
      summary: item.intro,
      body: item.body,
      relatedBlogs: item.relatedBlogs
    };
  });

  // retour de l'objet formatté
  return blogpostsFormatted;
}

// export pour 11ty
module.exports = getAllBlogposts;

Plutôt que d'utiliser directement les données de la réponse JSON, je la mets généralement en forme pour améliorer la maintenabilité future de mes templates. Si quelque chose change au niveau du CMS, je sais que j'aurais seulement à mettre à jour les fichiers de données, et non tous les templates qui les utilisent.

Les images et les vignettes

Les fichiers et les images uploadés dans DatoCMS sont stockés sur Imgix, nous pouvons donc ajouter des paramètres à chaque URL d'images pour les redimensionner, les retailler et les manipuler de diverses manières. Ces transformations se vont à la volée et sont ensuite mises en cache sur le CDN pour les utilisations ultérieures.

La majorité des CMS headless offrent des fonctionnalités similaires, soit en intégrant des services tiers comme Cloudinary ou Uploadcare, soit en proposant leur propre API pour les images.

Champs relationnels

L'API GraphQL de DatoCMS gère très bien les structures de données hautement imbriquées et vous permettra de récupérer les données voulues dans vos champs relationnels. Toutefois, j'adopte généralement une approche plus simple :

• Je crée un gros fichier JSON pour chaque type de données (articles, projets, évènements, etc.), chaque élément possède un identifiant unique.
• Pour les champs relationnels, je récupère seulement l'identifiants des élements relatifs.
• J'utilise des boucles imbriquées dans les templates pour récupérer les données à l'aide des identifiants.

Comme les générateurs de site statique performants comme Hugo ou Eleventy n'ont pas une empreinte mémoire importante lors du parcours de boucles dans les templates, je n'ai jamais fait face à des soucis de performance avec cette approche. C'est à la fois très flexible et vos requêtes s'en retrouvent simplifiées.

Générer une liste paginée des articles de blog avec 11ty

Grâce à la fonctionnalité pagination d'Eleventy, nous pouvons parcourir notre fichier JSON (accessible via l'objet blogposts) et générer une liste paginée des articles de blog. Dans cet exemple, nous allons générer une liste de pages contenant chacune 12 éléments, grâce à la clé size.

Voici le code complet du fichier src/blogposts/list.njk :

---
pagination:
  data: blogposts
  size: 12
permalink: blog{% if pagination.pageNumber > 0 %}/page{{ pagination.pageNumber + 1}}{% endif %}/index.html
---

{% extends "layouts/base.njk" %}
{% set htmlTitle = item.title %}

{% block content %}
  <h1>Blogposts</h1>

  {# boucler sur les éléments paginés #}
  {% for item in pagination.items %}
    {% if loop.first %}<ul>{% endif %}
      <li>
        <p><img src="{{ item.image }}?fit=crop&amp;w=200&amp;h=200" alt="{{ item.imageAlt }}"></p>
        <h2><a href="/blog/{{ item.slug }}">{{ item.title }}</a></h2>
        <p><time datetime="{{ item.date | date('Y-M-DD') }}">{{ item.date|date("MMMM Do, Y") }}</time></p>
        <p>{{ item.summary }}</p>
      </li>
    {% if loop.last %}</ul>{% endif %}
  {% endfor %}

  {# pagination #}
  {% if pagination.hrefs | length > 0 %}
  <ul>
    {% if pagination.previousPageHref %}
      <li><a href="{{ pagination.previousPageHref }}">Previous page</a></li>
    {% endif %}
    {% if pagination.nextPageHref %}
      <li><a href="{{ pagination.nextPageHref }}">Next page</a></li>
    {% endif %}
  </ul>
  {% endif %}

{% endblock %}

Générer les pages individuelles pour les articles dans 11ty

Nous pouvons nous reposer sur la même fonctionnalité pour générer également toutes les pages individuelles. La seule astuce ici est de spécifier le nombre d'élements de chaque page comme égal à 1 et de définir les permaliens de façon dynamique. Voici le code complet pour src/blogposts/entry.njk:

---
pagination:
  data: blogposts
  size: 1
  alias: blogpost
permalink: blog/{{ blogpost.slug }}/index.html
---
{% extends "layouts/base.njk" %}
{% set htmlTitle = blogpost.title %}

{% block content %}
  {# blogpost #}
  <img src="{{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576"
       srcset="{{ blogpost.image }}?fit=crop&amp;w=600&amp;h=338 600w,
               {{ blogpost.image }}?fit=crop&amp;w=800&amp;h=450 800w,
               {{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576 1024w"
       sizes="100vw"
       class="u-fluidimg"
       alt="{{ blogpost.imageAlt }}">

  <h1>{{ blogpost.title }}</h1>
  <p><time datetime="{{ blogpost.date | date('Y-M-DD') }}">{{ blogpost.date|date("MMMM Do, Y") }}</time></p>
  <p>{{ blogpost.intro }}</p>
  {{ blogpost.body | safe }}

  {# Articles relatifs #}
  {% if blogpost.relatedBlogs|length %}
    <h2>Vous pourriez aussi aimer</h2>
    <ul>
    {% for item in blogpost.relatedBlogs %}
      {% for post in blogposts %}
        {% if post.id == item.id %}
          <li>
            <a href="/blog/{{ post.slug }}">{{ post.title }}</a>
          </li>
        {% endif %}
      {% endfor %}
    {% endfor %}
    </ul>
  {% endif %}
{% endblock %}

Déclencher automatiquement les builds

La plupart des CMS headless fournissent des webhooks qui vont envoyer une requête à une URL lorsque les données sont modifiées. Si vous hébergez votre site chez Netlify (vous devriez, c'est un super service), il suffit de quelques clics pour créer un hook entrant qui déclenchera la génération de votre site. à chaque reception d'une requête POST.

DatoCMS propose le déploiement en 1 clic grâce à son intégration avec Netlify. Il vous suffit de l'activer et voilà, votre blog sera généré à chaque fois que les données seront mises à jour.

Nous disposons maintenant d'un blog qui combine la puissance d'une base de données relationnelle avec la rapidité et la stabilité d'un site statique, hébergé sur CDN.

Eleventy n'offre pas de fonctionnalités natives liées au multilinguisme et à la localisation, cela ne nous empêche aucunement de développer une bonne gestion du multilingue à l'aide de fichiers de données globales, de collections en utilisant Nunjucks comme langage de templating.

Afin d'illustrer notre propos, nous allons développer un blog multilingue tout ce qu'il y a de plus classique.

Voici l'arborescence de fichiers avec laquelle nous allons travailler. C'est une architecture Eleventy standard, dont les principes et les techniques peuvent être appliqués à des projets plus importants.

+-- src
  +-- _data
    +-- site.js
    +-- footer.js
    +-- header.js
  +-- _includes
    +-- layouts
      +-- base.njk
    +-- partials
      +-- header.njk
      +-- footer.njk
  +-- en
    +-- pages
      +-- index.html
      +-- blog.html
      +-- contact.html
    +-- posts
      +-- yyyy-mm-dd-some-blogpost.md
      +-- posts.json
    +-- en.json
  +-- fr
    +-- pages
      +-- index.html
      +-- blog.html
      +-- contact.html
    +-- posts
      +-- yyyy-mm-dd-some-blogpost.md
      +-- posts.json
    +-- fr.json
+-- .eleventy.js

Définition des locales

La première consiste à créer nos locales à l'aide des fichiers de données pour les répertoires.

Pour cela il nous suffit d'ajouter les fichiers en.json and fr.json dans nos répertoires de langues. Dans chacun d'entre eux, nous définissons une clé locale. Elle va permettre d'accéder aux valeurs correspondantes dans tous les fichiers de layout présents dans les sous-répertoires d'un dossier de langue.

Par exemple, notre fichier fr.json contient :

{
  "locale": "fr"
}

{{ locale }} va donc maintenant retourner "fr" ou "en" pour chacun de nos fichiers de layout, en fonction de sa position dans notre arborescence de fichiers.

Filtre de localisation de date

Nunjucks ne possède pas de filtre pour les dates. Nous pouvons en créer un à l'aide de moment.js et lui passer la valeur de notre locale pour qu'il localise les dates pour nous, ce qui est toujours une partie importante des projets multilingues.

Pour ce faire, nous allons insérer le code suivant dans notre fichier de configueration eleventy.js :

// date filter (localized)
eleventyConfig.addNunjucksFilter("date", function (date, format, locale) {
  locale = locale ? locale : "en";
  moment.locale(locale);
  return moment(date).format(format);
});

À présent, nous pouvons utiliser ce filtre dans nos layouts et lui passer le paramètre locale. Notez bien que comme nous avons défini la locale par défaut comme en, nous pouvons omettre de la préciser pour les dates purement numériques. Un petit exemple :

<p><time datetime="{{ post.date | date('Y-MM-DD') }}">{{ post.item|date("DD MMMM Y", locale) }}</time></p>

Maintenant que nos dates sont automatiquement localisées, passons aux collections.

Localisation des collections

Nous allons pouvoir tirer parti de notre arborescence de fichiers pour créer des collections dans Eleventy. Le plus simple est encore de créer une collection par langue. Nous utilisons pour cela la fonction getFilteredByGlob dans notre fichier eleventy.js.

module.exports = function (eleventyConfig) {
  eleventyConfig.addCollection("posts_en", function (collection) {
    return collection.getFilteredByGlob("./src/en/posts/*.md");
  });
};

module.exports = function (eleventyConfig) {
  eleventyConfig.addCollection("posts_fr", function (collection) {
    return collection.getFilteredByGlob("./src/fr/posts/*.md");
  });
};

Comme nos fichiers de contenu Markdown se trouvent dans des sous-répertoires de nos dossiers de langues, la variable locale est accessible. Nous pouvons par exemple l'utiliser pour créer les permaliens de tous nos articles.

Plutôt que d'ajouter une variable permalink dans le front matter de chaque fichier, nous pouvons créer un fichier de données posts.json dans chacun de nos dossiers posts avec le contenu suivant:

{
  permalink: "/{{ locale }}/blog/{{ page.fileslug }}/index.html";
}

Nous avons ainsi localisé toutes les pages de détail de tous nos articles, il nous reste encore à boucler sur nos collections dans les différentes pages blog.njk de nos différentes langues.

{% for post in collections.posts_en | reverse %}
  {% if loop.first %}<ul>{% endif %}
    <li>

      <article>
        <p><time datetime="{{ post.date | date('Y-MM-DD') }}">{{ post.date | date("DD MMMM[,] Y", locale) }}</time></p>
        <h3><a href="{{ post.url }}">{{ post.data.title }}</a></h3>
      </article>

    </li>

  {% if loop.last %}</ul>{% endif %}
{% endfor %}

Notez que nous pourrions aussi aussi utiliser pour nos collections notre variable locale. Il faudrait pour cela utiliser à la place une notation entre crochets pour concaténer les chaînes de caractères.

{% set posts = collections["posts_" + locale] %}
{% for post in posts %}
  {# loop content #}
{% endfor %}

Localisation des layouts et des fichiers partiels

Alors que la duplication de nos pages et de nos articles est à priori logique, nous ne voulons pas faire de même pour nos layouts et nos fichiers partiels.

Fort heureusement, nous pouvons éviter cela en traduisant simplement certaines chaînes de caractères. Pour ce faire, nous devons créer des fichiers de données génériques qui contiendront nos traductions sous forme de paire clés/valeurs. Nous pourrons ensuite faire référence dynamiquement à ces clés dans nos fichiers partiels et de layouts à l'aide de notre chère variable locale.

Layouts

Commençons par un exemple dans un fichier de layout.

Le fichier ./src/_data/site.js va rendre accessibles des variables via l'objet site.

module.exports = {
  buildTime: new Date(),
  baseUrl: "https://www.mysite.com",
  name: "mySite",
  twitter: "@handle",
  en: {
    metaTitle: "Title in english",
    metaDescription: "Description in english",
  },
  fr: {
    metaTitle: "Titre en français",
    metaDescription: "Description en français",
  },
};

Nous pouvons utiliser ces variables dans notre fichier ./src/fr/pages/index.njk. Dans notre exemple, nous allons d'abord assigner les valeurs à des variables Nunjucks plutôt que de les utiliser directement, car ces valeurs nous pourrions avoir besoin de les surcharger dans d'autres pages. La même logique peut être appliquée pour les modèles de page spécifiques aux articles.

---
permalink: /{{ locale }}/index.html
---

{% extends "layouts/base.njk" %}

{% set metaTitle = site[locale].metaTitle %}
{% set metaDescription = site[locale].metaDescription %}
{% set metaImage = site[locale].metaImage %}

{% block content %}
  {# page content #}
{% endblock %}

Puisque ce layout étend le fichier ./src/_includes/layouts/base.njk, les variables Nunjucks déclarées dans le gabarit enfant ainsi que les variables globales d'Eleventy sont également accessibles dans ce fichier.

<!DOCTYPE html>
<html lang="{{ locale }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>{{ metaTitle }}</title>
  <link rel="stylesheet" href="/css/main.min.css">

  <!-- open graph -->
  <meta property="og:type" content="article">
  <meta property="og:title" content="{{ metaTitle }}">
  <meta property="og:image" content="{{ metaImage }}">
  <meta property="og:site_name" content="{{ site.name }}">
  <meta property="og:description" content="{{ metaDescription }}">

  <!-- twitter -->
  <meta name="twitter:card" content="summary">
  <meta name="twitter:site" content="{{ site.twitter }}">
  <meta name="twitter:title" content="{{ metaTitle }}">
  <meta name="twitter:description" content="{{ metaDescription }}">
  <meta name="twitter:image" content="{{ metaImage }}">
</head>
<body>
  {% include "partials/siteheader.njk" %}
  {% block content %}{% endblock %}
  {% include "partials/sitefooter.njk" %}
</body>
</html>

Fichiers partiels

La traduction de fichiers partiels comme ./src/_includes/partials/footer.njk est basée sur le même principe.

Premièrement, nous créons un fichier ./data/footer.js et nous utilisons nos locales comme clés.

module.exports = {
  mapUrl: "https://goo.gl/maps/3YTkhCgfEgj1PRAd7",
  fr: {
    addressTitle: "Adresse",
    addressStreet: "Rue du marché",
    addressNumber: "42",
    addressPostcode: "1000",
    addressCity: "Bruxelles",
    directionsLabel: "Itinéraire",
  },
  en: {
    addressTitle: "Address",
    addressStreet: "Market street",
    addressNumber: "42",
    addressPostcode: "1000",
    addressCity: "Brussels",
    directionsLabel: "Directions",
  },
};

Ensuite dans le fichier ./src/_includes/partials/footer.njk, nous nous basons sur la valeur de notre variable locale pour accéder à ces clés à l'aide de la notation entre crochets.

<footer>
  <h2>{{ footer[locale].addressTitle }}</h2>
  <p>
    {{ footer[locale].addressStreet }}, {{ footer[locale].addressNumber }}<br>
    {{ footer[locale].addressPostcode }}, {{ footer[locale].addressCity }}
  </p>
  <p><a href="{{ footer.mapUrl }}">{{ footer[locale].directionsLabel }}</a></p>
</footer>

Et voilà, nous avons maintenant un pied de page traduit en plusieurs langues.

Flexible par nature

Les générateurs de site statiques sont très flexibles quant aux structures de données que vous pouvez créer. Eleventy est l'un des générateurs les plus flexibles qu'il m'ait été donné d'utiliser, ce qui en fait un bon candidat pour créer une structure de données multilingue, adaptable à tout type de projet.

Eleventy n'en finit pas de faire des émules, il séduit par sa simplicité et sa flexibilité, Jérôme Coupé a sauté le pas à son tour et il est très satisfait de son choix.

Jekyll est un générateur que je continue d'apprécier, d'utiliser et de suivre, néanmoins quand j'ai enfin eu le temps de mettre à jour mon site, j'ai choisi de partir sur Eleventy.

Choisir un générateur de site

Les générateurs de site statiques gagnent toujours plus en popularité, grâce à l'omniprésence des APIs, aux processus de développement basés sur Git, à la puissance des frameworks JavaScript, aux CMS headless et aux couches de données unifiées fournies par GraphQL. Ils sont devenus un choix raisonnable pour tous types de sites web.

Mon site tournait précédemment sous Jekyll, que j'apprécie pour sa facilité d'utilisation et sa flexibilité. Toutefois, il était devenu plus lent que d'autres générateurs plus récents et me forçait à maintenir un environnement Ruby à jour. J'ai testé plusieurs outils, avant de finalement restreindre ma liste de choix à Hugo et Eleventy.

Hugo

Écrit en Go, Hugo est extrèmement rapide. il est également disponible sous forme de fichier binaire, ce qui ne vous force pas à maintenir un environnement Go. A titre d'expérience, j'ai développé la version 2 de mon site avec Hugo et l'exercice a été concluant.

Cependant, les inconvénients d'Hugo sont pour moi la syntaxe de Go HTML template qui demande pas mal de pratique pour être apprivoisée, et le fait qu'Hugo soit une solution "tout en un". Cela peut se révéler utile pour les gros projets, mais réduit les possibilités de l'étendre facilement.

Eleventy

Ce qui nous amène à Eleventy. Eleventy est écrit en Node, vous avez donc accès à tout l'écosystème de NPM pour l'étendre, il est facile d'utilisation, et il est bien plus rapide que Jekyll (sans cependant atteindre les performances d'Hugo).

De plus Eleventy supporte plusieurs langagues de templating.

Configuration

J'ai opté pour le moteur de templating Nunjucks de Mozilla. Outre cela, je n'avais besoin que de fichiers Markdown et HTML.

Nunjucks n'offre pas de filtres date et limit, je les ai donc ajoutés dans mon fichier de configuration eleventy.js, en utilisant la bibliothèque moment.js pour le filtre de date.

const moment = require("moment");

// limit filter
eleventyConfig.addNunjucksFilter("limit", function (array, limit) {
  return array.slice(0, limit);
});

// date filter
eleventyConfig.addNunjucksFilter("date", function (date, format) {
  return moment(date).format(format);
});

J'utilise Gulp comme outil de génération, j'ai donc dû dire à Eleventy d'ignorer mes assets. Pour ce faire, j'ai simplement ajouté la ligne suivante au fichier .eleventyignore situé à la racine de mon projet:

src/assets/**/*

L'étape suivante a été d'ajouter Eleventy à mon fichier gulpfile.js et d'utiliser la fonction child_process de Node. De cette manière, je peux facilement intégrer Eleventy à mes commandes build et watch.

// packages
const cp = require("child_process");

// Eleventy
function build() {
  return cp.spawn("npx", ["eleventy", "--quiet"], { stdio: "inherit" });
}

Structure de données

Collections

Mon site est simple, je n'avais besoin que de deux collections (blogposts et projects) pour lesquelles j'ai créé deux dossiers contenant des fichiers Markdown avec du front matter YAML.

Eleventy propose une fonctionnalité intéressante qui vous permet d'utiliser des fichiers JSON nommés comme votre dossier de collection pour déclarer des valeurs front matter communes à tous les fichiers du répertoire.

Par exemple, j'ai utilisé un fichier blogposts.json dans mon dossier blogposts pour définir le layout et la structure des permaliens pour tous les articles de blog.

{
  "layout": "layouts/blogpost.njk",
  "permalink": "blog/{{ page.fileSlug }}/index.html"
}

Les projets quant à eux n'ont pas besoin de pages de détail, j'ai donc spécifié la valeur de permalink à false dans le fichier projects.json de mon dossier projects et je n'ai pas défini de layout.

{
  "permalink": false
}

Pour créer les deux collections et permettre à Eleventy de générer les fichiers HTML, j'ai utilisé la fonction getFilteredByGlob( glob ) dans mon fichier eleventy.js:

const moment = require("moment");

module.exports = function (eleventyConfig) {
  // blogpost collection
  eleventyConfig.addCollection("blogposts", function (collection) {
    return collection.getFilteredByGlob("./src/blogposts/*.md");
  });

  // projects collection
  eleventyConfig.addCollection("projects", function (collection) {
    return collection.getFilteredByGlob("./src/projects/*.md");
  });

  // limit filter
  eleventyConfig.addNunjucksFilter("limit", function (array, limit) {
    return array.slice(0, limit);
  });

  // date filter
  eleventyConfig.addNunjucksFilter("date", function (date, format) {
    return moment(date).format(format);
  });

  // Base config
  return {
    dir: {
      input: "src",
      output: "dist",
    },
  };
};

Les fichiers de données

Eleventy vous laisse aisément travailler avec des fichiers de données aux format JSON ou JS situés par défaut dans le sous-dossier _data de votre répertoire de base (src dans mon cas).

J'ai donc utilisé un fichier ./src/_data/site.js pour définir des variables globales du site, auxquelles je peux facilement accéder dans n'importe quel fichier en utilisant le nom du fichier de données et une des clés de l'objet correspondant.

module.exports = {
  title: "Webstoemp",
  description:
    "Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.",
  url: "https://www.webstoemp.com",
  baseUrl: "/",
  author: "Jerôme Coupé",
  authorTwitter: "@jeromecoupe",
  buildTime: new Date(),
};

La valeur de site.buildTime peut maintenant être utilisée dans le pied de page du site :

<div class="c-sitefooter__copyright">
  <p class="u-margin-all-none">&copy; Webstoemp {{ site.buildTime | date("Y") }}</p>
</div>

Layouts Nunjucks

J'ai choisi Nunjucks notamment pour son mécanisme d'héritage de layouts. Je peux définir un layout de base et ensuite l'étendre avec d'autres layouts si besoin.

Blogposts

Boucler sur la collection blogposts pour afficher les titres et les dates de publication n'est pas très compliqué:

{% for post in collections.blogposts | reverse %}
  {% if loop.first %}<ul class="c-list-ui">{% endif %}
  <li>
    <article class="c-blogteaser">
      <p class="c-blogteaser__date"><time datetime="{{ post.date | date('Y-M-DD') }}">{{ post.date|date("MMMM Do, Y") }}</time></p>
      <h2 class="c-blogteaser__title"><a href="{{ post.url }}">{{ post.data.title }}</a></h2>
    </article>
  </li>
  {% if loop.last %}</ul>{% endif %}
{% else %}
  <p>No blogpost found</p>
{% endfor %}

J'utilise un layout dédié pour afficher le détail de chaque article de blog. Le fichier _includes/layouts/blogpost.nkj appelle mon layout principal et ajoute l'image associée à l'article de blog, ainsi que le contenu Markdown au bloc content :

{% extends "layouts/base.njk" %}
{% set activeSection = "blog" %}

{% set metaTitle = title %}
{% set metaDescription = excerpt %}
{% set metaImage = site.url ~ "/img/blogposts/_600x600/" ~ image %}

{% block content %}

  <article class="c-blogpost">
    <div class="c-blogpost__media">
      <div class="l-container">

        <picture>
          <source media="(min-width: 500px)"
                  srcset="/img/blogposts/_1024x576/{{ image }} 1024w,
                          /img/blogposts/{{ image }} 1500w"
                  sizes="(min-width: 1140px) 1140px,
                         100vw">
          <img src="/img/blogposts/_600x600/{{ image }}"
               class="o-fluidimage"
               alt="{{ imageAlt }}">
        </picture>

      </div>
    </div>

    <div class="c-blogpost__body  l-container l-container--narrow">

      <header>
        <p class="c-suptitle  c-suptitle--dark"><time datetime="{{ page.date | date('Y-M-DD') }}">{{ page.date | date("MMMM Do, YYYY") }}</time></p>
        <h1 class="c-h1">{{ title }}</h1>
        <div class="c-blogpost__intro">
          <p>{{ excerpt }}</p>
        </div>
      </header>

      <div class="c-wysiwyg">
        {{ content | safe }}
      </div>

    </div>
  </article>

{% endblock %}

Projects

La même logique est appliquée pour afficher les projets, avec une petite nuance. Comme il n'y a pas de layout dédié pour la collection projects, il nous faut utiliser templateContent pour afficher le contenu des fichiers Markdown. Voici une version simplifiée du code :

{% for project in collections.projects | reverse %}
    {{ project.templateContent | safe }}
{% endfor %}

Satisfait de mon choix

Au final, je suis très content du résultat et d'avoir opté pour Eleventy. Le code source de mon site est publié sur GitHub, si vous avez envie d'aller y jeter un œil.

Imaginons que vous soyez en train de créer la prochaine grande startup ou d'organiser un super évènement — la première question que tout le monde va vous poser est : « C'est quoi le site web ? ».

Une présence en ligne séduisante et fonctionnelle est tout simplement primordial en 2019, que ce soit pour les entreprises, les organisations à but non lucratif ou encore pour le recrutement de nouveaux employés — et il en va de même pour Monetery, l'événement technologique — inclusif — organisé chaque printemps par Dwolla. Nous avions besoin d’un site rapidement opérationnel et performant, nous avons donc d’abord opté pour une solution fiable et éprouvée que nous avions déjà utilisé : GitHub Pages.

Cette solution a été rapidement opérationnelle lorsque nous avons lancé la page d’accueil de Monetery, mais il était évident que nous avions besoin d’une solution plus complète. En raison de notre processus de validation exigeant, la technique est rapidement devenue un obstacle. Nous devions travailler à une meilleure solution afin de migrer nos contributeurs de contenu et effectuer les changements nécessaires rapidement.

Nous avons alors étudié les options qui s’offraient à nous :

1. Mettre en place un outil de gestion de contenu (CMS) traditionnel tel que WordPress
2. Trouver un CMS headless à intégrer dans un générateur de site statique (SSG)

Le nombre de solutions potentielles pour ces deux options est très vaste. Connaissant déjà bien les solutions traditionnelles, nous avons donc fouillé du côté de headlesscms.org et de staticgen.com pour voir ce qui se passait ailleurs. Dwolla offre à son équipe d’ingénieurs du temps dédié au développement professionnel chaque semaine, ce qui nous a permis de tester les solutions potentielles.

L’une des solutions les plus intéressantes que nous avons testées vient de la société Netlify, et de son projet Netlify CMS.

Nous avons pensé que Netlify CMS pourrait être avantageux pour les raisons suivantes :

• Il est conçu pour être utilisé avec des générateurs de site statique, ce qui nous permet de conserver les avantages en terme de vitesse, de sécurité et d’évolutivité qui nous ont attirés vers les SSG
• Il est SSG agnostique, et fonctionne donc avec notre site Jekyll existant mais ne nous empêcherait pas de changer d’avis (salut GatsbyJS !)
• Il n’y a pas de base de données car les modifications de contenu sont enregistrées via des commits Git — ce qui ravi les gens de la sécurité informatique !
• Il fournit une expérience d’édition simple et fonctionnelle
• Il est open-source, il n’y a donc pas de dépendance à un fournisseur, et nous permet de reverser les fonctionnalités importantes à la communauté

Suite à l’adhésion des parties prenantes, nous avons décidé de nous orienter vers cette solution. Nous allons parler des décisions que nous avons dû prendre et vous montrer comment intégrer Netlify CMS avec Jekyll sur votre propre site.

Devez-vous passer de GitHub Pages à Netlify ?

Ça a été le premier choix à faire. Changer d’hébergement nous a semblé augmenter le temps et la complexité du projet, aussi notre décision à donc été « non ». Utiliser Netlify CMS avec votre hébergeur actuel est un choix parfaitement valable.

Alors pourquoi avons-nous changé d’avis et opté pour Netlify ? La réponse tient dans deux fonctionnalités très convaincantes : Git Gateway et le déploiement de branches.

Git Gateway fonctionne comme un intermédiaire entre le CMS et votre dépôt Git. Concrètement cela signifie que, par exemple, vos utilisateurs peuvent se connecter à l’administration du CMS en utilisant leur compte Google au lieu de leur demander d’avoir un compte GitHub. Ensuite Netlify effectue les commits via un compte GitHub autorisé à accéder au dépôt via OAuth. Bien que Git Gateway soit également un logiciel open-source, il était clair que l’héberger nous-même allait ajouter une complexité considérable.

Le déploiement de branches vous permet d’avoir plusieurs versions de votre site en même temps. À titre de comparaison, GitHub Pages est très limité puisqu’il ne permet de déployer qu’une seule branche (généralement “master“ ou “gh-pages“). Au premier abord ça peut sembler sans intérêt, mais ça offre une possibilité très intéressante que nous allons détailler dans un instant.

Migrer de GitHub Pages à Netlify

En général, publier votre site depuis Netlify est aussi simple que de créer un compte Netlify, connectez vous à votre fournisseur (GitHub, GitLab ou Bitbucket) et sélectionnez un dépôt. Dès que vous définissez la commande de build, Netlify peut commencer à déployer votre site. Les tâches telles que configurer le SSL sont expliquées dans la documentation Netlify, nous ne les détaillerons donc pas ici.

Si vous utilisez les gems intégrées à Jekyll et le processus de build proposé par GitHub, vous aurez besoin de quelques outils complémentaires pour que ça fonctionne. Vous aurez besoin d’un Gemfile pour vos dépendances, et c’est aussi une bonne idée d’intégrer la commande de build au code source :

Gemfile

source "https://rubygems.org"
gem 'github-pages'

netlify.toml

[build]
publish = "_site/"
command = "jekyll build"

Une fois que tout vous semble bon et que le déploiement Netlify se déroule correctement, vous pouvez demander à gérer votre nom de domaine via Netlify et migrer vos DNS vers les serveurs de nom de Netlify. Une fois vos DNS complètement coupés, vous pouvez désactiver le site GitHub Pages en toute sécurité depuis votre dépôt.

Ajouter Netlify CMS à un site existant

Netlify CMS se compose d’une application web monopage (NDT : en anglais single-page application ou SPA) construite avec React qui réside dans un dossier admin de votre site. Pour Jekyll, il doit être placé à la racine du site. Il contiendra deux fichiers :

admin
├ index.html
└ config.yml

La documentation de Netlify CMS explique ça très bien :

Le premier fichier, admin/index.html, est le point d’entrée à l’admin de Netlify CMS. Cela signifie que les utilisateurs y accèdent via votresite.com/admin/. Du côté du code, c’est une page HTML qui charge le fichier Javascript de Netlify CMS. Dans cet exemple, nous chargeons le fichier depuis un CDN public :

admin/index.html

<!doctype html>
<html>
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Content Manager</title>
  <script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>
</head>
<body>
  <!-- Include the script that builds the page and powers Netlify CMS -->
  <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script>
</body>
</html>

Le second fichier, admin/config.yml, est le coeur de l’installation de Netlify CMS, et il est un peu plus complexe. La section Configuration rentre dans les détails.

Pour commencer, voici à quoi peut ressembler le fichier de configuration :

admin/config.yml

backend:
  name: git-gateway
  branch: master
  identity_url: "https://yoursite.com/.netlify/identity"
  gateway_url: "https://yoursite.com/.netlify/git"
  squash_merges: true

publish_mode: editorial_workflow
media_folder: "assets/img/uploads"

site_url: https://yoursite.com
logo_url: https://yoursite.com/assets/img/logo.svg

collections:

La section backend couvre la configuration de base tel que le choix de la branche à modifier et la connexion Git Gateway dont nous avons parlé plus haut. La propriété publish_mode est paramétrée de manière à ce que notre flux de travail utilise le mode editorial. En bref cela signifie que nous avons la possibilité de sauvegarder les brouillons sous la forme de Pull Requests Git avant de décider de les publier. Combiné à la fonctionnalité de déploiement de branches de Netlify, cela va nous permettre d’avoir un aperçu immédiat du contenu non publié !

Remarque : depuis mai 2019, le flux de travail éditorial n’est pris en charge que lorsque vous utilisez GitHub.

Maintenant il ne nous reste plus qu’à déposer le widget Netlify Identify sur le site principal. C’est nécessaire car après s’être connecté l’utilisateur est redirigé vers la page d’accueil du site. Nous devons rediriger les utilisateurs vers l’administration du CMS, en ajoutant le script suivant avant la fermeture de la balise body :

<script>
  if (window.netlifyIdentity) {
    window.netlifyIdentity.on("init", user => {
      if (!user) {
        window.netlifyIdentity.on("login", () => {
          document.location.href = "/admin/";
        });
      }
    });
  }
</script>

Une fois ceci mis en place, avec l’authentification adéquate et la Git Gateway configurée sur netlify.com, vous devriez être en mesure de vous connecter à l’administration de Netlify CMS de votre site via l’URL https://yourdomain.com/admin/.

Qu’est-ce que les Collections ?

Bien qu'à ce stade vous pouvez vous connecter, vous ne pouvez pas encore faire grand chose ! Aucune structure de données n’est configurée pour les champs du CMS dont vous aurez besoin pour éditer votre site. Vous avez peut-être remarqué le champ vide collections dans le fichier de configuration, et c’est là que la magie opère. Tous les champs des données que vous souhaitez enregistrer doivent appartenir à une collection.

Il existe deux types de collections, le dossier de collections et le fichier de collections. Pour comprendre la différence, voyons ce que Netlify CMS fait réellement lorsque vous modifiez un contenu : les données doivent être stockées quelque part et nous savons qu’il utilise Git comme back-end. Cela signifie que les données que vous enregistrez doivent se retrouver dans un un fichier de votre projet. Ainsi, lorsque nous configurons une collection, nous donnons à Netlify CMS l’information de structure et la convention de nommage des fichiers que nous voulons créer. C’est ensuite à votre générateur de site statique de déterminer comment interpréter ces fichiers et injecter les données dans des templates. Dans ce billet, nous allons expliquer comment ça fonctionne avec Jekyll.

Sachant cela, pouvez-vous deviner pourquoi il existe deux types de collections ? Dans le cas de données de configuration, nous pouvons dire au CMS de mettre ces champs dans un fichier spécifique de notre projet. Dans le cas de contenus répétés tels que des billets de blog ou des pages construites à partir de composants modulaires, nous souhaitons configurer Netlify CMS de manière à ce qu’il puisse générer un certain nombre de formats de fichier différents — il supporte YAML, JSON, Markdown avec un front matter, et quelques autres.

Paramétrage d’un fichier de collection pour les données de configuration

Un fichier de collection est l’endroit idéal pour définir les champs des données pour les éléments qui sont valables sur l’ensemble du site, tels que la navigation globale, le pied de page et les valeurs par défaut. Jetons un oeil à un fichier de collection issu d’un cas réel :

admin/config.yml

collections:
  - label: "Options transverses"
    name: options
    editor:
      preview: false
    files:
      - label: "Menu de navigation"
        name: nav
        file: "_data/nav.yml"
        fields:
          - label: "Entrées de menu"
            label_singular: "Entrée de menu"
            name: topLevelItems
            widget: list
            fields:
              - {label: "Texte affiché", name: displayText, widget: string}
              - {label: URL, name: url, widget: string}
              - label: "Type d'objet"
                name: itemType
                widget: select
                options: ["Link", "Button"]

Cela définira une nouvelle collection qui apparaîtra à gauche de l’interface utilisateur de l’administration du CMS, et créera une page “Menu de navigation” au sein de cette collection. À l’intérieur se trouvent des champs qui définissent les entrées de navigation du site qui incluent chacune un nom, une URL, etc. Nous définissons le type de donnée et l’interface d’édition des champs à l'aide de widgets. Lorsqu'une modification est apportée, elle sera enregistrée dans le fichier _data/nav.yml de votre projet.

Voici un exemple de ce à quoi peut resembler un fichier de données :

_data/nav.yml

topLevelItems:
  - displayText: 'Une page'
    itemType: Link
    url: '/une-page/'
  - displayText: 'Lien externe'
    itemType: Link
    url: 'https://google.com'

Comment utiliser un fichier de collection dans Jekyll ?

Voyons comment exploiter ces données dans un template Jekyll. Voici un template Liquid qui utilise nos données de navigation :

<ul>
  {% for item in site.data.nav.topLevelItems %}
    <li>
      {% if item.itemType == 'Link' %}
        <a href="{{ item.url }}">{{ item.displayText }}</a>
      {% else %}
        ...
      {% endif %}
    </li>
  {% endfor %}
</ul>

Dans Jekyll, toutes les informations du dossier _data sont accessibles en utilisant la syntaxe site.data.{file}.{field}. Vous pouvez itérer et obtenir les champs que vous souhaitez.

Paramétrer un dossier de collection de pages

Une dossier de collection est utilisé chaque fois que nous avons besoin de générer un certain nombre de fichiers selon un template, mais sans savoir combien. Par exemple, si vous créez un blog, c’est ce dont vous aurez besoin pour vos billets. Dans cet exemple, nous allons utiliser une fonctionnalité intéressante de Jekyll afin de permettre aux contributeurs de créer les pages de notre site à la volée et selon la destination de leur choix.

Regardons la structure d’un dossier de collection provenant d’un fichier de configuration réel pour voir comment ça marche :

admin/config.yml

collections:
 - label: "Pages"
    label_singular: "Page"
    name: pages
    folder: "_pages"
    create: true
    slug: "{{slug}}"
    preview_path: "{{permalink}}"
    editor:
      preview: false
    fields:
      - {label: "Titre", name: title, widget: string}
      - {label: "Lien permanent", name: permalink, widget: string}
      - label: "Template"
        name: "layout"
        widget: "select"
        default: "blocks"
        options:
          - { label: "Défaut", value: "blocks" }
          - { label: "Page d'accueil", value: "home" }
      - {label: "Meta description", name: metaDescription, widget: text, required: false}
      - label: "Partage sur les réseaux sociaux"
        name: social
        widget: object
        required: false
        fields:
          - {label: "Image OpenGraph", name: ogImage, widget: image, required: false}
          - {label: "Image Twitter", name: twitterImage, widget: image, required: false}

Ceci définit une nouvelle collection appelée “Pages” qui contiendra de nombreux fichiers stockés dans le dossier /_pages/ de votre projet. Les fichiers seront nommés en fonction du modèle définit dans le champ slug, lequel est configuré pour prendre la valeur de la variable pas forcément très explicite {{slug}}. Ne vous inquiétez pas, dans ce cas, cela signifie simplement que nous utiliserons la valeur par défaut, à savoir le contenu du champ Titre. Vous pouvez configurer cela de différentes façons pour y inclure une date ou tout autre élément selon votre besoin, mais dans le cas de notre exemple c’est parfait.

Veuillez noter les champs permalink et preview_path. Nous utiliserons le champ permalink pour définir le chemin d’accès à notre page dans Jekyll, et le champ de preview permet à Netlify CMS de savoir comment pointer vers la bonne URL de prévisualisation (déploiement de branches :+1:).

Voici un exemple de ce à quoi peut ressembler le fichier de contenu d’une page :

_pages/home.md

---
Title: Accueil
permalink: /
layout: home
metaDescription: Dites nous de quoi il s'agit !
social: {}
---

Comment utiliser un dossier de collection dans Jekyll ?

Si vous lisiez avec attention, vous avez sans doute remarqué qu’une collection de fichiers génère des fichiers YAML, alors qu‘une collection de dossiers génère des fichiers Markdown avec un front matter. Vous pensez peut-être que c’est un peu étrange d’avoir un fichier Markdown sans contenu sous le front matter (séparé par trois tirets), mais soyez rassuré : c’est pour une bonne raison !

Nous travaillerons de concert avec la fonctionnalité de collections propre à Jekyll afin de coupler nos fichiers Markdown avec un template, lire les données du front matter et ensuite générer notre page. Cela nous permettra de faire des choses plus travaillées plus tard, comme utiliser le widget liste à types de variable pour créer un composant de page builder !

Avant de commencer, nous avons besoin de compléter le fichier de configuration de Jekyll :

_config.yml

collections:
  pages:
    output: true

Ceci indique à Jekyll qu’il doit générer une nouvelle page pour chaque fichier Markdown présent dans le dossier pages.

Mais comment Jekyll fait-il pour savoir quel template utiliser ? Dans le cas présent c’est champ layout défini dans Netlify CMS qui s’occupe de ça. Jekyll fait correspondre la valeur du champ dans le front matter directement avec le nom du fichier de template présent dans le dossier _layouts du projet.

Regardons un exemple de template :

_layouts/home.html

---
layout: default
---

<h1>{{ page.title }}</h1>

<section class="home">
  {{ content }}
</section>

Toutes les données provenant du front matter qui nous intéresse sont accessibles en utilisant la syntaxe Jekyll {collection}.{field}. Nous pouvons utiliser les templates parents et autres comme on veut.

Réaliser un page builder dans Jekyll

C’est un bon début, mais nous n’aurions pas besoin de tout ça dans notre dossier de collection si nous n’allions pas plus loin : créons un page builder flexible, basé sur des composants.

Pour commencer, nous devons définir nos composants dans le fichier de configuration de Netlify CMS :

_admin/config.yml

collections:
  - label: "Pages"
      ...
      - label: "Blocs de contenu"
        label_singular: "Bloc de contenu"
        name: blocks
        widget: list
        types:
          - label: "Mise en avant"
            name: hero
            widget: object
            fields:
              - {label: "En-tête", name: heading, widget: string}
              - {label: "Contenu", name: content, widget: markdown, buttons: ["bold", "italic", "link"], required: false}
          - label: "Bloc de texte riche"
            name: textBlock
            widget: object
            fields:
              - {label: "En-tête", name: heading, widget: string, required: false}
              - {label: "Contenu", name: content, widget: markdown}
          ...

Ici nous avons étendu notre collection de pages afin d’y inclure un widget de liste à type de variable qui contient différents types d’objets que l’éditeur de contenu pourra ajouter dynamiquement et réorganiser depuis l’administration du CMS.

Créons maintenant un nouveau template pour le rendu de nos widgets :

_layouts/blocks.html

---
layout: default
---

{% for block in page.blocks %}
  {% include blocks/{{ block.type }}.html block=block %}
{% endfor %}

Ici nous itérons sur chacun des composants de la page et incluons un autre fichier de template qui lui s’occupe du rendu. Voici à quoi pourrait ressembler un template de composant :

_includes/blocks/hero.html

<header class="page-hero">
  <h1>{{ block.heading }}</h1>
  {% if block.content and block.content != '' %}
    <div class="max-width--330">
      {{ block.content | markdownify }}
    </div>
  {% endif %}
</header>

Parce que nous avons transmis notre variable block, nous avons tout ce dont nous en avons besoin. Vous remarquez également que nous avons veillé à transformer notre Markdown en HTML avec markdownify car ce n’est pas fait automatiquement.

Notre retour d'expérience avec Netlify + Netlify CMS

Grâce à ces techniques, nos ingénieurs ont pu intégrer Netlify CMS à notre site Jekyll existant pour Monetery et mettre en oeuvre un CMS opérationnel en l’espace de quelques jours (trois pour être exact). Les contributeurs de contenu ont été en mesure de s’intégrer rapidement et de commencer à publier des modifications et de nouvelles pages peu de temps après le lancement. Pendant ce temps, nous avons également intégré un nouvel ingénieur qui a pu commencer à contribuer de manière significative dès son deuxième jour de travail !

Cela dit, ce n’est jamais terminé. Nous apprenons constamment de nos expériences et nous essayons de nous améliorer. Jetons un oeil critique sur les avantages et les inconvénients quant à l’utilisation de Netlify + Netlify CMS :

Pour

• Héberger son site avec Netlify est un jeu d’enfant et nous n’avons rencontré aucun problème avec le site lui-même
• Netlify CMS à été très facile à installer sur un projet Jekyll existant et il est intuitif pour les nouveaux ingénieurs
• Il est facile et très pratique de créer une copie de l’ensemble de votre projet, y compris le contenu, et de l’exécuter localement à l’aide de Docker
• L’interface de Netlify CMS est simple et facile à prendre en main pour les contributeurs de contenu
• Le déploiement et l‘aperçu par branche est extraordinaire
• L‘offre gratuite de Netlify vous donnent la liberté d’évaluer le service avant de vous engager
• Il existe une communauté active et très utile pour Netlify CMS sur Gitter
• Netlify CMS est open-source et les contributions sont bienvenues

Contre

• Nos contributeurs de contenu apprécient le flux de travail éditorial, mais n’aiment pas les nombreuses étapes nécessaires pour enregistrer et publier
• L’enregistrement et la publication sont relativement lents, parfois jusqu’à plusieurs secondes
• Nous rencontrons des erreurs occasionnelles — mais frustrantes — lors de l’utilisation de l’administration du CMS
• Certains widgets ou fonctionnalités que vous pourriez rechercher, tels que l‘affichage conditionnel des champs de l’interface utilisateur de l’administration, n’ont pas encore été implémentés
• L’interface utilisateur du CMS ne permet pas de sauvegarder le contenu sur votre ordinateur lors du développement en local, il sera toujours nécessaire de commiter sur votre dépôt Git, alors soyez prudent
• Il est préférable d’utiliser Netlify comme hébergeur plutôt qu’un autre fournisseur si vous souhaitez utiliser des fonctionnalités telles que le déploiement de branches et un Git Gateway déjà hébergé — Cela peut ajouter des coûts supplémentaires à votre projet

Communauté et contribution

Les échanges avec la communauté Netlify CMS ont été merveilleux, nous vous encourageons donc à essayer cette technologie. Dwolla croit également qu’il faut associer les mots et les actes, aussi nous sommes résolus à reverser à la communauté open-source. Nous sommes heureux d’annoncer que notre première Pull Request est déjà en ligne !

Découvrez le code sur GitHub : https://github.com/netlify/netlify-cms

Dans cet article, nous allons voir certains cas d'usage d'une appli Web complexe, comme le fait d'aller requêter des données tierces dynamiques ou de s'authentifier, et nous allons vous révéler pourquoi Gatsby est un très bon choix pour construire des applis web.

Nous allons prendre comme exemple une appli Web classique — Gmail — que nous avons reconstruit en Gatsby pour démontrer comment Gatbsy peut servir à construire des applications modernes et plaisantes.

Pour commencer, nous pouvons nous demander ce qu'est, au juste, une appli Web.

Note : Si vous ne l'avez pas déjà fait, nous vous suggérons de regarder la vidéo « Beyond Static: Building Dynamic Apps with Gatsby » de laquelle la plupart des idées de ce billet sont reprises.

Qu'est-ce qu'une appli Web ?

J'ai par le passé tenté de définir ce qu'est une appli Web traditionnelle, ce qui s'est avéré étonnamment difficile. Pour résumer, je pense qu'il y a plusieurs fonctionnalités clés qui tendent à créer une expérience semblable à celle d'une app :

• requêtage de données dynamiques;
• authentification des utilisateurs, et le fait d'avoir des routes authentifiées côté client;
• des interactions côté client portées par JavaScript.

Bien entendu, une appli Web n'est pas une simple checklist pour laquelle il faudrait avoir coché chacun des points précédents afin d'obtenir une expérience semblable à celle d'une app. Je pense plutôt qu'il est plus simple d’observer un exemple d'une appli Web — qui aurait mis en place plusieurs de ces fonctionnalités — afin de pouvoir se créer un modèle mental du type d'applis Web que Gatsby peut construire.

Je pense plus particulièrement à deux exemples clé, qui sont pour moi les plus représentatifs de mon modèle mental d'un appli web… Gmail et Twitter.

Gmail

Gmail peut-être vu, avec le recul, comme une “preuve de concept” qui a démontré deux choses très importantes :

• le JavaScript côté client peut offrir une expérience proche de celles des apps, et
• une application JavaScript (qui s'exécute dans votre navigateur) soutient favorablement la comparaison avec une application native, que ce soit sur desktop ou mobile.

Il ne faut pas sous-estimer l'impact de ces bénéfices. Gmail a prouvé qu'une expérience de type native est non seulement possible pour les utilisateurs grâce au JavaScript côté client, mais aussi que cette solution peut être préférable et plus pratique que la solution native. Nous reviendrons sur l'exemple de ce bon vieux Gmail en temps voulu.

Twitter (Progressive Web Application)

Twitter est un autre très bon exemple de mon modèle mental de ce qu'est (et ce que peut être !) une appli Web parce que :

• ça illustre une partie de la richesse d'une expérience Web moderne, et
• ça repose sur des pratiques avancées et des optimisations poussées de performances pour proposer une expérience rapide et plaisante.

En particulier, les fonctionnalités suivantes sont des composantes clés pour un nouveau genre d'applications :

• le cache agressif des données et une navigation rapide grâce aux Service Workers,
• la mise en place du pattern PRPL (Push, Render, Pre-cache, Lazy-Loading),
• l'illustration du pattern Coquille Applicative (App Shell) pour rendre encore plus rapide les visites subséquentes et afficher une page la plus complète possible, le plus rapidement possible.

Ces concepts modernes, lorsqu'ils sont pris ensemble, sont un atout majeur dans l'approche qu'a suivi Twitter pour proposer une expérience proche d'une app. Les ingénieur·e·s de Twitter ont réussi à isoler le cœur de l'expérience Twitter et à le rendre disponible à travers une appli Web moderne ultra-rapide grâce à l'application de techniques d'ingénierie éprouvées; et certains utilisateurs la préfèrent même à l'expérience native. Pour en apprendre davantage sur ces techniques, vous pouvez parcourir cette excellente étude de cas par Addy Osmani de Google.

Ces deux applis Web serviront de d'exemples à garder à l'esprit quand nous allons aborder l'utilisation de Gatsby pour les applis Web.

Gatsby est taillé pour les applis Web

Et si je vous disais… que construire un site avec Gatsby autorisait toutes ces fonctionnalités, traditionnellement réservées à des applis Web, parce qu'un “site statique” Gatsby est en fait une appli Web ?

Aucune application Gatsby n'est dans les faits purement statique. Tout ce qui peut être rendu à l'aide de HTML statique dès le chargement de la page l'est. Ensuite, le JavaScript côté client (via React !) prend le contrôle en tant que socle technique pour les fonctionnalités dynamiques des applis Web. Un petit tour d'horizon du système de build de Gatsby permet d’expliquer clairement le concept. Gatsby :

1. injecte la donnée dans les pages (depuis GraphQL ou même sans utiliser GraphQL);
2. utilise la fonction d'API de rendu côté serveur ReactDOMServer.renderToString pour transformer les composants React en fichiers HTML;
3. injecte le runtime et des additions (comme un routeur !) pour permettre de construire des features d’applis Web.

• Gatsby offre une expérience similaire à create-react-app une fois que le runtime est fonctionnel

Pour illustrer ce concept, commençons avec une exemple classique… Nous avons besoin de requêter des points de donnée à l'execution plutôt qu'au moment du build.

// src/pages/messages.js

import React from "react";

import Layout from "../components/layout";

class Messages extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      messages: [],
    };
  }

  // note: this is a simplified example without error handling, authentication, etc.
  async componentDidMount() {
    const messages = await fetch(
      `/api/some-url-to-get-messages`
    ).then((response) => response.json());

    this.setState({
      messages,
    });
  }

  render() {
    const { messages } = this.state;
    return (
      <Layout>
        {messages.length === 0 ? (
          <p>Loading messages&hellip;</p>
        ) : (
          <ul>
            {messages.map((message) => (
              <li key={message.id}>{message.text}</li>
            ))}
          </ul>
        )}
      </Layout>
    );
  }
}

export default Messages;

Tout ce que nous avons fait ci-dessus est d'implémenter la méthode du cycle de vie React componentDidMount, qui va déclencher une requête vers une API REST pour requêter des données (des messages !) depuis une API distante. Au runtime notre application requête donc des données dynamiquement. Ceci illustre l'efficacité du runtime Gatsby + React, ainsi que la manière dont une application Gatsby est en réalité proche d'un create-react-app déjà hydraté avec la donnée. Les méthodes du lifecycle React sont pleinement supportées et permettent donc d'implémenter n'importe quel type d'interaction nécessaire, comme, dans notre exemple, une requête sur une API distante.

Considérons l'animation ci-dessous, qui représente l'expérience utilisateur. En réalité, nous avons généré statiquement les blocs non-dynamiques (le header, la sidebar…) et nous avons requêté dynamiquement le reste des données !

Cependant, notre exemple peut paraître simpliste — ou en tous cas assez éloigné d'une vraie appli Web. Que se passerait-il si l'API REST nécessitait une authentification ? Et si nous souhaitions des routes gérées côté client, par exemple pour avoir un lien direct vers un message spécifique ? Tout est possible ! Est-ce qu'on peut profiter de GraphQL lors du build et du runtime ? Bien sûr !

L'idée principale que je tiens à clarifier dans cet article est que les fonctionnalités typiques d'une appli Web sont non seulement possibles avec Gatsby, mais aussi et surtout simples et intuitives à implémenter grâce au runtime dynamique disponible dans chaque application Gatsby. Ce n'est que du React.

Gatsby sert à construire des applis Web dynamiques, de la même manière que Gatsby sert à construire des sites statiques. C'est maintenant acté. Gatsby peut être utilisé pour beaucoup de cas d'utilisations typiques d'une appli Web, que ce soit l'authentification, les routes côté client, le requêtage dynamique de données et bien plus.

Pourquoi utiliser Gatsby pour une appli Web ?

Des optimisations de performance, par défaut

Si l'on regarde les avantages que procure Gatsby, à minima :

• le rendu statique de composants React et des données associées en HTML statique;
• l'optimisation des données, des images, etc. pour obtenir des sites ultra-rapides;
• la présence de patterns liés à la performance et des bonnes pratiques comme le PRPL, la séparation de code par route, etc.

Chacun de ces avantages mériteraient que l'on s'y attarde un peu plus, mais nous nous contenterons de dire que ce sont d' excellentes fonctionnalités que vous souhaitez avoir dans vos sites statiques, mais aussi dans vos applis web.

Ces optimisations de performances ne sont pas à activer — elles sont présentes par défaut. Quand de nouvelles techniques et de nouvelles optimisations apparaîtrons et gagneront en popularités, nous pourrons les y ajouter tout comme nous avons ajouté celles-ci. Ces optimisations peuvent alors être poussées à vos utilisateurs en mettant à jour votre version de Gatsby, un peu comme les améliorations d'outillage peuvent être obtenues en mettant à jour create-react-app.

Les plugins et l'écosystème Gatsby

Un des avantages principaux de Gatsby est son architecture modulaire. Vous avez besoin d'un plugin pour récupérer des données de Wordpress ? Bien sûr, cela semble raisonnable. Vous avez besoin de transformer des données YAML en objets JavaScript plus simples à manipuler ? Allez, pourquoi pas ! Une envie de se raccorder à une API GraphQL distante et d'injecter ses données au moment du build ? Ah, je vois qu'on a des goûts de luxe. Vous souhaitez afficher des images optimisées, adaptées à toutes les tailles et qui affichent un effet de flou lors du chargement ? C'est parti !

Prenons le temps de regarder plus en détail ces fonctionnalités proposées par un de nos composants, gatsby-image.

gatsby-image

gatsby-image est certainement un de mes composants préférés parmi ceux que Gatsby propose et maintient. Il offre un excellent rendu d'images, et amène des optimisations rendues possibles par des plugins comme gatsby-plugin-sharp. Ces deux techniques, couplée avec l'API GraphQL disponible dans n'importe quelle application Gatsby, simplifie grandement l'expérience de développement lorsque l'on souhaite afficher des images optimisées. Parmi les fonctionnalités disponibles, citons :

• l'adaptabilité de la taille des images pour en afficher une optimisée à celle de votre interface — ce qui permet de reléguer la fameuse image de 5Mo en tête de page au fin fond des oubliettes;
• la génération de multiples images, adaptées aux appareils mobiles, en utilisant srcset pour ne télécharger que celle dont votre utilisateur a besoin;
• le chargement asynchrone des images avec une technique de flou dégressif — ou même de SVG tracé.

gatsby-image est incroyable. Si vous n'avez pas encore pu tester ses fonctionnalités dans vos sites, je vous recommande chaudement de vous y mettre ! Vous pouvez vous inspirer de notre exemple, fraîchement redesigné, “Using Gatsby Image” (en anglais) pour en apprendre plus et le voir dans un cas d'utilisation réelle. En somme, utilisez gatsby-image et vos utilisateurs vous remercieront.

Le potentiel de ces composants et de ces plugins est immense. De la même manière que les composants réutilisables ont été incroyablement importants dans le succès de l'écosystème React, les plugins ont une valeur immense pour les applications Gatsby. Pourquoi perdre du temps de développement à réimplémenter ces composants vous-même lorsque vous pouvez réutiliser et profiter du potentiel de l'écosystème Open Source ? Lorsque vous utilisez ces plugins et ces composants, vous pouvez passer davantage de temps à construire votre propre application Gatsby. Jetez un oeil à notre librairie de plugins si ce n'est pas déjà fait !

Maintenant, la suite : nous allons comparer l'expérience utilisateur lorsque nous requêtons des données derrière une authentification entre une application Gatsby, et une application rendu côté serveur.

La Coquille Applicative

En ajoutant juste le plugin gatsby-plugin-offline, nous transformons notre appli Web en une Progressive Web App complète, qui fonctionne hors ligne, et qui crée une “coquille applicative” en enregistrant un Service Worker. Une coquille applicative est en réalité une collection de composants de votre application (par exemple, l'en tête, le pied de page, la navigation latérale, etc…) qui sont disponibles immédiatement depuis le Service Worker pendant que le contenu dynamique est récupéré en tâche de fond. Cela permet de créer des expériences utilisateur immersives, car l'application apparaît instantanément à l'écran et le contenu dynamique se remplit progressivement.

Si nous regardons de plus près cette approche, elle se décompose comme suit:

• on rend le plus de contenu possible instantanément (la coquille applicative);
• on fait des requêtes asynchrones pour aller chercher des données supplémentaires, par exemple du contenu venant d'une API (plus particulièrement d'une API authentifiée).

Comparons cette méthode avec celle du rendu côté serveur. Pour cet exemple, nous allons considérer que nous devons nous connecter à une API authentifiée. L'appel API que l'on déclenche sert à peupler le contenu de la page avant qu'elle soit envoyée (en HTML) à l'utilisateur. Nous devons donc attendre que l'appel API soit terminé avant de commencer à charger la page, plutôt que de proposer la coquille applicative et d'aller chercher les données dans un second temps, en tâche de fond.

Pour illustrer cet exemple, nous pouvons nous appuyer sur l'animation suivante. Sur la gauche, on peut voir une application qui utilise un Service Worker et une coquille applicative — une application Gatsby par exemple. Sur la droite, c'est une application rendue côté serveur, qui doit donc attendre que l'appel API soit terminé avant de pouvoir proposer la page complète, d'un coup.

Nous voyons donc clairement les avantages de cette approche. Lorsque nous chargeons une coquille applicative, nous donnons à nos utilisateurs l'impression que la page se charge plus rapidement, bien que si nous comparons les deux approches, elles affichent toutes deux toute la donnée au même moment. Nous avons donc le meilleur des deux mondes… On donne la perception que le site est très rapide, tout en sachant qu'il est très rapide grâce aux optimisations que l'on obtient avec Gatsby, par défaut.

Afin de revenir sur tous ces concepts, j'ai préparé une application de démonstration qui ressemble à notre vieil ami Gmail. Cette démonstration montre que les applis Web complexes sont non seulement possibles avec Gatsby, mais aussi que Gatsby est un excellent choix lorsque l'on doit en construire une.

Et voici… Gatsby Mail ! (Qui ne sert qu'à des fins de démonstration !)

Gatsby Mail reprend certains des concepts et des thèmes que j'ai abordés. Plus particulièrement :

1. Gmail, Twitter et les autres sont des exemples parlants d'applis Web complexes qui proposent des expériences riches.
2. Gatsby fournit des composants, des plugins, etc… qui permettent de développer ces expériences, servez-vous en !
3. Gatsby est un excellent choix lorsqu'il s'agit de construire de telles applis Web.

De plus, Gatsby Mail fait la démonstration de fonctionnalités spécifiques aux applis Web, comme :

• du rendu statique couplé à des requêtes dynamiques grâce au runtime côté client;
• de l'authentification et des routes gérées côté client;
• des routes non-authentifiées, comme une page d'accueil (qui utilise l'API Context de React);
• l'utilisation de GraphQL au moment du build et au runtime, en s'appuyant sur une API GraphQL distante et sur apollo-boost;
• le chargement d'une coquille applicative grâce à gatsby-plugin-offline (voyez par vous-même la démo en “3G rapide” ci-dessous !).

et même des thèmes clairs/sombres, parce que pourquoi pas ! Vous pouvez voir ce que ce tout cela donne, et comment cela amène à une très bonne expérience utilisateur dans l'exemple ci-dessous, pour lequel j'ai simulé une connexion 3G rapide. La coquille applicative (l'en-tête, le pied de page, etc…) s'affiche instantanément pendant que l'on va chercher le contenu dynamique (depuis notre API distante GraphQL) en tâche de fond.

Vous pouvez aller jeter un oeil au repository GitHub pour en savoir plus sur comment elle a été développée, et vous approprier quelques unes de ces techniques pour la prochaine appli Web que vous développerez en Gatsby ;)

On a hâte de voir ce que vous allez construire.

Pedro Duarte a lancé https://jamstack.wtf un mini-site afin de donner une vue d'ensemble de la Jamstack. Nous vous proposons ici sa traduction en français afin de permettre à toujours plus de développeurs d'adopter cette façon de travailler.

La Jamstack révolutionne notre manière de travailler en proposant une expérience de développement plus simple, de meilleures performances, des coûts bien moins élevés et une grande scalabilité.

Vous vous demandez peut-être ; oui OK, mais comment ? pourquoi ? c'est quoi au juste ?

C'est la raison d'être de cette page https://jamstack.wtf.

Le but de ce guide est de présenter de manière claire le concept de la Jamstack et d'inciter d'autres développeurs à adopter cette approche.

Le contenu ci-dessous est tiré du site ci-dessus 👆

Asseyez-vous, mettez-vous à l'aise et appréciez ✌️

C'est quoi la Jamstack ?

Signification

JavaScript
Les fonctionnalités dynamiques sont gérées par JavaScript. Vous êtes libres d'utiliser la bibliothèque ou le framework que vous voulez.

APIs
Les opérations côté serveur sont abstraites sous forme d'APIs réutilisables, accessibles en HTTPS à l'aide de JavaScript. Ces opérations peuvent être déléguées à des services tiers ou bien à vos propres fonctions.

Markup
Les sites web sont servis sous forme de fichiers HTML statiques. Ces fichiers peuvent être générés à partir de fichiers source, comme du Markdown, à l'aide d'un générateur de site statique.

Bénéfices

Les principaux bénéfices apportés par la Jamstack sont :

Une performance accrue
Servir du code généré et des assets à partir d'un CDN

Une meilleure sécurité
Plus besoin de se soucier des vulnérabilités du serveur ou de la base de données

Un coût bien moindre
L'hébergement de fichiers statiques est moins cher voire gratuit

Une meilleure expérience de développement
Les développeurs front end peuvent se focaliser sur la partie client, sans être dépendants d'une architecture monolithique. Cela se traduit en général par un développement plus rapide et plus ciblé.

Redimensionnement à la volée
Si votre site devient viral ou est soumis à un pic d'activité, le CDN compensera sans problèmes.

Bonnes pratiques

Les astuces suivantes vous aideront à tirer le meilleur parti de la stack.

Réseau de distribution de contenu (CDN)
Puisque tous les fichiers et les assets sont générés en amont, ils peuvent être servis sur un CDN. Cela procure une meilleure performance et un redimensionnement à la volée.

En savoir plus

Déploiement atomique
Chaque déploiement est une photographie complète du site. Vous disposez ainsi d'une version consistante du site à l'échelle mondiale.

En savoir plus

Invalidation du cache
Une fois votre site généré poussé en ligne, le CDN va invalider son cache. Cela signifie que la nouvelle version est instantanément disponible partout.

En savoir plus

Tout est versionné
Votre code vit dans un système de gestion de versions tel que Git. Les principaux avantages sont : l'historique des changements de chaque fichier et de chaque collaborateur ainsi que la traçabilité.

En savoir plus

Générations automatiques
Votre serveur est notifié lorsqu'une nouvelle génération est requise, typiquement à l'aide de webhooks. Le serveur génère le projet, met à jour les CDNs et le site est en ligne.

En savoir plus

Chaîne de publication

Voici à quoi ressemblerait la chaîne de publication Jamstack idéale.

Historique

2015
Les générateurs statiques sont de plus en plus en vogue, grâce à des générateurs populaires comme Jekyll.

2016
Quelques développeurs pensent que les sites statiques n'ont pas à être forcément statiques, le terme "Jamstack" fait son apparition.

2017
La révolution du web moderne commence à prioriser la performance, le redimensionnement à la volée et l'expérience de développement. Le terme Jamstack est adopté par un groupe de développeurs plus important et les premières entreprises commencent à annoncer des projets basés sur la Jamstack.

2018
Des outils comme Netlify, Gatsby et Contentful contribuent à promouvoir le terme et la communauté grandit vite. C'est aussi l'année de la première conférence Jamstack.

Source : Snipcart

Bien démarrer

C'est à vous de décider comment générer vos fichiers HTML. Les trois approches les plus communes sont :

Développement

À la main
Une méthode simple et efficace d'écrire du HTML, c'est idéal pour les pages super simples.

Générateurs de site statique
La plupart des sites Jamstack sont propulsés par un générateur de site statique. Vous êtes libres de choisir votre GSS.

• Gatsby
• Next.js
• Hugo

Voir davantage de générateurs

Framework frontend
La plupart des frameworks ne génèrent pas de fichiers HTML statiques par défaut, toutefois c'est possible si vous connaissez bien vos outils, cela demande plus d'expérience et de maintenance.

• React
• Vue.js
• Preact

Déploiement

Vous devez héberger le résultat de la compilation de votre site. Il existe de fantastiques services qui font cela gratuitement et simplement.

• Netlify
• Vercel
• Github Pages

Voir plus de services de déploiement

Parties dynamiques

Les sites Jamstack n'ont pas à être entièrement statiques. Il existe des services formidables pour vous aider à insérer des parties dynamiques dans votre projet.

Fonctions personnalisées
Vous pouvez également abstraire vos propres fonctions pour en faire des APIs réutilisables. Pour cela vous pouvez utiliser les fonctions AWS lambda ou les fonctions Netlify

Commentaires
Beaucoup de sites Jamstack intègrent des sections pour les commentaires, principalement sur des blogs.

Formulaires
Un excellent moyen d'interagir avec votre audience.

E-Commerce
Mettre en place une boutique en ligne sur un site Jamstack n'a jamais été aussi simple.

Recherche
Reposez-vous sur des services tiers pour intégrer des fonctionnalités de recherche.

Voir plus de services pour les sites statiques

CMS

Les sites Jamstack peuvent aussi être gérés via un système de gestion de contenu, plus précisément avec des CMS headless. Chaque changement effectué dans le CMS va entraîner une nouvelle génération du site, qui sera ensuite déployé sous forme de fichiers statiques.

• Contentful
• Forestry
• Ghost
• Headless WordPress
• Netlify CMS
• Strapi

Voir plus de services de gestion de contenu

Ressources

Voici une sélection de ressources sur la Jamstack qui comporte des matériaux d'apprentissage ainsi que des listes de services.

Services

• Une liste de services pour les sites web statiques
• Une liste de gestionnaires de contenu pour les sites Jamstack
• Une liste de générateurs de site statiques pour les sites Jamstack
• Un annuaire de sélection d'outils et de services

Articles

• Débuter avec la Jamstack? Tout ce que vous devez savoir pour bien démarrer
• Quel est le concept derrière la Jamstack
• Développement web moderne avec la Jamstack
• Smashing Magazine va dix fois plus vite
• Ghost avec la Jamstack
• Jamstack avec Gatsby, Netlify et Netlify CMS

Vidéos

• L'essor de la Jamstack, présentation de Mathias Biilmann
• La nouvelle stack Front-end, présentation de Mathias Biilmann
• Une sélection de vidéos par The New Dynamic
• Comment freeCodeCamp sert des millions d'apprenants en utilisant la Jamstack

Podcast

• Jamstack Radio

À propos

Cette page a été mise en place par @peduarte et présentée au meetup Jamstack de Londres — (voir les slides).

Nous allons soigneusement comparer les concepts d'Hugo et son vocabulaire avec ceux de WordPress, avec lesquels vous êtes déjà familier, afin que la courbe d'apprentissage soit un peu moins rude.

Nous allons partir de the_post(), the_loop et de la hiérarchie de modèle, pour mieux comprendre comment Hugo fonctionne !

De WordPress à Hugo

Vu que de nos jours WordPress fait tourner une bonne partie des sites web, nous pouvons supposer que beaucoup d'entre vous connaissent, voire sont experts de ce CMS très populaire. Moi aussi je faisais principalement du développement avec WordPress, avant de devenir complètement accro à Hugo.

Et j'ai mis du temps à me familiariser avec sa logique de fonctionnement. Quand j'ai découvert Hugo, je comparais son vocabulaire et ses concepts avec ceux de WordPress.

Je me suis rapidement aperçu que cette comparaison systématique était une mauvaise idée. Hugo possède son propre lexique et sa logique lui est propre et elle diffère beaucoup de celle de WordPress.

Mais j'ai réalisé qu'une étude parallèle plus attentive aurait pu m'aider à apprendre Hugo plus vite, et ainsi m'éviter pas mal d'erreurs coûteuses en chemin.

Donc si vous débutez avec Hugo, et que vous connaissez WordPress, ce qui va suivre ne pourra que vous être bénéfique.

Tout est page

Cette affirmation catégorique est essentielle pour mieux appréhender le fonctionnement d'Hugo, surtout en ce qui concerne la logique dans les gabarits.

Pour Hugo, tout fichier compilé et ajouté à votre dossier cible public est une page. En ce sens, un article, une page, une liste d'articles, une liste de catégories ou de tags : tout ça ce sont des pages.

On peut le voir ainsi : tout ce qui possède une URL, c'est une page !

Si pour Hugo, tout est page, il faut néanmoins faire quelques distinctions bien nettes. Parmi elles, il y a les les Types et les Kinds.

Type

Si dans WordPress, toute entrée est un post avec un type distinct. Un article c'est un post de type post, une page c'est post de type page et une recette, c'est un post de type personnalisé recipe (ou ce qui vous chante).

Dans Hugo, chaque entrée ou fichier de contenu est une page habituelle d'un type différent. Et comme il n'existe pas de type pré-établi, tout type est votre propre type personnalisé. Pour créer une page d'un certain type :

1. Vous ajoutez le type désiré dans le front matter
2. Ou plus généralement, vous laissez le premier niveau d'arborescence de contenu définir le type du fichier.

Donc pour créer une page de type recette, vous pouvez soit écrire le front matter suivant :

title: De délicieux cupcakes
type: recette
---

Ou vous reposer sur la structure de votre arborescence et laisser faire la magie :

content
  ├── post
  └── recette
      └── de-delicieux-cupcakes.md

Kind

Dans WordPress nous pouvons distinguer les layouts des templates. La page d'index qui affiche vos articles est construite d'après le fichier archive.php, cela s'appelle une archive. Et la page qui affiche le détail d'un article est elle construite à partir du fichier single.php, et s'appelle une single.

D'où les fonctions booléennes is_single(), is_archive()!

Dans Hugo, une fois encore, tout est page. Et donc pour déterminer ce que nous sommes supposés afficher, nous allons utiliser le mot Kind.

Voici différents exemples de valeurs pour kind :

• La page d'accueil de votre site web est la seule qui ait le kind homepage
• La page qui affiche vos recettes est une page avec le kind section
• La page qui affiche vos recettes catégorisées dans chocolat est une page avec le kind taxonomy
• La page qui regroupe toutes les catégories de vos recette (dont celles au chocolat) est une page avec le kind taxonomyTerm
• Enfin la page qui affiche une recette est la page la plus commune est de kind page.

Modèles et hiérarchie

Maintenant que nous avons vu Type et Kind, plongeons nous dans la logique des gabarits de page d'Hugo.

Tout ce qui se trouve dans le dossier layouts, que ce soit celui de votre projet ou celui de votre thème est soumis à la hiérarchie de modèles, qui est un concept propre à Hugo, également désigné dans la documentation comme l'ordre de consultation des modèles.

En plus des conventions sur les noms de fichier, Hugo se base aussi sur l'arborescence des dossiers pour savoir quel modèle appliquer.

De nombreux paramètres dont Kind, Type, le format en sortie, la langue, les termes de taxonomie, peuvent déterminer le modèle qu'il faudra utiliser pour une page donnée.

Les modèles de page personnalisés

C'est un des trucs plus anciens de WordPress.

Si vous voulez qu'un éditeur puisse choisir la mise en page d'une page en particulier, vous devez créer un fichier de modèle de page, le déposer dans le dossier de votre thème et inclure cette saleté de gribouillage :

<?php /* Template Name: Custom 🤮 */ ?>

Avec Hugo, vous pouvez assigner une mise en page personnalisée à n'importe quel fichier de contenu à l'aide d'un simple paramètre front matter : layout.

Ensuite nommez votre fichier d'après la valeur définie pour layout, placez-le dans le dossier layouts/_default/ et c'est bon !

---
title: À propos
layout: about
---
À propos de moi !

layouts
  └── _default
      └── about.html

Les fichiers includes

Une bonne pratique WordPress consiste à utiliser la fonction get_template_parts pour inclure un fichier de votre thème. Cela permet d'hériter des variables globales définies par WordPress ($post, $wp_query, etc.) mais c'est tout.

Dans Hugo, on parle de fichiers partiels. Ce sont des fichiers stockés dans layouts/partials qui seront chargés lors de l'appel à la fonction partial.

Le truc à savoir c'est que cette fonction prend comme paramètre un périmètre ou un contexte. Par défaut aucune information relative à votre page se sera transmise dans le fichier partiel.

On inclut un fichier partiel ainsi :

{{ partial "post-head" . }}

Le point ci-dessus .............☝️ correspond à la page courante.

Le contexte de la page courante comprend toutes les variables de page dont vous aurez besoin dans votre fichier partiel et dans tous vos modèles, nous allons y venir.

La boucle et les données

Les variables de Page

Dans WordPress, les données relatives à un article sont accessibles depuis les fichiers de gabarits de page via des fonctions comme the_permalink(), the_title(), the_content(), the_date() etc.

Hugo de son côté vous fourni un objet qui comprend des variables et des méthodes appelé le contexte de page et stocké dans le fameux point (.) mentionné plus tôt.

Dans Hugo, les équivalents aux expressions WordPress citées un peu plus haut sont .Permalink, .Title , .Content, .Date.

Vous vous rappelez du fichier partiel de toute à l'heure ? Et bien une fois le contexte de page précisé, vous avez accès à toutes les variables de la page dans ce fichier :

{{/* layouts/partials/post-head.html */}}
<div class="post-head">
  <h1><a href="{{ .Permalink }}">{{ .Title }}</a><h1>
  <time>{{ .Date }}</time>
</div>

Boucler avec range

Pouvoir parcourir des articles pour construire des pages archives ou un widget Derniers articles est essentiel pour un moteur de template.

Selon le gabarit de page que vous utilisez, WordPress vous donnera toujours accès à une liste d'articles à parcourir, même s'il n'y en a qu'un seul à afficher pour une page single.

Donc que ce soit pour le fichier des archives des posts de blog, des archives de la catégorie chocolat des recettes, ces éléments sont dans la boucle Loop, paginés.

Avec Hugo, dans les gabarits de listes, les pages concernées sont stockées dans une collection et sont accessibles via l'objet .Pages.

Cela fait que pour le modèle de liste de la section recettes, .Pages retournera la collection des pages correspondantes : recettes.

Pour une liste de taxonomie, .Pages contiendra la liste des pages qui utilisent cette taxonomie ainsi que les informations sur la taxonomie en elle-même stockés dans .Data, telles que .Data.Singular, .Data.Plural et bien plus.

Une chose à retenir, c'est que contrairement à WordPress, pour une page single, .Pages sera vide (arf) car toutes les informations de la page sont déjà disponibles dans le contexte de page ..

Comparaison des boucles

Voici notre boucle WordPress tant aimée :

// theme/archive.php
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
  <!-- post -->
  <h2>
    <a href="<?php the_permalink(); ?>"><?php the_title() ?></a>
  </h2>
  <h6><?php the_date(); ?></h6>
  <p>
    <?php the_excerpt(); ?>
  </p>
  <hr>
<?php endwhile; ?>
<?php else: ?>
<!-- aucun post trouvé -->
<?php endif; ?>

La même chose en beaucoup plus lisible et succinct avec Hugo, grâce à la transmission du contexte dans les fonctions :

//layouts/_default/list.html
{{ with .Pages }}
  {{ range . }}
    <h2>
      <a href="{{ .Permalink }}">{{ .Title }}</a>
    </h2>
    <h6>{{ .Date.Format "January, 02 2006" }}</h6>
    <p>
      {{ .Summary }}
    </p>
    <hr>
  {{ end }}
{{ else }}
<!-- aucun élément trouvé -->
{{ end }}

Qu'en-est-il des autres pages ?

Pour récupérer toutes les pages du site et ce depuis n'importe quel modèle de page, avec WordPress vous devrez écrire vous-même une requête.

Avec Hugo, nous avez simplement à appeler la collection .Site.pages. Comme tout est page, cette collection inclut aussi bien les pages normales, les pages de sections, les pages des taxonomies, la page d'accueil, etc. Pour ne sélectionner que les pages que WordPress appelle des posts, on utilisera .Site.RegularPages.

Voici un exemple de requête plus avancée avec WordPress, qui permet d'afficher un widget Les dernières recettes ordonnées en fonction d'un paramètre défini, et utilisable dans n'importe quel modèle de page :

<?php
$recents = new WP_Query(
  [
    'post_type'=>'recipe',
    'posts_per_page'=>5,
    'orderby'   => 'meta_value_num',
    'meta_key'  => 'rating',
  ]
);
if ( $recents->have_posts() ) : while ( $recents->have_posts() ) : $recents->the_post(); ?>
  <h2>
    <a href="<?php $recents->the_permalink(); ?>"><?php $recents->the_title() ?></a>
  </h2>
<!-- post -->
<?php endwhile; ?>
<?php else: ?>
<!-- aucune entrée trouvée -->
<?php endif; ?>
?>

Et voici son élégante variante avec Hugo :

{{ $recents := (where .Site.RegularPages "Type" "recipe").ByParam "rating" }}
{{ range first 5 $recents }}
  <h2>
    <a href="{{ .Permalink }}">{{ .Title }}</a>
  </h2>
{{ end }}

Les shortcodes

Dans WordPress, les shortcodes sont "des fonctions qui retournent quelque chose en sortie", ajoutées à l'aide de plusieurs add_shortcode dans votre fichier functions.php.

Hugo supporte également les shortcodes, ils sont crées en ajoutant des modèles particuliers dans layouts/shortcodes/. Le contenu du fichier est récupéré avec .Inner et ses paramètres avec .Get. Contrairement à WordPress, ses derniers n'ont pas forcément besoin d'être nommés.

• Si le paramètre est nommé 👉 .Get "title".
• Sinon on utilise sa position 👉 .Get 0.

Les shortcodes par l'exemple

Voici un exemple de shortcode WordPress tiré de la documentation[^1]. Il prendre en paramètre une classe, caption par défaut, et un contenu à insérer.

<?php
function caption_shortcode( $atts, $content = null ) {
  $a = shortcode_atts( array(
    'class' => 'caption',
  ), $atts );

  return '<span class="' . esc_attr($a['class']) . '">' . $content . '</span>';
}
add_shortcode( 'caption', 'caption_shortcode' );

Le shortcode s'utilise ensuite ainsi :

[caption class="headline"]My Caption[/caption]

Voyons maintenant la réponse en une ligne d'Hugo :

{{/* layouts/shortcodes/caption.html */}}
<span class="{{ default "caption" (.Get 0) }}">{{ .Inner }}</span>

On écrira dans son fichier Markdown :

{{%/* caption "headline" */%}}My Caption{{%/* /caption */%}}

Nous avons opté pour l'utilisation de la position… car il n'y a qu'un seul paramètre 🤷

Paramètres

Il y a de nombreuses pages de paramètres dans le tableau de bord de WordPress. Vous vous retrouvez souvent à naviguer entre le mode écriture et lecture de manière à pouvoir définir vos permaliens, votre titre de site, votre pagination, vos commentaires, etc.

Tout comme pour l'édition de contenu, la configuration d'Hugo se fait dans des fichiers ! Et pour faire plaisir à tout le monde, vous pouvez choisir le format qui vous convient le mieux :

• YAML
• TOML
• JSON

Si vous ne connaissez aucun d'entre eux (le dernier devrait vous dire quelques chose), vous pouvez vous pencher sur cet exemple de configuration que vous pouvez basculer entre les langues et vérifier leurs syntaxes.

Ces paramètres sont stockés dans un fichier config à la racine ou dans un répertoire dédié, qui vous permet de les grouper et d'écraser les variables d'environnement de façon plus intelligente.

Formats de sortie

Hein, c'est quoi ça ?

Ah oui c'est vrai, WordPress ne vous a pas présenté.

Imaginons que pour chaque page vous ayez un fichier HTML cette-page/index.html et c'est tout. Hugo vous permet aussi de faire en sorte que chaque page possède aussi une version au format JSON ainsi qu'au format AMP. Ces pages sont générées à côté de leur soeur au format HTML, respectivement cette-page/index.json et cette-page/index.amp.html.

Tout ce que vous avez à faire pour cela est de dire à Hugo d'ajouter les formats de sortie pour les Kinds desirés à l'aide du fichier de configuration évoqué juste avant, et d'ajouter les fichiers de templates correspondants.

Pour résumer :

# config.yaml
outputs:
  homepage:
    - HTML
    - JSON
  page:
    - HTML
    - AMP

layouts
  ├── _default
  │   └── about.html
  ├── index.html
  ├── index.json
  └── recipes
      └── single.amp.html

Et c'est tout ! Du moment que ces fichiers de gabarit contiennent le code qui va bien, votre page d'accueil sera disponible en HTML ainsi qu'en JSON, alors que vos recettes pourront être servies en HTML ou au format AMP !

Je vous conseille vivement d'aller éplicher la documentation sur les formats de sortie, grâce à eux vous pourrez ajouter une API à votre site où un fichier .ics pour vos évènements, ou qui sait ce dont vous aurez besoin sur votre prochain projet !

Traitement des assets

WordPress ne propose rien en ce sens, c'est à vous d'utiliser votre propre gestionnaire de tâches et ses paquets de traitement des assets.

Hugo propose lui sa propre suite d'outils de traitement des assets !

-- Heeein? -- Oui! Ça s'appelle les tuyaux d'Hugo et sans aucune dépendance node vous pouvez :

• Minifier 🗜️
• Paquetter vos fichiers 📦
• Compiler vos fichiers Sass/Scss 👓
• Ajouter une empreinte et un contrôle d'intégrité 🔑

Avec quelques dépendances vous pouvez :

• Exécuter PostCSS sur vos feuilles de style

Le tout avec la même élégance à laquelle vous devez commencer à vous habituer :

{{ $style := resources.Get "main.scss" | toCSS | minify | fingerprint }}
<link href="{{ $style.Permalink }}" rel="stylesheet">

Hugo s'assurera également que ces assets sont compilés et publiés uniquement si vous appelez leur .Permalink dans vos templates.

Traitement des images

Le traitement d'image par défaut de WordPress se fait uniquement lors de l'étape initiale de téléversement.

WordPress stocke ensuite les nouveaux formats de tailles d'images crées aux côtés du fichier d'origine. Lorsque vous appelez votre image, peu importe la fonction, vous devrez utiliser un paramètre pour récupérer la taille de la variante souhaitée.

Hugo quant à lui procède au traitement des images lorsque vous en avez besoin, ce qui signifie que vous obtiendrez cette variation pour cet entête d'article seulement si vous appelez les fonctions .Fit ou .Resize dans votre gabarit de page.

{{ $img := resources.Get "header.jpg" | .Resize "600x" }}
<img src="{{ $img.Permalink }}" alt="">

Je sais! Moi aussi je ne me lasse pas de ces instructions sur deux lignes !

Vous pouvez lancer des traitements d'images, soit à l'aide des tuyaux d'Hugo ou des ressources de page.

Thèmes et Plugins VS Composants de Thème

WordPress fait un usage immodérée des thèmes et des plugins, pour qu'en échange vous puissiez modeler l'apparence de vos sites et ajouter des fonctionnalités en codant le moins possible.

Pour les thèmes, WordPress ne vous donne que deux niveaux de personnalisation. Vous pouvez créer un thème parent, et y mettre toutes les choses génériques. Et ensuite créer un thème enfant, qui pourra, pour tous les homonymes de fichiers partagés avec son parent, prendre le pas sur ceux-ci.

Si vous avez besoin d'un niveau supplémentaire de personnalisation en plus de ces deux, comme un ensemble de shortcodes ou un format de sortie en AMP, il faudra avoir recous à des plugins.

Dans Hugo, on ne parle pas de plugins et des thèmes mais plutôt de composants. Vous pouvez en ajouter autant que vous voulez.

Fichiers de gabarit, JavaScript, Scss, images, fichiers de données, chaînes i18n (que nous couvrons plus bas), il est possible de presque tout écraser grâce aux homonymes de fichiers et vous pouvez définir l'ordre de précédence.

Voyez les composants comme des thèmes enfant illimités !

Certains composants peuvent être des thèmes complets qui contiennent un nombre important de fichiers. D'autres peuvent se contenter d'être une simple variation de votre thème principal, et ajouter leur propre ensemble de gabarits personnalisés par exemple. D'autres peuvent simplement ajouter quelques définitions de shortcodes, un nouvel ensemble de variables Sass, ou un format de sortie supplémentaire.

Le thème par l'exemple

Prenons pour exemple un projet fictif de clinique dentaire, où personne ne veut avoir à trop mettre les mains dans le code. Vous aurez besoin :

• Un thème principal adapté pour le secteur de la santé 👩‍⚕️
• Une extension du thème principal adaptée pour le domaine dentaire 🦷
• Une extension saisonnière du thème principal 🎄
• Une solution pour gérer des menus de navigation riches
• Un ensemble de shortcodes en relation avec le médical à l'intention de l'équipe de rédaction
• Un fichier JSON pour chaque page.

Avec WordPress il vous faudrait :

• Thèmes

  • Un thème santé
  • Un thème dentaire enfant du thème santé

• Plugins

  • Un plugin thème santé saisonnier
  • Un plugin Mega Menu
  • Un plugin Shordcodes médicaux
  • Un plugin API REST

Notez bien que si en plus de cela, vous souhaitez créer vos propres fichiers de gabarit pour prendre le pas sur les thèmes parent et enfant… et bien à ce que je sâche, ce n'est pas possible. 🤷‍♂️

Dans Hugo, vous n'avez qu'à ajouter ces différents répertoires dans votre dossier themes et y faire appel dans votre fichier de configuration principal.

theme:
  - health-theme
  - health-theme-dental-extension
  - health-theme-season-extension
  - mega-menu-component
  - medical-shortcodes-component
  - json-api-component

output:
  page:
    - HTML
    - JSON

L'exemple ci-dessus déclare les composants de thèmes à utiliser ainsi que leur ordre de précédence. Et comme vu auparavant, nous nous assurons que le format de sortie JSON est ajouté à toutes les pages de type page.

C'est tout. Si vous devez écraser n'importe quel des composants des fichiers de gabarit, il vous suffit de placer un fichier homonyme dans le dossier layouts à la racine de votre projet (à condition que les chemins soient identiques bien entendu).

On en parle de l'interface du CMS ou pas ?

Oui !

Comme vous le savez, l'interface graphique n'est pas du ressort d'Hugo. Mais il existe des tonnes de solutions, dont le formidable Forestry.io qui vous permet de générer une belle interface de CMS personnalisable à partir du dépôt git de votre projet Hugo !

Croyez-moi, elles sont toutes bien plus rapides et mieux conçues que ce bon vieux tableau de bord.

Autres fonctionnalités notables

Avant de conclure, passons en revue sans ordre particulier les façons qu'ont WordPress et Hugo de gérer les fonctionnalités les plus communément demandées.

Multilinguisme

Au revoir WPML! 🥳

Hugo gère nativement le multilingue, y compris l'i18n et la traduction de chaînes de caractères.

Reportez-vous à l'article complet de Régis Philibert sur la gestion multilingue dans Hugo.

Menus

Les menus Wordpress sont très puissants mais s'avèrent difficiles à maîtriser pour un développeur. La sortie est gérée à l'aide d'une fonction appelée Walker pas forcément évidente à lire et à comprendre lorsqu'il s'agit de s'aventurer dans des menus à plusieurs niveaux.

La solution proposée par Hugo pour les menus vous laisse assigner n'importe quelle page à un menu ou à une url externe.

Concrètement, si vous avez deux menus sur votre site, vous assigner une page donnée à un menu de la sorte :

# /content/a-propos.md
title: À propos
menu:
  main:
    name: Qui suis-je?
    weight: 2
  footer:
    weight: 1

Si vous avez besoin d'ajouter une url externe au menu main, ça se fait au niveau de la configuration de votre site :

# /config.yaml
menus:
  main:
    - name: Blog
      url: https://blog.tumblr.com
      weight: 3
  footer:
    - name: Blog
      url: https://blog.tumblr.com

Dans l'exemple ci-dessus, votre lien de navigation vers votre page À propos apparaîtra en seconde position dans votre menu principal avec l'intitulé Qui suis-je ? Il apparaîtra également dans le menu de bas de page en première place en reprenant le titre de page: À propos. En plus de cela, les deux menus incluent un lien externe Blog qui pointe vers votre ancien blog tumblr.

Contrairement à WordPress, il n'y a pas de notion d'emplacement de menu. Vous appelez votre objet où vous voulez dans votre gabarit de page avec .Site.Menus.main, .Site.Menus.footer or .Site.Menus.cequevousvoulez et vous bouclez ensuite dessus avec range.

Encore une fois allez voir la doc pour apprendre à ajouter des menus dans vos gabarits de page, c'est une grande avancée par rapport aux bons vieux Walkers (ici c'est plus 🏃‍♀️).

Champs personnalisés

Avec WordPress, à moins que vous aimiez passer des heures à réinventer la roue, vous allez tout le temps vous reposer sur le plugin ACF pour récupérer et modifier les métadonnées des articles.

Hugo, comme Jekyll et d'autres générateurs basés sur Markdown, se repose sur Front Matter pour la gestion de toutes les variables "perso". Cela permet de stocker tous les paramètres non réservés de votre contexte de page dans l'objet .Params.

Donc dans votre gabarit, plutôt que :

<?php if ($subfield = get_field('subfield')){ echo $subfield; } ?>

vous écrivez :

{{ with .Params.subtitle }}{{ . }}{{ end }}

.................................................... ☝️ Vous allez l'aimer ce point !

Les options génériques du site

Qu'en est-il de ces options génériques non rattachées à une page en particulier ?

Et bien une fois de plus, si vous avez pratiqué WordPress après 2013, il y a des chances que vous ayez fait appel à ACF pour gérer ça, parce qu'ajouter des champs optionnels vous même à WordPress c'est vraiment une galère !

Hugo vous propose deux manière de faire. Vous pouvez ajouter des variables personnalisés comme tagline à l'objet Params dans le fichier de configuration principal de votre site et les récupérer avec .Site.Params.tagline par exemple.

Si vous avez des ensembles de données plus complexes, vous pouvez ajouter des fichiers yaml|toml|json dans votre dossier data/. Tout ce qui s'y trouve sera agrégé dans un objet bien pratique .Site.Data accessible dans vos gabarits.

Donc si vous voulez que vos contributeurs puissent gérer les liens vers les réseaux sociaux ainsi que des options génériques, vous pouvez ajouter deux fichiers dans le répertoire data.

# data/socials.yaml
- title: Facebook
  icon: fb
  url: https://facebook.com/hugo_rocks
- title: Twitter
  icon: tw
  url: https://twitter.com/hugoRocks

# data/options.yaml
socials: true
tagline: Hugo rocks!

Et dans votre fichier partiel…

{{/* layouts/partials/socials.html */}}
{{ if .Site.Data.options.social }}
<ul class="socials">
  {{ range .Site.Data.socials }}
    <li>
      <a href="{{ .url }}"><i class="icon icon-{{ .icon }}"></i> {{ .title }}</a>
    </li>
  {{ end }}
</ul>
{{ end }}

Commentaires

Je doute que beaucoup d'entre vous utilisent encore les commentaires natifs de WordPress en 2019… mais il y a des chances pour que vous ayez envie de proposer des discussions à propos de vos articles.

Comme tous les générateurs Hugo se contente de produire des fichiers statiques, il vous faudra donc vous tourner vers un service tiers pour la gestion de vos commentaires.

Heureusement il existe un support natif de Disqus prêt à l'emploi.

Et si vous n'êtes pas fans de Disqus, il existe bien d'autres solutions, qui ne demandent souvent qu'une simple balise script et le balisage correspondant.

Formulaires

Là aussi, il faut passer par un service tiers, le plus souvent gratuit, par exemple :

• Formkeep.io
• Netlify's forms
• TypeForm

Contenu relatif

Générer des suggestions du genre "Vous aimerez aussi" dans WordPress repose entièrement sur des plugins externes ou votre propre requête d'articles personnalisée.

Hugo sait faire ça tout seul comme un grand, et il le fait très bien, à l'aide de son propre système entièrement personnalisable de relation de contenus

Recherche

Comme pour tout ce qui est dynamique, rien de natif dans un générateur de site statique. Ce qui n'est pas pire que la recherche WordPress par défaut si vous voulez mon opinion. Maintenant il existe des douzaines de services qui vont proposer une expérience de recherche digne de ce nom pour vous, parmi eux :

• Lunr.js 🆓
• Algolia et leur incroyable widget InstantSearch.js (🆓 pour les sites de petite et moyenne tailles)

Conclusion

Cet article n'est pas gravé dans le marbre, beaucoup de choses vont continuer d'évoluer dans Hugo, et il se peut que certaines comparaisons ne fassent plus sens.

Nous espérons simplement qu'en étudiant sur les concepts bien arrêtés depuis longtemps et rarement remis en question de WordPress, nous avons contribué à aider quelques utilisateurs de WordPress à mieux comprendre l'état d'esprit et la logique d'Hugo, et qui sait à les convaincre de franchir le pas vers la Jamstack en 2019 ! 🏃

• Un article n'a pas besoin de préciser une catégorie.
• Un article ne peut appartenir qu'à une seule catégorie
• Par convention, les noms de catégories commencent par une majuscule.

Les tags, eux, peuvent figurer dans n'importe quelle catégorie. Un livre étrange et un article technique fantaisiste appartiennent à des catégories différentes, mais peuvent très bien être tous les deux étiquettés "bizarre".

Comment ça marche à l'usage ?

Regardons comment nous allons utiliser les catégories :

• Comment préciser la catégorie d'un article,
• Comment accéder à la catégorie d'un article dans un modèle
• Comment manipuler tous les articles d'une même catégorie

Préciser la catégorie

On utilise la propriété category ainsi pour préciser la catégorie à laquelle appartient l'article :

---
date: 10/30/2018
title: Loomings
category: Tech
tags:
  - tools
  - git
  - eleventy
---

Appeler la catégorie dans un modèle

Dans un modèle, on fait référence à la propriété catégorie comme d'habitude :

<a href="/categories/{{category}}">{{ category }}</a>

Manipuler les articles d'une même catégorie

On peut manipuler les articles d'une même catégories en créant une collection categories ². Pour lister tous les articles rangés dans la catégorie Tech, on pourrait procéder de la sorte :

<ul>
  {%- for article in collections.categories["Tech"] -%}
  <li>{{ article.data.title }}</li>
  {%- endfor -%}
</ul>

Tout comme l'objet collections possède une propriété pour chaque tag, l'objet collections.categories possède une propriété pour chaque catégorie. Chaque propriété fait référence à un tableau d'articles. Ça donne quelque chose comme ça :

collections: {
  all: [ items ],
  categories: {
    Culture: [ items ],
    Life: [ items ],
    Thinking: [ items ]
  }
}

Implémentation

Nous voulons :

• une liste de catégories
• un objet qui contient une propriété pour chaque catégorie, chaque propriété est une liste d'articles pour cette catégorie

Créer une liste de catégories

Pour générer une liste de catégories nous itérons sur tous les fichiers générés. Cette fonction crée une collection categoryList qui contient les noms de toutes les catégories.

getCatList = function (collection) {
  let catSet = new Set();

  collection
    .getAllSorted()
    .forEach(
      (item) =>
        typeof item.data.category === "string" && catSet.add(item.data.category)
    );

  return [...catSet];
};

eleventyConfig.addCollection("categoryList", getCatList);

Créer une liste d'articles pour chaque catégorie

Pour générer les listes d'articles de chaque catégorie, nous voulons créer un objet qui possède une propriété pour chaque catégorie, et chaque propriété contient une liste d'articles de cette catégorie. Pour le dire plus simplement, nous voulons finir avec un objet qui ressemble à ça :

categories {
  Culture: [article_1, article_4],
  Tech: [article_3],
  Life: [article_1, article_3]
}

Nous pouvons utiliser la fonction makeCategories() comme callback de addCollection() pour créer cet objet. Nous itérons sur chaque élément qui possède une propriété category dans son front matter et nous l'ajoutons à la liste de cette catégorie ³ :

makeCategories = function (collection) {
  let categories = {};

  // Every rendered page

  collection.getAllSorted().forEach((item) => {
    let category = item.data.category;

    // Ignore the ones without a category

    if (typeof category !== "string") return;

    if (Array.isArray(categories[category]))
      //  category array exists? Just push
      categories[category].push(item);
    //  Otherwise create it and
    //  make `item` the first, uh, item.
    else categories[category] = [item];
  });

  return categories;
};

Puisque nous souhaitons appeler notre collection de catégories catgories, nous la créons comme cela :

addCollection("categories", makeCategories);

Nous avons maintenant un moyen de créer une collection, qui contient elle-même ses propres collections. Cela me permet de ranger mes articles dans des@ endroits distincts.

Le générateur de site statique open source Eleventy est à la différence d'autres générateurs — comme Jekyll ou Hugo — beaucoup moins opiniâtre. Là où ces deux générateurs vont imposer la manière dont vous pouvez créer des collections de documents (appelées sections de contenu dans Hugo), Eleventy lui vous laisse le choix.

Dans Eleventy les collections permettent de grouper des articles selon divers critères. Une collection pourrait désigner une série d'articles. Un autre collection pourrait regrouper les articles à propos de livres. Une troisième collection pourrait rassembler tous les contenus d'un même répertoire.

Eleventy vous permet de créer des collections de deux manières :

• implicitement, à l'aide de tags dans le front matter
• explicitement, avec la fonction addCollection()

Les collections à base de tags

Toutes les pages qui partagent un même tag appartiennent à la même collection. Un modèle avec le front matter suivant va générer des pages dans les collections books et reviews.

---
title: Finding Oz
category: Culture
tags:
  - books
  - reviews
---
. . .

Dans un modèle, on accède aux collections par leur nom, en tant que propriété de l'object global collections.

<p>
  Le titre de cette page est :
  {{ collections.books[0].data.title }}
</p>

On utilise généralement les collections dans des boucles afin d'itérer sur chaque élément de la collection.

{% for post in collections.books %}
  {{ post.data.title }}
  {{ post.url }}
  {{ post.data.category }}
  {{ post.data.tags }}
  {{ post.date }}
{% endfor %}

L'objet collections lui, ressemble à ça :

{
  "all": [...],
  "nav": [...],
  "books": [
    {
      "inputPath": "./src/articles/finding-oz.md",
      "outputPath": "_site/articles/finding-oz/index.html",
      "fileSlug": "finding-oz",
      "data": {...},
      "date": "2009-08-07T13:52:12.000Z",
      "url": "/articles/finding-oz/",
      "templateContent": "<p>As with most books ... much about The Wizard of Oz</li>\n</ul>\n",
      "template": {...}
    },
    ...
  ],
  "programming": [...],
}

Chaque propriété est un tableau d'objets d'éléments de collection (également appelés objets modèle dans la documentation).

La collection spéciale all représente un tableau de tous les objets page générés par Eleventy.

Implémentation : Comment un tag devient une collection

getTaggedCollectionsData() est la fonction qui transforme des tags en collections.

async getTaggedCollectionsData() {
let collections = {};
collections.all = this.createTemplateMapCopy(
this.collection.getAllSorted()
);
debug(`Collection: collections.all size: ${collections.all.length}`);

let tags = this.getAllTags();
for (let tag of tags) {
collections[tag] = this.createTemplateMapCopy(
this.collection.getFilteredByTag(tag)
);
debug(`Collection: collections.${tag} size: ${collections[tag].length}`);
}
return collections;
}

getTaggedCollectionsData() est appelée dans TemplateMap.cache() qui est l'endroit ou Eleventy génère les collections.

Les collections sur mesure

Outre les collections créées à partir de tags, vous pouvez utiliser la fonction addCollection() dans votre fichier de configuration .eleventy.js pour créer vos propres collections.

Par exemple, voici comment créer une collection nommée articles constituée de pages générées à partir de modèles présents dans le dossier src/articles/ :

eleventyConfig.addCollection("articles", (collection) =>
  collection
    .getAllSorted()
    .filter(
      (item) =>
        item.url &&
        !item.inputPath.includes("index.njk") &&
        item.inputPath.startsWith("./src/articles/")
    )
);

La fonction addCollection() prend deux paramètres¹ :

• le nom de la collection (une chaîne de caractères)
• une fonction qui prend une collection en paramètre.

Vous pourriez penser que le paramètre collection est un tableau d'objets de modèle comme l'objet collections basé sur les tags. Ce paramètre est en fait une instance d'une TemplateCollection, qui dérive de Sortable, et ressemble à ceci :

{
  "items": [
    { ... },
    . . .
    { ... }
  ],
  "sortFunctionStringMap": { ... },
  "sortAscending": true,
  "sortNumeric": false
}

La propriété items est un tableau de tous les objets de modèle. C'est la même chose que collections.all. Vous ne voulez pas accéder aux éléments directement en écrivant : collection.item[n]. Utilisez plutôt les méthodes suivantes pour accéder aux éléments.

Les éléments sont presque les mêmes que ceux des collections basées sur des tags, à la différence près que dans les collections basées sur des tags, les éléments ont une propriété templateContent. Dans les collections créées avec la fonction addCollection(), les éléments ont une propriété _pages. Je ne saurais dire pourquoi.

Vous pouvez utiliser addCollection() pour créer des collections de pages. Depuis Eleventy 0.5.3, vous pouvez l'utiliser pour créer des collections ou des objets de votre choix.

Par exemple, voici comment vous créeriez une collection constituée d'un tableau de toutes les catégories :

module.exports = function (collection) {
  let catSet = new Set();

  collection
    .getAllSorted()
    .forEach(
      (item) =>
        typeof item.data.category === "string" && catSet.add(item.data.category)
    );

  return [...catSet];
};

Implémentation : Comment sont construites les collections sur mesure

getUserConfigCollectionsData() est la fonction qui appelle ce qui est retourné par la fonction addCollection().

async getUserConfigCollectionsData() {
let collections = {};
let configCollections =
this.configCollections || eleventyConfig.getCollections();
for (let name in configCollections) {
let ret = configCollections[name](this.collection);
// work with arrays and strings returned from UserConfig.addCollection
if (
Array.isArray(ret) &&
ret.length &&
ret[0].inputPath &&
ret[0].outputPath
) {
collections[name] = this.createTemplateMapCopy(ret);
} else {
collections[name] = ret;
}
debug(
`Collection: collections.${name} size: ${collections[name].length}`
);
}
return collections;
}

getUserConfigCollectionsData() est appelé dans TemplateMap.cache() qui est l'endroit où Eleventy construit les collections.

Au programme du premier meetup Jamstack Paris, un retour d'expérience sur la migration d'un site Angular vers Gatsby, et un exemple de développement en live d'un plugin Gatsby. Les vidéos sont en ligne.

Dans la première présentation, Louis Lafont, développeur front-end chez MonBanquet, présente la stack qu'il a choisi pour la refonte du site, à savoir Gatsby pour la partie front, Contentful pour la gestion de contenu et Netlify pour héberger le tout.

Il aura fallu près de deux mois à Louis pour mener à bien cette tâche et apprécier la developer experience offerte par Gatsby. Au final grâce notamment au plugin gatsby-image, la PWA générée est bien entendu beaucoup plus rapide, le Time to Interactive est passé sous les deux secondes. Autre gain appréciable, la prise en main rapide de Contentful par l'équipe marketing chargée de la mise à jour des contenus. Tout le monde a gagné en confort d'utilisation, en autonomie et en productivité.

Et le tout pour la modique somme de zéro euro 😲, puisque Gatsby et ses plugins sont sous license open source, et que pour le moment le volume de données consommé ne génère aucun frais d'abonnement aux différentes plate-formes Saas. Le pricing est une bénédiction pour les startups.

Tous le monde est ravi, la prochaine étape sera de s'attaquer à l'authentification utilisateur et d'ajouter un gestion de panier 💳 e-commerce.

Pour la deuxième présentation, Nicolas Goutay, évangéliste performance web chez Theodo, se propose ni plus ni moins de développer un plugin Gatsby en direct. Nicolas avait déjà testé Gatsby sur un projet qui liste les théâtres parisiens.

Grand amateur de disques vinyles, Nicolas comme tout bon nerd a enregistré sa collection dans Discogs, qui propose une API pour récupérer les releases. Problème, le nombre d'appel est très limité, et son premier mockup, ne peut même pas afficher la totalité de sa collection, voire rien du tout si le nombre d'appel à la minute est déjà atteint. Pas glop.

L'application récupére les références des releases sur Discogs pour pouvoir ensuite générer une tracklist de chaque album via l'API de YouTube. Pour contourner la limitation de Discogs, Nicolas a donc eu l'idée d'utiliser Gatsby et de générer son application au build, quitte a espacer les appels à l'API pour pouvoir tout récupérer. Pour cela il a donc développé un plugin Gatsby source, qui va lui permettre de créer facilement des noeuds, qui pourront être ensuite requêter dans GraphQL. La démo permet d'apprécier encore une fois la developer experience offerte par Gatsby, avec notamment une gestion automatique de la documentation de tous les attributs des noeuds.

👏 Un grand bravo aux organisateurs, le prochain meetup aura lieu le 27 février. Au programme encore du Gatsby, cette fois avec du Algolia et du WordPress dedans.

On espère voir toujours plus de retours d'expérience, pas forcément que sur Gatsby, même si les frameworks front-end sont devenus en quelques années le nouveau standard de facto. En tout cas ça fait rudement plaisir de voir que la communauté francophone se fédère, nul doute que ce genre d'évènement contribuera à inciter à l'adoption d'architectures décentralisées.

Jekyll est à ce jour le générateur de site statique le plus utilisé, c'est aussi un des plus anciens, et il fait face aujourd'hui à beaucoup de concurrents. Un des projets récents qui se rapproche le plus de Jekyll est Eleventy, développé par le très sympathique Zach Leat. Eleventy, c'est Jekyll repensé pour tirer parti de JavaScript et de l'écosystème npm. C'est un outil qui reste très simple d'approche et qui supporte Liquid comme langage de gabarit.
Autant d'arguments qui ont vite fait de convaincre Paul Robert Lloyd de tenter de migrer son site vers Eleventy. Qui sait, la lecture de cet article vous incitera peut-être à faire de même ?

Ne pas compliquer les choses s'avère parfois payant. Bien que beaucoup de sites que nous utilisons tous les jours aient besoin de bases de données relationnelles pour gérer leurs contenus, et de pages dynamiques pour répondre aux contributions de leurs utilisateurs, beaucoup de sites plus simples peuvent se contenter de servir du HTML pré-compilé, c'est généralement une solution beaucoup moins onéreuse et bien plus sécurisée.

La Jamstack (JavaScript, APIs réutilisables et Markup préparé à l'avance) est un terme marketing populaire qui désigne cette nouvelle manière d'architecturer des sites web, et en un sens c'est un retour aux débuts du web, avant que les développeurs ne commencent à bricoler avec des scripts CGI ou PHP. En réalité mon site web a toujours servi du HTML pré-compilé : d'abord à l'aide de Movable Type, et puis récemment avec celle de Jekyll, à propos duquel Anna écrivait en 2013.

En combinant trois langages faciles d'approche — Markdown pour le contenu, YAML pour les données et Liquid pour les modèles de page — Jekyll a rencontré un large public et a influencé le design de beaucoup de générateurs de sites statiques qui ont suivi. Jekyll n'en est pas parfait pour autant. Outres des temps de compilation qui peuvent être importants, il est développé en Ruby. Bien que Ruby soit un langage de programmation très élégant, c'est un nouvel écosystème à appréhender et à savoir gérer, en plus ce celui que l'on utilise déjà côté front : JavaScript. Quand j'utilisais Jekyll, je me disais souvent "La même chose, mais en Node". Heureusement pour moi, un des elfes de Noël a exaucé mon vœu Atwoodien et a déposé un tel générateur de site statique au pied de mon sapin.

Présentation d'Eleventy

Eleventy est une alternative beaucoup plus flexible que Jekyll. Outre le fait qu'il soit écrit en Node, il est beaucoup moins strict quant à la manière d'organiser ses fichiers, et supporte d'autres langages de gabarits comme EJS, Pug, Handlebars et Nunjucks, en plus de Liquid. Le top c'est que les temps de compilations sont bien meilleurs (et les optimisations futures promettent des gains supplémentaires).

Vu que le contenu est stocké avec la même combinaison familière de front matter YAML et de Markdown, passer de Jekyll à Eleventy semble plutôt raisonnable au premier abord. Et pourtant, j'ai découvert à mes dépens qu'il y avait quelques pièges. Si vous envisagez une migration, voici quelques petits trucs et astuces pour vous aider dans votre parcours¹.

Avant de commencer

Si vous avez déjà utilisé des outils comme Grunt, Gulp ou webpack, vous connaissez déjà un peu l'écosystème de Node.js, mais si vous avez uniquement utilisé Jekyll pour compiler vos CSS et générer votre HTML, il est maintenant temps pour vous d'installer Node.js et de configurer votre projet afin de pouvoir utiliser son gestionnaire de paquet, npm :

1. Installer Node.js :

• Mac : Si ce n'est pas déjà fait, je vous conseille d'installer Homebrew, a gestionnaire de paquets pour Mac. Ensuite dans un terminal tapez brew install node.
• Windows : Téléchargez l'installateur pour Windows depuis le site web de Node.js et suivez les instructions.

2. Initialiser NPM : Assurez-vous d'être dans le répertoire du projet et tapez npm init. Cette commande va vous poser quelques questions avant de créer un fichier appelé package.json. Comme le Gemfile de RubyGems, il contient la liste des dépendances tierces de votre projet.

Si vous gérez les versions de votre site avec Git, assurez-vous également d'ajouter le répertoire node_modules à votre fichier .gitignore. Contrairement à RubyGems, npm stocke par défaut ses dépendances dans le répertoire de votre projet. Ce répertoire peut vite devenir assez important, et comme il contient des fichiers binaires compilés spécifiquement pour votre ordinateur, il ne devrait pas être versionné. Eleventy prend ce fichier en compte, ce qui veut dire que tout ce que vous voulez que Git ignore, Eleventy l'ignorera aussi.

Installer Eleventy

Maintenant que Node.js est installé et que votre projet est prêt à utiliser npm, nous pouvons installer Eleventy en tant que dépendance :

npm install --save-dev @11ty/eleventy

Si vous ouvrez votre package.json vous devriez y voir figurer les lignes suivantes :

…
"devDependencies": {
  "@11ty/eleventy": "^0.6.0"
}
…

Nous pouvons maintenant lancer Eleventy en ligne de commande à l'aide de l'utilitaire npx de NPM. Par exemple pour convertir le fichier README.md en HTML, nous taperons la commande suivante :

npx eleventy --input=README.md --formats=md

Cette commande va générer un fichier HTML dans _site/README/index.html.
Eleventy utilise par défaut le même répertoire de destination que Jekyll (_site), comme nous le verrons à de nombreuses reprises pendant cette transition.

La configuration

Alors que Jekyll utilise la syntaxe YAML pour son fichier de configuration, Eleventy lui se repose sur JavaScript. Cela permet de programmer des options et ouvre donc des possibilités assez puissantes comme nous le verrons par la suite.

Commençons par créer notre fichier de configuration (.eleventy.js), et reportons les paramètres pertinents du _config.yml dans leurs options équivalentes :

module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "./",      // Équivalent au paramètre source de Jekyll
      output: "./_site" // Équivalent au paramètre destination de Jekyll
    }
  };
};

Quelques choses bonnes à savoir :

• Alors que Jekyll vous permet de lister les fichiers et dossiers à exclure de la génération avec le paramètre exclude, Eleventy recherche ses mêmes valeurs dans un fichier nommé .eleventyignore (en plus du .gitignore).
• Par défaut, Eleventy utilise markdown-it pour parcourir le Markdown. Si vous utilisez des fonctionnalités avancées (comme les abréviations, les listes de définition et les notes de bas de page), vous devrez déclarer votre propre instance de cette bibliothèque Markdown (ou d'une autre) à Eleventyet la configurer avec les options et les plugins de votre choix.

Les gabarits de mise en forme

Eleventy manque encore de flexibilité quant à la localisation des layouts, qui doivent pour le moment se trouver dans le répertoire _includes (Surveiller la résolution du problème sur GitHub).

Nous allons donc devoir déplacer nos fichiers du répertoire _layouts vers _includes\layouts, puis mettre à jour les références pour y incorporer le sous-dossier layouts. Nous pourrions mettre à jour la propriété layout: dans le front matter de chacun de nos fichiers de contenu, mais nous allons opter pour la création d'alias dans la configuration d'Eleventy :

module.exports = function(eleventyConfig) {
    // les alias sont relatifs au répertoire _includes
    eleventyConfig.addLayoutAlias('about', 'layouts/about.html');
    eleventyConfig.addLayoutAlias('book', 'layouts/book.html');
    eleventyConfig.addLayoutAlias('default', 'layouts/default.html');

    return {
      dir: {
        input: "./",
        output: "./_site"
      }
    };
  }

Déterminer le langage à utiliser pour les gabarits

Par défaut Eleventy va transformer les fichiers Markdown (.md) avec Liquid, mais nous avons aussi besoin de dire à Eleventy comment procéder au traitement des autres fichiers qui utilisent des gabarits Liquid. Il existe pour cela plusieurs manières de faire, la plus simple étant de modifier les extensions des fichiers. Ici, quelques fichiers se trouvent dans notre dossier api que nous voulons traiter avec Liquid et exporter au format JSON. Pour cela nous ajoutons le suffixe .liquid à notre fichier (en conséquence basic-syntax.json devient basic-syntax.json.liquid), Eleventy saura alors quoi faire.

Les variables

De l'extérieur, Jekyll et Eleventy se ressemblent pas mal, mais chaque outil modélise son contenu et ses données d'une manière légèrement différente, il va donc nous falloir mettre à jour quelques variables dans nos modèles.

Les variables de site

En plus des directives de compilation, Jekyll vous permet de stocker des variables globales dans son fichier de configuration et d'y accéder dans les modèles via l'espace de nom site.*. Par exemple dans notre Guide Markdown nous avons les valeurs suivantes :

title: "Markdown Guide"
url: https://www.markdownguide.org
baseurl: ""
repo: http://github.com/mattcone/markdown-guide
comments: false
author:
  name: "Matt Cone"
og_locale: "en_US"

Le fichier de configuration d'Eleventy utilise JavaScript et n'est pas fait pour stocker de telles valeurs. Toutefois comme avec Jekyll, nous pouvons utiliser des fichiers de données pour stocker des variables globales. Si nous ajoutons nos données relatives au site dans un fichier JSON situé dans le dossier _data et que nous le nommons site.json, nous pouvons continuer à utiliser l'espace de nom site.* et laisser nos variables telles quelles.

{
    "title": "Markdown Guide",
    "url": "https://www.markdownguide.org",
    "baseurl": "",
    "repo": "http://github.com/mattcone/markdown-guide",
    "comments": false,
    "author": {
      "name": "Matt Cone"
    },
    "og_locale": "en_US"
  }

Les variables de page

Le tableau ci-dessous établit la correspondance entre les variables de page. Retenez qu'on peut accéder directement aux propriétés front matter, alors que les valeurs des méta-données dérivées (comme les URLs, les dates, etc.) sont préfixées avec l'espace de nom pages.* :

Lorsque d'une itération sur des pages, les valeurs front matter sont accessibles via l'objet data et le contenu via templateContent :

Espérons que ces différences entre les pages et les variables d'item disparaissent dans une future version (suivre le problème sur GitHub), afin de faciliter la compréhension de la manière dont Eleventy structure ses données.

Les variables de pagination

Alors qu'avec Jekyll, la pagination est limitée à lister des articles sur une page, Eleventy vous permet de paginer n'importe quelles données ou documents de collections. Vu cette disparité, les changements sont plus importants, mais ce tableau liste la correspondance des variables équivalentes :

Les filtres

Jekyll propose quelques filtres supplémentaires, en plus de ceux fournis par défaut par Liquid. Il y en a un certain nombre — cet article ne peut pas tous les couvrir — mais vous pouvez les répliquer avec l'option de configuration addFilter d'Eleventy. Convertissons les deux filtres utilisés par notre Guide Markdown : jsonify et where.

Le filtre jsonify sert à exporter un objet ou une chaîne de caractères dans un format JSON valide. Comme JavaScript propose une méthode JSON native pour cela, nous pouvons l'utiliser dans notre filtre. La méthode addFilter prend deux paramètres en entrée : en premier le nom du filtre, en deuxième la fonction dans laquelle nous voulons passer le contenu pour le transformer :

// {{ variable | jsonify }}
  eleventyConfig.addFilter('jsonify', function (variable) {
    return JSON.stringify(variable);
  });

Le filtre where de Jekyll est un peu plus complexe au sens où il prend deux arguments additionnels, la clef sur laquelle on veut effectuer la recherche et la valeur recherchée :

{{ site.members | where: "graduation_year","2014" }}

Pour reproduire ce comportement, nous pouvons passer trois arguments au lieu d'un à la fonction passée à addFilter: le tableau (array) que nous voulons examiner, la clef sur laquelle on veut effectuer la recherche et la valeur recherchée :

// {{ array | where: key,value }}
  eleventyConfig.addFilter('where', function (array, key, value) {
    return array.filter(item => {
      const keys = key.split('.');
      const reducedKey = keys.reduce((object, key) => {
        return object[key];
      }, item);

      return (reducedKey === value ? item : false);
    });
  });

Il se passe pas mal de trucs dans ce filtre, que je vais tenter d'expliquer.
Nous examinons chaque item dans notre array, et nous réduisons la key (passée comme une chaine à l'aide de la notation avec le point) de manière à pouvoir être analysée correctement (comme une référence d'objet) avant de comparer sa valeur avec celle de value. Si elle correspond, l'item reste dans le tableau retourné, sinon il est supprimé. Pfiou !

Les includes

Comme pour les filtres, Jekyll fournit un jeu de tags qui ne fait pas partie intégrante du cœur de Liquid. Parmi eux, l'un des plus utiles est le tag include. La bibliothèque utilisée par Eleventy, LiquidJS fournit aussi un tag include, mais sa syntaxe diffère légèrement de celle définie par Shopify. Si vous ne passez pas de variables en paramètre de vos includes, vous ne devriez pas à avoir à faire de modification pour que ça marche.
Dans le cas contraire, alors qu'avec Jekyll vous écrivez :

<!-- page.html -->
{% include include.html value="key" %}

<!-- include.html -->
{{ include.value }}

dans Eleventy, vous allez écrire :

<!-- page.html -->
{% include "include.html", value: "key" %}

<!-- include.html -->
{{ value }}

L'inconvénient de la syntaxe Shopify c'est que les assignations de variables ne sont plus limitées au périmètre de l'include et peuvent donc être exposées ailleurs ; gardez cela bien en tête lors de la conversion de vos gabarits, car vous aurez peut-être à faire des ajustements supplémentaires.

Paramétrer Liquid

Vous aurez peut-être remarqué dans l'exemple ci-dessus que LiquidJS s'attend à ce que le nom des fichiers d'inclusion soient entre guillemets (sinon ils seront traités comme des variables). Nous pourrions mettre à jour nos gabarits pour ajouter des guillemets autour des noms de fichier (c'est l'approche conseillée), mais nous pouvons aussi désactiver ce comportement en mettant l'option`dynamicPartialsde LiquidJS àfalse\.

En outre, Eleventy ne supporte pas le tag include_relative, nous ne pouvons donc pas inclure des fichiers relativement à l'emplacement du fichier courant. Toutefois, LiquidJS nous laisse définir plusieurs chemins dans lesquels rechercher les fichiers à inclure via l'option root.

Heureusement pour nous, Eleventy nous laisse passer des options à LiquidJS :

eleventyConfig.setLiquidOptions({
    dynamicPartials: false,
    root: [
      '_includes',
      '.'
    ]
  });

Les collections

Dans Jekyll les collections permettent aux auteurs de créer les collections de documents de leur choix, en plus des pages et des articles. Eleventy propose une fonctionnalité similaire, mais qui permet de faire beaucoup plus de choses.

Les collections dans Jekyll

Dans Jekyll, pour créer des collections, vous devez ajouter leurs noms dans le fichier _config.yml et créer les dossiers correspondants dans votre projet. Notre guide Markdown possède deux collections :

collections:
    - basic-syntax
    - extended-syntax

Elles correspondent aux dossiers _basic-syntax et _extended-syntax, nous pouvons itérer sur leurs contenus de la sorte :

{% for syntax in site.extended-syntax %}
  {{ syntax.title }}
{% endfor %}

Les collections dans Eleventy

Il existe deux manières de configurer des collections dans Eleventy. Tout d'abord, en utilisant simplement la propriété tag dans le front matter des fichiers de contenu :

---
title: Barré
syntax-id: barre
syntax-summary: "~~La terre est plate~~"
tag: extended-syntax
---

Nous pouvons ensuite itérer sur les contenus étiquetés de la sorte :

{% for syntax in collections.extended-syntax %}
  {{ syntax.data.title }}
{% endfor %}

Eleventy permet aussi de déclarer des collections à l'aide de la fonction addCollection. Par exemple, plutôt que d'utiliser des tags, nous pouvons rechercher des fichiers à l'aide d'un motif global (une manière de spécifier un ensemble de fichiers à rechercher à l'aide de caractères joker) :

eleventyConfig.addCollection('basic-syntax', collection => {
  return collection.getFilteredByGlob('_basic-syntax/*.md');
});

eleventyConfig.addCollection('extended-syntax', collection => {
  return collection.getFilteredByGlob('_extended-syntax/*.md');
});

Nous pouvons faire encore mieux. Par exemple, imaginons que nous voulions trier une collection par la propriété display_order du front matter de nos documents. Nous pourrions prendre les résultats retournés par la fonction collection.getFilteredByGlob et les trier à l'aide de la fonction sort de JavaScript :

eleventyConfig.addCollection('example', collection => {
  return collection.getFilteredByGlob('_examples/*.md').sort((a, b) => {
    return a.data.display_order - b.data.display_order;
  });
});

Avec un peu de chance, cet exemple vous a fait comprendre ce qu'il est possible de faire avec cette approche.

Utiliser les données de répertoire pour définir les paramètres par défaut

Par défaut, Eleventy ne va pas toucher à la structure de vos fichiers de contenus quand il va générer le site. Dans le cas présent, cela signifie que /_basic-syntax/lists.md sera généré sous /_basic-syntax/lists/index.html. Comme dans Jekyll, nous pouvons définir où les fichiers seront générés à l'aide de la propriété permalink. Par exemple si nous voulons que cette page devienne accessible sous /basic-syntax/lists.html nous pouvons ajouter :

---
title: Lists
syntax-id: lists
api: "no"
permalink: /basic-syntax/lists.html
---

Là encore, ce n'est pas quelque chose que vous voulez gérer au niveau de chaque fichier, et une fois de plus Eleventy propose des fonctionnalités qui peuvent vous aider : les données de dossier et les variables pour les permaliens.

Par exemple, pour parvenir au même résultat que précédemment pour tous les contenus stockés dans le dossier _basic-syntax, nous pouvons y créer un fichier JSON du même nom, _basic-syntax/_basic-syntax.json et y définir nos valeurs par défaut. Pour les permaliens, nous avons le droit d'utiliser une variable Liquid pour construire le chemin désiré :

{
  "layout": "syntax",
  "tag": "basic-syntax",
  "permalink": "basic-syntax/{{ title | slug }}.html"
}

Maintenant, le guide Markdown ne publie pas les exemples de syntaxe sous forme d'URLs individuelles et permanentes, il se contente d'utiliser les fichiers de contenu pour stocker les données. Modifions donc un peu tout ça. Affranchissons-nous des règles imposées par Jekyll sur l'emplacement et le nom des dossiers de collections, et déplaçons tout dans un dossier nommé _content :

markdown-guide
└── _content
    ├── basic-syntax
    ├── extended-syntax
    ├── getting-started
    └── _content.json

Ajoutons également un fichier de données (_content.json) dans ce dossier. Comme les règles définies au niveau du dossier sont appliquées de manière récursive, cela signifie que tous les fichiers contenus dans cette arborescence ne seront plus publiés :

{
  "permalink": false
}

Les fichiers statiques

Eleventy ne va transformer que les fichiers dont il connaît les gabarits. Maintenant nous pouvons aussi avoir des fichiers statiques qui n'ont pas besoin d'être convertis, mais que nous devons copier dans le dossier de destination. Pour cela, nous pouvons utiliser la copie de fichier "passe-plat". Dans notre fichier de configuration, nous indiquons à Eleventy quels dossiers/fichiers copier via l'option addPassthroughCopy. Puis nous activons cette fonctionnalité dans ce qui est retourné, en mettant passthroughFileCopy à true :

module.exports = function(eleventyConfig) {
  …

  // Copy the `assets` directory to the compiled site folder
  eleventyConfig.addPassthroughCopy('assets');

  return {
    dir: {
      input: "./",
      output: "./_site"
    },
    passthroughFileCopy: true
  };
}

Considérations finales

Gestion des assets

Contrairement à Jekyll, Eleventy ne propose aucun support de compilation et d'assemblage des scripts — ce ne sont pas les options qui manquent dans l'écosystème npm dans ce domaine. Si vous utilisiez Jekyll pour compiler vos fichiers Sass en CSS, ou CoffeeScript en JavaScript, vous devrez rechercher comment faire ça, car malheureusement ce n'est pas le but du présent article.

Publication sur GitHub Pages

Un des gros avantages de Jekyll, c'est son intégration dans GitHub Pages. Pour publier un site généré avec Eleventy — ou tout autre site non généré par Jekyll — sur GitHub Pages peut s'avérer compliqué, et implique généralement de devoir copier le site généré dans la branche gh-pages ou d'inclure cette branche comme un sous-module Git. Vous pouvez aussi utiliser un service d'intégration continue comme Travis ou CircleCI et pousser le site généré sur votre serveur web. De quoi vous faire tourner la tête !

C'est peut-être pour cette raison que des services spécialisés dans l'hébergement de fichiers statiques ont émergé comme Netlify ou Google Firebase. Rappelez-vous cependant que vous pouvez publier un site statique où vous voulez !

Montez d'un cran

Si vous songiez à passer à Eleventy, j'espère que ce bref aperçu vous aura été utile. Il sert également à rappeler qu'il n'est pas toujours prudent de prendre le train en marche.

Essayer de nouveaux outils et des technologies émergentes est toujours gratifiant, cela demande pas mal de travail et de compromis. Eleventy est très intéressant, mais il n'a qu'un an, et donc peu de thèmes ou de plugins sont disponibles. De plus, il n'est maintenu que par une seule personne. Alors que Jekyll est un projet mature, qui possède une grande communauté, ainsi que de nombreux contributeurs et mainteneurs.

J'ai passé mon site sous Eleventy car la lenteur et la rigidité de Jekyll m'empêchaient de faire ce que je voulais. Mais j'ai également investi du temps dans cette migration. Après avoir lu ce guide, et en fonction des spécificités de votre projet, vous déciderez peut-être de garder Jekyll, surtout si c'est pour parvenir au même résultat. Et ce n'est pas un problème !

Mais ceux-là vont jusqu'à 11.

La popularité croissante des architectures décentralisées s'explique par l'évolution de l'offre de services disponibles. Que ce soit pour héberger du code source, gérer ses contenus, fournir une authentification, une gestion des paiements, etc. faire appel à des services distants fait de plus en plus sens pour les entreprises dont l'informatique n'est pas le coeur de métier mais simplement un moyen de fournir un service à leurs clients.

À l'heure où les entreprises se débattent pour devenir plus agiles et rester pertinentes, elles peuvent compter sur les dernières évolutions des technologies. Oubliez Docker, Jamstack marque la prochaine évolution du développement web moderne.

Jamstack c'est pour JavaScript, APis et Markup. C'est la merveilleuse union de technologies modernes, du logiciel as a service et des langages au coeur des fondations du web. Cette stack procure :

• une réduction des coûts,
• une mise sur le marché plus rapide,
• une sécurité accrue,
• plus de fiabilité, de disponibilité, et une meilleure adaptation à la montée en charge,
• une réduction de la dépendance à des technologies propriétaires.

Les technologies comme Docker vont continuer à jouer un rôle primordial dans le futur du numérique, mais elles devraient devenir de plus en plus transparentes pour la majorité des entreprises et seront utilisées sans que vous le sachiez. Le fait de devoir gérer et maintenir soi-même sa propre infrastructure appartiendra bientôt au passé.

Si votre coeur de métier n'est pas de fournir des services dans le Cloud, cet article vous explique pourquoi la Jamstack devrait devenir votre première préoccupation si vous tenez à fournir un avantage stratégique et une agilité accrue à la majorité de vos activités en ligne.

La Jamstack ?

La Jamstack c'est en partie du JavaScript et du code généré qui peuvent être hébergés en statique n'importe où. Elle est parfaitement complémentaire avec les technologies serverless et peut faire appel à des fonctions serverless exécutées dans le Cloud. Les serveurs d'applications traditionnelles sont en passe d'être totalement superflus, en leur lieu et place une bonne partie de la complexité est résolue lors de l'étape de génération à l'aide de l'outillage fourni par entre autres par JavaScript.

Des générateurs de site statiques comme Next.js ou Gatsby sont souvent utilisés pour combler le besoin de faire du rendu côté serveur. Ces outils s'intègrent parfaitement avec des services du Cloud pendant l'étape de génération et produisent en sortie une application complète composée de pages pré-rendues. Par exemple, ces outils peuvent récupérer des contenus stockés dans un CMS headless et générer l'ensemble de votre site sous forme de pages statiques en quelques secondes. Un instantané immuable de toutes ces pages peut alors être déployé en production et distribué partout dans le monde.

Il est possible de déclencher des modifications à partir de n'importe quel service en aval grâce à des webhooks et de générer une nouvelle version en quelques secondes après avoir récupéré le contenu mis à jour.

Bien que les applications Jamstack soient hébergées de manière statique, cela ne veut pas dire qu'elles n'en sont pas moins dynamiques ou interactives que des pages dont le rendu est effectué côté serveur. Ces applications peuvent être conçues pour interagir avec des APIs web côté client et peuvent fournir du contenu dynamique et de l'interactivité comme n'importe quelle application classique. On peut toujours authentifier des utilisateurs et enrichir les pages progressivement en fonctionnalités.

Des fonctions exécutées depuis le Cloud peuvent fournir des capacités de services additionnelles au besoin, et peuvent être elles aussi être écrites en JavaScript.

Pourquoi la Jamstack ?

Un application Jamstack réduit les dépendances nécessaires lors de l'exécution pour des performances, une fiabilité, une capacité de montée en charge et une sécurité maximales. En effet comme elles n'ont pas besoin de serveurs d'application dédiés pour servir les pages, cela réduit considérablement la surface d'attaque possible. Le contenu statique est extrêmement facile à mettre en cache et à distribuer via un fournisseur d'accès au Cloud. Vous ne dépendez pas d'un fournisseur en particulier.

Les entreprises peuvent développer des solutions à l'aide de la Jamstack pour se lancer plus rapidement sur le marché et ce à moindre coût. C'est dû au fait qu'il y a besoin de beaucoup moins de ressources pour gérer et maintenir l'application en production et en développement. Une petite équipe agile multi-disciplinaire aura seulement besoin d'être en capacité de livrer du HTML, du CSS et du JavaScript. Pas besoin d'avoir beaucoup d'autres compétences quand il s'agit de publier pour le web.

Dans les applications traditionnelles, les mises à jour de dépendances se font généralement sur le serveur. Cela augment le risque d'interruption. Avec la Jamstack comme tout se fait en aval, il y a beaucoup moins de chances que quelque chose puisse impacter les utilisateurs finaux — et encore moins si les générations sont testées automatiquement avant la mise en production.

La JAMStack sur repose sur les services dans le Cloud pour l'extension de fonctionnalités. Elle suit la tendance du développement JavaScript full-stack facilité par des outils comme React et les offres de "functions as a service" du Cloud. Fini les serveurs d'applications et les systèmes monolithiques avec des bases de données SQL. Plus besoin d'une infrastructure disponible en permanence pour effectuer du rendu côté serveur à l'aide de langages compilés comme Java ou .NET.

Une architecture Jamstack n'est jamais aussi performante que lorsqu'elle utilise les services d'un hébergeur spécialisé comme Netlify. Netlify est une plate-forme complète de Cloud pour les architectures Jamstack, qui se connecte directement à votre dépôt de code. Chaque sauvegarde permet d'à la fois versionner et déployer votre application et ses fonctions de support dans le Cloud sur votre environnement de production en quelques secondes.

Netlify déploie vos applications sur son réseau global de CDN pour une performance optimale et propose également d'autres fonctionnalités à forte valeur ajoutée, que vous auriez dû autrement développé ou configurer vous-mêmes.

Verrou logiciel

Beaucoup d'entreprises utilisent des logiciels tiers qu'elles hébergent elles-mêmes, ces logiciels demandent d'avoir des équipes importantes chargées de leur développement, de leur déploiement et de leur maintenance, avant même que vous n'ayez songé à développeur votre application. Parfois les deux sont indissociables et cela augmente considérablement les compétences minimales requises dont vous auriez normalement besoin pour développer votre application.

Les systèmes de gestion de contenu (CMS) en sont un parfait exemple. Quand ces fonctionnalités ne sont pas au coeur de votre activité, aujourd'hui cela n'a plus aucun sens d'investir du temps et des ressource spécialisées pour leur maintenance, leur disponibilité et leur support. Ce fut pendant longtemps la seule option disponible et un sacrifice à consentir pour essayer de tirer parti de la valeur ajoutée que ces outils pouvaient vous procurer en retour.

Depuis les offres de services ont évolué et les solutions adaptatives du Cloud entièrement gérées et maintenues pour une fraction du prix ont changé la donne. Prismic et Contentful sont des exemples de solutions de CMS découplés qui offrent des APIs web hautement interopérables. Plus besoin des compétences d'un expert maison, ces services s'intègrent facilement à une architecture Jamstack, quelle que soit la technologie choisie.

Sur le même principe, presque n'importe quelle fonctionnalité peut être lancée ou générée par des services offerts par le Cloud. Cela inclut des serices d'intégration et de déploiement continus qui peuvent être déclenchés à la demande. Dans la plupart des cas, il n'y a plus besoin d'héberger et de gérer vos propres serveurs qu'ils soient chez vous ou dans le Cloud.

Commodités logicielles

Étant donnée que les offres Saas (Software as a service) transforment les produits en services dans le Cloud, les entreprises doivent repenser leur stratégie pour rester agiles.

Il est critique pour une entreprise de comprendre l'offre actuelle et de faire appels à ces services distants lorsque c'est possible de façon à réduire ses coûts et éviter de fournir un effort inutile en reproduisant ces infrastructures disponibles partout en interne à un coût plus important.

Les commodités, c'est quand des produits sont disponibles à grande échelle, en importante quantité et qu'ils sont hautement standardisés. Les commodités répondent à un but très précis et évoluent au fil du temps à travers les répliques et les affinements d'un produit.

Ici le terme commodité fait référence à la technique de cartographie de Wardley et décrit la façon dont les produits évoluent : de leur genèse à des solutions sur mesure, puis à des produits et enfin à des commodités. Parmi les composants de la topologie d'un business qui favorisent l'évolution des process, et en fonction de leur valeur pour le client, vous pouvez établir une stratégie et décider sur quoi votre entreprise doit porter ses efforts afin de vous focaliser uniquement sur votre canal de vente.

Avec la Jamstack, on tire parti des services du Cloud comme suit :

• hébergement de fichiers statiques plutôt que des serveurs d'application,
• intégration et déploiement dans le Cloud plutôt que chez soi en fonction de ses capacités,
• partenaires Saas plutôt que des produits tiers hébergés en interne,
• fonctions déclenchées à la demande dans le Cloud plutôt que sur des serveurs qui tournent en permanence,
• des développeurs JavaScript full-stack plutôt que des compétences et des langages variés.

En résumé

Les technologies comme Docker sont au coeur des infrastructures modernes. Elles simplifient le provisionnement de ressources de manière très consistante et très fiable.

Toutefois, à moins que vous soyez un expert qui fournit des services dans le Cloud, se focaliser sur l'infrastructure ne fait plus sens.

Une grande partie de la complexité de l'infrastructure de développement d'un produit interne provient de dépendances lourdes comme celles à des systèmes de gestion de contenu. Pendant longtemps il a fallu héberger des logiciels tiers, les configurer pour qu'ils soient tout le temps disponibles, et posséder des compétences variées pour développer et maintenir l'ensemble. Cela pousse les entreprises à s'engouffrer dans de faux problèmes en se focalisant sur l'infrastructure et le déploiement, plutôt que de se défaire de ces dépendances qui peuvent s'avérer douloureuses à gérer.

La Jamstack propose un modèle d'architecture efficace pour remplacer l'approche traditionnelle du développement web et permet à une petit équipe agile d'adopter un bon rythme. Plus besoin de se préoccuper de l'infrastructure et des serveurs. Elle encourage également l'intégration d'autres offres SaaS qui fournissent des APIs interopérables et s'affranchit des systèmes

La Jamstack rend les mises à jour, le support et le redimensionnement de ses applications trivial. C'est l'assurance d'une agilité accrue et d'un lancement sur le marché plus rapide, avec de meilleures performances. Le monde de l'entreprise bouge lentement et ceux qui pourront s'adapter en tireront un avantage compétitif.

Il y a trois ans, fatigué par WordPress et de sa galaxie de plugins douteux, j'ai décidé de migrer vers un générateur de site statique. Après quelques essais avec diverses solutions, j'ai opté pour Jekyll, dont la communauté me semblait plus mature. Trois ans plus tard, je commence à comprendre les forces et les faiblesses de la solution, mais je reste loin d'en maîtriser tous les mystères. Je l'ai bidouillée pour publier du contenu multilingue, j'ai développé mes propres plugins, j'ai intégré des éléments d'architecture piochés chez des amis… Disons que je suis désormais assez à l'aise. Par contre, à force de manipulations, mon Jekyll ressemblait moins au célèbre docteur qu'au monstre de Frankenstein : un assemblage de portions de code grossièrement liées entre elles par des liens fragiles, se déplaçant lentement en gémissant… En un mot comme en cent : mon build était lent.

TL;DR

• Constatant que ma compilation Jekyll était des plus lentes, j'ai contacté la communauté Jamstack francophone pour des conseils.
• Plusieurs choses ont émergé, chaque conseil permettant d'optimiser le temps de compilation.
• Le plus gros gain provient des évolutions de Jekyll lui-même, sur lequel l'équipe est en train de faire un énorme travail.

Pour générer mon site (source), j'ai développé un ensemble de commandes Rake¹ qui se chargent de nettoyer l'espace de travail, de déterminer l'environnement de destination et de configurer la compilation en conséquence, de vérifier l'intégrité des en-têtes front matter de mes articles, de générer le site avec Jekyll et, enfin, de contrôler ce qui est produit en utilisant la gemme html-proofer. Je n'exécute pas tout cela sur mon ordinateur : à la place, je délègue cette tâche à Netlify, branché sur mon dépôt GitHub pour compiler et déployer mes branches.

Toutes ces tâches prenaient individuellement du temps, mais la partie dédiée à la génération avec Jekyll restait la plus consommatrice de CPU, prenant plusieurs minutes. Résultat : pendant des mois, mes compilations Netlify ont duré plus de 10 minutes. Chaque compilation était plus lente que la précédente.

Il y a quelques jours, Netlify a complètement arrêté le déploiement du site web car mes compilations prenaient tellement de temps qu'elles dépassaient la limite imposée par le système d'intégration continue de Netlify².

Il était temps d'agir.

Un proverbe africain dit :

Seul, on va plus vite. Ensemble, on va plus loin.

Je ne pense pas que ce soit tout à fait vrai. Je crois que lorsque nous nous entourons des bonnes personnes, nous pouvons aller ailleurs, vers des possibilités que nous n'avions même pas envisagées.

Quand j'ai pensé que j'atteignais la limite de mes compétences, j'ai demandé l'aide à la communauté que je connais le mieux : les membres de Jamstatic. Et parmi eux, un membre de la Core Team de Jekyll, Frank. Il m'a beaucoup aidé (et continue de le faire) en me montrant des possibilités que je n'avais pas envisagées.

Inclusions : à consommer avec modération

L'expérience m'a appris qu'il est souvent plus difficile de maintenir un projet que de le réaliser en premier lieu. Pour augmenter ses chances de succès, mieux vaut trouver des techniques d'organisation du code qui soient adaptées à sa compréhension sur le long terme. À mon sens, diviser le code en portions significatives est l'une des astuces de maintenance les plus efficaces.

Dans Jekyll, cela se fait avec des inclusions, via la balise {% include %}. Mais attention, une décomposition de code trop ambitieuse aura un coût sur votre temps de compilation, que vous pourrez visualiser avec le profileur Liquid [EN].

D'après Pat Hawks, membre de la Core Team Jekyll :

Chaque fois que vous utilisez une balise {% include %}, Jekyll doit ouvrir le fichier concerné, lire son contenu en mémoire, puis analyser le gabarit avec Liquid. Cela se produit à chaque {% include %}, et pas une seule fois par fichier ! Donc l'utilisation d'une même inclusion sur 100 pages provoquera le chargement et l'analyse de cette inclusion 100 fois. Le problème s'aggrave très rapidement si vous commencez à faire des inclusions dans vos inclusions…

Une façon de surmonter ce coût supplémentaire est de mettre en cache les blocs compilés pendant l'interprétation de votre {% include %}. Il y a un plugin pour cela : le plugin jekyll-include-cache de Ben Balter. Mais attention à deux choses très importantes :

1. assurez-vous de passer toutes les données nécessaires à votre {% include %} en paramètres, car elles seront utilisées comme clés pour le cache ;
2. si vous le pouvez, n'utilisez des inclusions que pour générer des portions de code réutilisables. Si les paramètres de l'inclusion la rendent si spécifique qu'elle n'est pas réutilisable ailleurs, alors le cache relatif à cette inclusion aura été construit pour rien et n'apportera aucun gain de performance.

Ces deux contraintes sont si fortes qu'elles m'ont obligé à réintégrer plus de la moitié de mes inclusions dans mes gabarits (_layouts). Je ne suis pas entièrement satisfait de cette situation (car, en conséquence, je trouve que les capacités de maintenance sont dégradées) mais je dois avouer que j'ai gagné près de 10 % de temps de compilation³ en sacrifiant ce petit confort.

Et avec des commentaires Liquid ({% comment %}This is a comment{% endcomment %}), je peux toujours organiser efficacement mon code, même réintégré dans un seul fichier.

Faites confiance aux gemmes compilées en C

Par défaut, Jekyll est basé sur un ensemble de gemmes écrites en Ruby. Récemment, de nouvelles gemmes sont apparues, partiellement écrites en C, ce qui améliore leur performance d'exécution. L'équipe Jekyll a eu la gentillesse d'ajouter des tests conditionnels dans le générateur pour utiliser ces gemmes si elles sont référencées dans votre Gemfile. Vous n'avez donc qu'à ajouter les gemmes à votre Gemfile pour tirer parti de ces améliorations.

Il en existe certainement d'autres, mais en voici au moins deux :

• la gemme liquid-c, pour optimiser la compilation Liquid ;
• la gemme sassc, si vous avez besoin de Jekyll pour compiler des fichiers Sass plus efficacement.

Je n'ai pas besoin de Jekyll pour mes fichiers Sass mais en utilisant liquid-c, j'ai économisé 9 % du temps de compilation.

Si vous pouvez l'éviter, n'utilisez pas LSI

Jekyll est livré avec une option très pratique appelée Latent Semantic Indexing (LSI) dont le rôle est d'analyser tout le contenu avant de générer le site, afin d'alimenter, pour chaque article, une collection qualitative d'articles connexes (au lieu des dix articles les plus récents). LSI fait un très bon travail mais si vous avez des centaines d'articles comme moi, il fonctionnera lentement, très lentement⁴.

Après une très rapide non-analyse des données analytiques dont je ne dispose pas⁵, j'ai décidé de me séparer de la proposition d'articles associés et d'économiser 17 % du temps de compilation.

Markdown : choisissez la bonne variante

Markdown est un langage à balisage léger vraiment sympa mais il lui manque une chose très importante : une standardisation. Il existe des douzaines de parseurs Markdown, chacun avec ses caractéristiques spécifiques. Depuis quelque temps, une initiative de standardisation émerge autour de CommonMark, et les projets l'implémentant fleurissent.

Par défaut, Jekyll utilise kramdown, un surensemble de Markdown développé en Ruby qui fait du très bon boulot. Pour le remplacer par CommonMark, j'ai voulu utiliser commonmarker qui est, encore une fois, un wrapper Ruby pour une implémentation en C. Pour en tirer parti dans Jekyll, vous pouvez utiliser le plugin jekyll-commonmark de Pat Hawks.

Attention, la transition n'est pas sans adaptations. kramdown et CommonMark sont assez différents : en passant de l'un à l'autre, j'ai dû sacrifier quelques sucres syntaxiques.

Par exemple, CommonMark ne supporte pas les attributs de bloc tels que { :.myclass} pour décorer un paragraphe de contenu. Vous aurez besoin d'utiliser de bonnes vieilles balises HTML. N'oubliez pas d'activer l'option UNSAFE dans votre configuration Jekyll (_config.yml) si vous ne voulez pas générer beaucoup de commentaires du type <!-- raw HTML omitted --> :

markdown: CommonMark
commonmark:
  options: ["SMART", "FOOTNOTES", "UNSAFE", "HARDBREAKS"]
  extensions: ["strikethrough", "autolink", "table"]

Vous remarquerez peut-être aussi que CommonMark est moins tolérant que kramdown, qui corrige à la volée de nombreuses approximations de contribution. Passer à cet analyseur m'a aidé à détecter des problèmes dans mes articles que je n'avais jamais remarqué auparavant. Si vous avez un contenu conséquent, attendez-vous à devoir corriger quelques coquilles.

Un petit prix à payer pour gagner encore 9 % de temps de compilation.

Faites confiance à la Team pour aller dans la bonne direction

Enfin, l'une des dernières améliorations apportées a été le passage à la version master de Jekyll. Depuis la version 3.8.5 (ma version précédente), de nombreuses améliorations ont été apportées, et le gain de performance est vraiment considérable : 93 % !

Je n'arrivais tellement pas à y croire que j'ai temporairement versionné mon dossier _site et vérifié qu'il n'y avait rien de cassé en changeant de version. Et dans mon cas : rien à redire, tout est parfait.

Si vous ne deviez retenir, ou tester, qu'une seule optimisation, c'est celle-ci. Faites confiance à la Core Team, la performance est une de leurs priorités.

Qu'en est-il de mon chantier multilingue ?

Avec toutes ces optimisations, ma compilation Jekyll est passée de plus de 15 minutes à environ une minute. C'est encore beaucoup, et je sais pourquoi : ma gestion "fait maison" de l'internationalisation, et plus particulièrement de la traduction de mes articles, est sous-optimale.

Elle est basée sur une clé front matter i18n-key qui me permet de faire se correspondre mes articles et pages d'une langue à l'autre et sur un plugin qui, pour chaque contenu, scanne tous les autres contenus pour trouver ceux qui sont des traductions du contenu courant. Cette stratégie O(n²), bien que facile à mettre en œuvre, n'est pas efficace du tout et pénalise mes performances de compilation.

Ashwin Maroli, l'un des membres de la Jekyll Plugin Core Team, travaille sur un plugin qui utilise une convention d'organisation des fichiers pour trouver les traductions, ce qui devrait considérablement améliorer les choses : jekyll-locale. J'ai essayé d'implémenter le plugin sur mon blog mais j'ai rencontré quelques impondérables lors de cette première tentative. J'y reviendrai plus tard, une fois que j'aurais simplifié mon organisation des contenus. J'aurais également besoin que certains autres plugins soit modifiés pour être compatibles, comme jekyll-paginate-v2 de Sverrir Sigmundarson, qui me sert pour la pagination.

Je ne manquerai pas d'en parler quand j'attaquerai à nouveau ce chantier.

Protocole expérimental

Comme les optimisations ci-dessus nécessitent également de modifier le contenu, je n'ai pas effectué de benchmark en parallèle de l'implémentation itérative des optimisations. J'ai attendu d'avoir complètement terminé, et donc d'avoir le contenu final, puis j'ai repris ma configuration d'avant optimisation et j'ai analysé les gains étape par étape.

Voici mon protocole de test : Je suis parti d'une installation sans aucune de ces optimisations, puis j'ai écrit un script implémentant les optimisations une par une et compilant le site (sauf la suppression des inclusions, car… j'étais trop paresseux pour scripter la modification des gabarits, je l'avoue). J'ai ensuite programmé l'exécution du script 10 fois et je me suis couché pendant que mon ordinateur passait près de 16 heures à passer ces optimisations au banc d'essai.

Voici les données brutes, si certains veulent jouer avec :