{ "version": "https://jsonfeed.org/version/1.1", "title": "Jamstatic", "home_page_url": "https://jamstatic.fr/", "feed_url": "https://jamstatic.fr/feed.json", "description": "Jamstatic, la communauté des sites statiques et des architectures découplées.", "icon": "https://jamstatic.fr/favicon.7713e34cae9563a23ca4ae37c39f46d6.png", "favicon": "https://jamstatic.fr/thumbnails/64x/favicon.7713e34cae9563a23ca4ae37c39f46d6.png", "language": "fr", "items": [ { "id": "https://jamstatic.fr/2023/08/28/migration-site-cecil/", "url": "https://jamstatic.fr/2023/08/28/migration-site-cecil/", "title": "Pourquoi et comment j’ai migré Jamstatic.fr de Hugo vers Cecil", "summary": "Retour d’expérience sur la migration du site vers Cecil.", "date_published": "2022-08-28T00:00:00+00:00", "date_modified": "2026-01-28T00:00:00+00:00","content_text": "À la fin de l’année dernière j’avais entrepris de pérenniser le travail de refonte du site, engagé avec Frank : nouveau logo et nouvelle charte graphique, impliquant la modification des templates et de la feuille de styles.\nC’est la version sur laquelle vous lisez cette article 😊\nPour rappel, avant le site ressemblait à ça :\n\n\n\n\n\n\nCapture d’écran de la v1 de Jamstatic.fr\n\nPourquoi changer de solution ?\nAu 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.\nPuis, 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.\nBref, une perte de temps importante et une motivation se réduisant de jour en jour.\nJ’ai alors décidé de sauter le pas et de migrer vers Cecil, pour 2 raisons majeures :\n\nJe connais la solution sur le bout des doigts (et pour cause puisque j’en suis le créateur ^^) ;\nEt surtout je suis à l’aise, et donc efficace, avec le moteur de template Twig.\n\nComment ?\nAprès le \"pourquoi ?\" intéressons nous maintenant à la partie la plus intéressante de ce billet, à savoir le \"comment ?\" 😊\nLe 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 :\n\nJ’effectue une modification ;\nJe lance un nouveau build ;\nJ’effectue les ajustements nécessaires (en m’appuyant sur les messages d’erreur retournés) ;\nJe recommence jusqu’à ce que le build soit valide.\n\nGestion de contenu\nNous pouvons séparer les contenus en 2 catégories :\n\nLes pages, c’est à dire les articles rédigés dans le format Markdown\nLes assets, c’est à dire les illustrations et autres vidéos au sein des articles\n\nAussi, je me suis tout d’abord concentré sur la réorganisation de ces contenus :\n\nDéplacement des fichiers *.md du dossier content\/ de Hugo vers le dossier pages\/ de Cecil\nRenommage 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\nDéplacement des fichiers médias dans le dossier dédié de Cecil (asset\/)\n\nMise en forme et templates\nLe changement de moteur de templates aura certainement été le plus gros du travail, mais qui aura permis d’optimiser le rendu, via :\n\nLa rationalisation et la factorisation des templates de manière à ne pas\/plus dupliquer du code\nLa suppression des templates inutiles, c’est à dire disponibles en natif avec Cecil (tel que celui du flux RSS)\n\nDépendances et scripts\nCecil 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.\nDe 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.\nImage de partage\nL’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.\nMê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.\nDe plus le service de Cloudinary était sollicité à chaque affichage du post concerné, alors même que l’image n’était plus modifiée.\nAussi, j’ai délégué la construction de cette URL au template post\/page.html.twig :\n{% 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') %}\n{% set image = asset(cloudinary_url, {filename: 'cards\/%s.png'|format(page.id)}) %}\nEn pratique :\n\nCréation d’une image « modèle » (en veillant à garder de la place pour y intégrer le titre du billet)\nUtilisation de la fonction asset() pour manipuler l’image générée par Cloudinary :\nFormat automatique et qualité automatique\nDéfinition de la largeur maximum du texte avant retour à la ligne (1100 px) et positionnement du texte aux coordonnées 80:120\nUtilisation de la police de caractère Poppins 80 ultra bold interligne -30\nRemplacement des virgules présentes dans le titre par des espaces\nEncodage de l’URL obtenue\nEnfin, enregistrement de l’asset avec un nom de fichier \"slugifié\" afin d'être compatible avec les contraintes de nommage Windows, au format PNG\n\n\n\nExemple :\n\n\n\n\n\n\nExemple d’une Twitter Card\n\nConclusion\nPour 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.", "content_html": "

À la fin de l’année dernière j’avais entrepris de pérenniser le travail de refonte du site, engagé avec Frank : nouveau logo et nouvelle charte graphique, impliquant la modification des templates et de la feuille de styles.

\n

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

\n

Pour rappel, avant le site ressemblait à ça :

\n
\n\n\n\n\"Capture\n\n
Capture d’écran de la v1 de Jamstatic.fr
\n
\n

Pourquoi changer de solution ?

\n

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.
\nPuis, 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.
\nBref, une perte de temps importante et une motivation se réduisant de jour en jour.

\n

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

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

Comment ?

\n

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

\n

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 :

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

Gestion de contenu

\n

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

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

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

\n
    \n
  1. Déplacement des fichiers *.md du dossier content/ de Hugo vers le dossier pages/ de Cecil
    2. \n
  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. \n
  3. Déplacement des fichiers médias dans le dossier dédié de Cecil (asset/)
    4. \n
\n

Mise en forme et templates

\n

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

\n\n

Dépendances et scripts

\n

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.

\n

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.

\n

Image de partage

\n

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.

\n

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.

\n

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

\n

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

\n
{% 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') %}\n{% set image = asset(cloudinary_url, {filename: 'cards/%s.png'|format(page.id)}) %}
\n

En pratique :

\n\n

Exemple :

\n
\n\n\n\n\"Exemple\n\n
Exemple d’une Twitter Card
\n
\n

Conclusion

\n

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.

", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://arnaudligny.fr/blog/moteur-de-recherche-algolia-site-statique/", "url": "https://arnaudligny.fr/blog/moteur-de-recherche-algolia-site-statique/", "title": "Un moteur de recherche sur un site statique grâce à Algolia", "summary": "Comment j'ai implémenté une fonctionnalité de recherche à la documentation de Cecil.app.", "date_published": "2021-07-26T00:00:00+00:00","content_text": "Billet initialement publié sur le blog d’Arnaud Ligny.\nQuand 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.\n\n\n\n\n\n\nExemple de résultat de recherche\n\n\n\nQuelle solution technique ?\nGoogle CSE\nAlgolia\n\n\nÉtapes clefs\nCréer un index\nTransmettre l’index\nParamétrer l’index\n\n\nMise en œuvre\nCréation de l’index\nTransmission de l’index\n\n\nConclusion\n\nLa 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.\nAussi, 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.\n\n\n\n\n\n\nExemple de page de documentation\n\nQuelle solution technique ?\nGoogle CSE\nDans 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:).\nSi 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.\nAlgolia\nAussi, après plusieurs comparatifs, j’ai finalement retenu la solution Algolia pour les raisons suivantes :\n\nPertinence des résultats\nTarifs abordables (dont un plan gratuit)\nDocumentation riche\nNombreuses bibliothèques de code open source\n\nÉtapes clefs\nJe 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).\nCréer un index\nAlgolia 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.\nCet 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.\nTransmettre l’index\nAlgolia propose plusieurs méthodes afin de transmettre ou de mettre à jour l’index :\n\nà la main, via le dashboard, en uploadant le fichier JSON\nen ligne de command, via Algolia CLI\nprogrammatiquement, en PHP, en JavaScript, etc.\n\nParamétrer l’index\nLe 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.\nJe dis relativement car il peut être nécessaire d’effectuer quelques tests avant de maitriser les règles de priorisation des résultats.\n\n\n\n\n\n\nDashboard Algolia\n\nMise en œuvre\nDans le cas de la documentation de Cecil, il faut donc :\n\ncréer un fichier d’index au format JSON\nle transmettre à application Algolia\nafficher un champs de recherche avec auto-complétion\n\nCréation de l’index\nAvec 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 😊\nAinsi, l’objectif est de :\n\ncollecter le contenu des pages de la documentation (fichiers au format Markdown dans pages\/documentation), converti en HTML\ndé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\ngénérer un fichier algolia.json grâce aux formats de sortie\n\nRésultat cible\nLe fichier d’index va ressembler à ça :\n[\n {\n \"objectID\": \"documentation\/quick-start#download-cecil\",\n \"page\": \"Quick Start\",\n \"title\": \"Download Cecil\",\n \"description\": \"Download cecil.phar from your terminal:\",\n \"content\": \"...\",\n \"date\": \"2020-12-19T00:00:00+00:00\",\n \"href\": \"documentation\/quick-start\/#download-cecil\"\n },\n ...\n]\nCréation du template\nComme 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.\nS’agissant de rechercher dans la documentation, j’aurais pu créer ce template dans le dossier « documentation » (layouts\/documentation\/list.algolia.twig).\nMais 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.\nAinsi, au sein du template, il suffit de boucler sur les contenus de la section « documentation », à l’aide du tag for :\n{% for p in site.pages|filter(p => p.section == 'documentation')|sort_by_weight %}\n...\n{% endfor %}\nEnsuite, 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 :\n{% set sections = p.content|preg_split('\/<h3[^>]*>\/') %}\n\nLe 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.\n\nDe 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 » :\n{\n \"objectID\": \"Un ID unique\",\n \"page\": \"Le nom de la page de documentation\",\n \"title\": \"Le titre de section\",\n \"description\": \"Le premier paragraphe de la section (utilisé pour illustrer l’aperçu des résiltats)\",\n \"content\": \"Le contenu de la section, dans laquelle la recherche est effectuée\",\n \"date\": \"La date de la page, utilisée pour pondérer les résultats\",\n \"href\": \"Le lien vers la page de la documentation, combinée à une ancre afin d’emmener l’internaute à la bonne section\",\n}\n\nVoir le template complet sur GitHub.\n\nAssocier ce template à un format de sortie\nEn 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 😅\nPour régler ce soucis il suffit de compléter la configuration de la manière suivante :\noutput:\n formats:\n - name: algolia\n mediatype: 'application\/json'\n filename: 'algolia'\n extension: 'json'\n pagetypeformats:\n homepage: ['html', 'atom', 'algolia']\nMaintenant Cecil sait que :\n\nLes pages dont la variable format a pour valeur le nom du format « algolia » peuvent utiliser un template de la forme <layout>.algolia.twig\nEnregistrer le fichier généré sous filename.extension, soit « algolia.json »\nLa 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 »)\n\nEt voilà, l’index est maintenant généré et disponible à la racine du site généré : https:\/\/cecil.app\/algolia.json.\nTransmission de l’index\nComme indiqué précédemment, Algolia offre plusieurs méthodes d’envoi de l’index.\nDans 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.\nJ’ai ensuite cherché à automatisé cette procédure, et j’ai donc opté pour le client d’API JavaScript.\nCecil.app étant hébergé par Netlify, j’ai utilisé un plugin pour me simplifier la mise en oeuvre : Algolia Index Refresh Build Plugin :\n[[context.production.plugins]]\n package = \"netlify-plugin-refresh-algolia\"\n [context.production.plugins.inputs]\n appId = \"APP_ID\"\n indexName = \"INDEX\"\n filePath = \"_site\/algolia.json\"\nFormulaire de recherche\n\n\n\n\n\n\nExemple de résultat de recherche\n\nLa mise en œuvre est relativement simple :\n\nintégrer un champ de saisi (élément input)\nlui associer la bibliothèque Autocomplete.js\n\nChamp de saisie :\n<input type=\"text\" id=\"search-input\" placeholder=\"{% trans %}Search the Docs [Alt+S]{% endtrans %}\" accesskey=\"s\" \/>\nAutocomplete.js :\n\/\/ client Algolia\nvar client = algoliasearch('APP_ID', 'API_KEY');\n\/\/ index dans lequel rechercher\nvar index = client.initIndex('INDEX');\n\/\/ fonction de recherche\nfunction newHitsSource(index, params) {\n return function doSearch(query, cb) {\n index\n .search(query, params)\n .then(function(res) {\n cb(res.hits, res);\n })\n .catch(function(err) {\n console.error(err);\n cb([]);\n });\n };\n}\n\/\/ association de la lib au champ \"search-input\"\nautocomplete('#search-input', { hint: false }, [\n {\n source: newHitsSource(index, {\n \/\/ paramètres de mise en valeur des résultats suggérés\n hitsPerPage: 4,\n attributesToHighlight: ['description', 'page', 'title'],\n highlightPreTag: '<strong>',\n highlightPostTag: '<\/strong>',\n attributesToSnippet: ['description:25'],\n snippetEllipsisText: '…'\n }),\n \/\/ clef d'affichage principale (ici le titre de la section)\n displayKey: 'title'\n }\n]).on('autocomplete:selected', function(event, suggestion, dataset, context) {\n \/\/ au clic sur une suggestion on envoie l'internaute vers la page#ancre correspondante\n window.location.href = '{{ url() }}' + suggestion.href;\n});\n\nVoir le template complet sur GitHub.\n\nEt voilà ! 🎉\nNotes :\n\nIl s’agit ici de la version 0 de Autocomplete.js qui reste fonctionnelle mais commence à vieillir\nLa 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…\n\nConclusion\nJe 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.\nPour tester, ça se passe par ici : https:\/\/cecil.app\/documentation\/", "content_html": "\n

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.

\n
\n\n\n\n\"Exemple\n\n
Exemple de résultat de recherche
\n
\n\n
\n

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.

\n

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.

\n
\n\n\n\n\"Exemple\n\n
Exemple de page de documentation
\n
\n

Quelle solution technique ?

\n

Google CSE

\n

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:).
\nSi 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.

\n

Algolia

\n

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

\n\n

Étapes clefs

\n

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).

\n

Créer un index

\n

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.

\n

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.

\n

Transmettre l’index

\n

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

\n\n

Paramétrer l’index

\n

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.

\n

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

\n
\n\n\n\n\"Dashboard\n\n
Dashboard Algolia
\n
\n

Mise en œuvre

\n

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

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

Création de l’index

\n

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 😊

\n

Ainsi, l’objectif est de :

\n
    \n
  1. collecter le contenu des pages de la documentation (fichiers au format Markdown dans pages/documentation), converti en HTML
    2. \n
  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. \n
  3. générer un fichier algolia.json grâce aux formats de sortie
    4. \n
\n

Résultat cible

\n

Le fichier d’index va ressembler à ça :

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

Création du template

\n

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.

\n

S’agissant de rechercher dans la documentation, j’aurais pu créer ce template dans le dossier « documentation » (layouts/documentation/list.algolia.twig).
\nMais 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.

\n

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

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

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 :

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

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.

\n
\n

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 » :

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

Voir le template complet sur GitHub.

\n
\n

Associer ce template à un format de sortie

\n

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 😅

\n

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

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

Maintenant Cecil sait que :

\n
    \n
  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. \n
  2. Enregistrer le fichier généré sous filename.extension, soit « algolia.json »
    3. \n
  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 »)
    4. \n
\n

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

\n

Transmission de l’index

\n

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

\n

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.

\n

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

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

Formulaire de recherche

\n
\n\n\n\n\"Exemple\n\n
Exemple de résultat de recherche
\n
\n

La mise en œuvre est relativement simple :

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

Champ de saisie :

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

Autocomplete.js :

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

Voir le template complet sur GitHub.

\n
\n

Et voilà ! 🎉

\n

Notes :

\n
    \n
  1. Il s’agit ici de la version 0 de Autocomplete.js qui reste fonctionnelle mais commence à vieillir
    2. \n
  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…
    3. \n
\n

Conclusion

\n

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.

\n

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

", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://arnaudligny.fr/blog/generer-et-heberger-un-site-statique-avec-github/", "url": "https://arnaudligny.fr/blog/generer-et-heberger-un-site-statique-avec-github/", "title": "Générer et héberger un site web statique avec GitHub", "summary": "Dans cet article j’explique comment mettre en pratique GitHub Pages et GitHub Actions, en utilisant Cecil comme générateur de site statique.", "date_published": "2021-06-29T00:00:00+00:00","content_text": "Billet initialement publié sur le blog d’Arnaud Ligny.\nGitHub 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.\nDans cet article j’explique comment mettre en pratique GitHub Pages et GitHub Actions, en utilisant Cecil comme générateur de site statique.\n\n\nQu’est-ce que GitHub Pages ?\nQu’est-ce que GitHub Actions ?\nEn pratique, comment faire ?\nCréation du workflow\nDéfinition des tâches et des étapes\nParamétrage de GitHub Pages\n\n\n\nQu’est-ce que GitHub Pages ?\n\n\n\n\n\nGitHub Pages est une solution d’hébergement de pages web statiques permettant de créer rapidement un site web associé à un projet GitHub.\\\nHistoriquement, 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).\nAujourd’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.\nGitHub 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 :\n\nChoix de la branche (et du dossier : racine ou \/docs) à utiliser\nPossibilité de choisir un domaine personnalisé (via un enregistrement CNAME)\nActivation de HTTPS\n\nComme 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 ! 😀\nQu’est-ce que GitHub Actions ?\n\n\n\n\n\nGitHub Actions est la solution de GitHub pour automatiser des workflows de type intégration ou déploiement continue.\nLe principe est très proche de ce que propose des outils comme Jenkins, Travis CI ou encore GitLab CI.\nEn 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).\nCe 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.\nEn pratique, comment faire ?\nLe principe semble simple mais, en pratique, est-ce que c’est aussi facile à mettre en œuvre ?\\\nLa réponse est oui bien sûr ! 😀\nComme 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.\nCréation du workflow\nLes 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 :\n.github\/workflows\/\nDe 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.\nDéfinition des tâches et des étapes\nAvant de définir les tâches il est nécessaire de déterminer l’évènement déclencheur :\non:\n push:\n branches:\n - master\nIci 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).\nEn pratique nous devons définir 2 tâches (jobs) :\n1. build : génération du site statique\nC’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 :\n\nObtention du code source via checkout\nGénération du site via Cecil-Action\n« Mise de côté » des fichiers générés via upload-artifact\n\n\nNote : la directive with permet de passer des options à l’action.\n\nbuild:\n name: Build\n # Utilisation d'une image Linux Ubuntu\n runs-on: ubuntu-latest\n steps:\n\n - name: Checkout source\n uses: actions\/checkout@v2\n with:\n # Inutile de récupérer tout l'historique : la dernière version suffit\n fetch-depth: 1\n\n - name: Build site with Cecil\n uses: Cecilapp\/Cecil-Action@v3\n with:\n # Pour éviter les conflits, utilisation d'un nom spécifique\n config: 'cecil.yml'\n\n - name: Upload site to Artifacts\n uses: actions\/upload-artifact@v2\n with:\n name: _site\n path: _site\n # La tâche ne sera pas exécutée si aucun fichier n'est généré\n if-no-files-found: error\n2. deploy : déploiement des fichiers générés\n\nRécupération des fichiers générés via download-artifact\nDéploiement du site via GitHub-Pages-deploy\n\ndeploy:\n name: Deploy\n # La tâche 'deploy' est exécutée après la tâche 'build'\n needs: build\n runs-on: ubuntu-latest\n steps:\n\n - name: Download site from Artifacts\n uses: actions\/download-artifact@v2\n with:\n name: _site\n path: _site\n\n - name: Deploy site to GitHub Pages\n uses: Cecilapp\/GitHub-Pages-deploy@v3\n env:\n # Accès en écriture à la branche cible (`gh-pages`)\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n with:\n # Adresse e-mail valide sur GitHub\n email: arnaud@ligny.org\n\nNote : par défaut GitHub-Pages-deploy utilise le dossier _site comme source et le déploie dans la branche gh-pages.\n\nParamétrage de GitHub Pages\nEnfin, il reste à activer GitHub Pages au sein du dépôt via Settings > Pages.\n\n\n\n\n\n\nSélectionner la branche cible gh-pages (ainsi que le dossier \/)\nPuis le domaine (si vous souhaitez le personnaliser)\nEt enfin activer HTTPS (si le domaine de référence est personnalisé)\n\n\n\n\n\n\nEt voilà comment générer et déployer automatiquement un site web statique, hébergé gratuitement ! 🎉\nRemarques :\n\nDans cet article j’ai utilisé Cecil Action mais j’aurais également pu effectuer la même démonstration avec une action Hugo ou Eleventy ;\nSi vous souhaitez tester par vous même, en moins d’une minute, je vous invite à essayer avec le template Single-GitHub-Page.\n", "content_html": "\n

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.

\n

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

\n\n
\n

Qu’est-ce que GitHub Pages ?

\n\n\n\n\"GitHub\n\n

GitHub Pages est une solution d’hébergement de pages web statiques permettant de créer rapidement un site web associé à un projet GitHub.\\\nHistoriquement, 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).

\n

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.

\n

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 :

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

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 ! 😀

\n

Qu’est-ce que GitHub Actions ?

\n\n\n\n\"GitHub\n\n

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

\n

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

\n

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).

\n

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.

\n

En pratique, comment faire ?

\n

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

\n

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.

\n

Création du workflow

\n

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 :

\n
.github/workflows/
\n

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.

\n

Définition des tâches et des étapes

\n

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

\n
on:\n  push:\n    branches:\n    - master
\n

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).

\n

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

\n

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

\n

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 :

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

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

\n
\n
build:\n  name: Build\n  # Utilisation d'une image Linux Ubuntu\n  runs-on: ubuntu-latest\n  steps:\n\n  - name: Checkout source\n    uses: actions/checkout@v2\n    with:\n      # Inutile de récupérer tout l'historique : la dernière version suffit\n      fetch-depth: 1\n\n  - name: Build site with Cecil\n    uses: Cecilapp/Cecil-Action@v3\n    with:\n      # Pour éviter les conflits, utilisation d'un nom spécifique\n      config: 'cecil.yml'\n\n  - name: Upload site to Artifacts\n    uses: actions/upload-artifact@v2\n    with:\n      name: _site\n      path: _site\n      # La tâche ne sera pas exécutée si aucun fichier n'est généré\n      if-no-files-found: error
\n

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

\n
    \n
  1. Récupération des fichiers générés via download-artifact
    2. \n
  2. Déploiement du site via GitHub-Pages-deploy
    3. \n
\n
deploy:\n  name: Deploy\n  # La tâche 'deploy' est exécutée après la tâche 'build'\n  needs: build\n  runs-on: ubuntu-latest\n  steps:\n\n  - name: Download site from Artifacts\n    uses: actions/download-artifact@v2\n    with:\n      name: _site\n      path: _site\n\n  - name: Deploy site to GitHub Pages\n    uses: Cecilapp/GitHub-Pages-deploy@v3\n    env:\n      # Accès en écriture à la branche cible (`gh-pages`)\n      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n    with:\n      # Adresse e-mail valide sur GitHub\n      email: arnaud@ligny.org
\n
\n

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

\n
\n

Paramétrage de GitHub Pages

\n

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

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

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

\n

Remarques :

\n", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://arnaudligny.fr/blog/un-site-e-commerce-avec-cecil-et-snipcart/", "url": "https://arnaudligny.fr/blog/un-site-e-commerce-avec-cecil-et-snipcart/", "title": "Créer un site e-commerce avec Cecil et Snipcart", "summary": "Comment créer un site e-commerce statique performant et peu couteux grâce à Cecil et Snipcart.", "date_published": "2021-06-24T00:00:00+00:00","content_text": "Billet initialement publié sur le blog d’Arnaud Ligny.\nEn 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.\nElle 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.\nNé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.\nJe 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.\n\n\nPourquoi un site statique ?\nPourquoi Snipcart ?\nMise en œuvre\nCréation du catalogue\nTemplates et intégration Snipcart\nPersonnalisation du tunnel d’achat\n\n\nGestion de contenu (CMS)\nConclusion\n\nPourquoi un site statique ?\nJe suis un fervent promoteur de l’approche statique pour la diffusion de sites web de contenu pour les raisons suivantes (entre autres) :\n\nPerformance : une fois généré, le site n’a pas plus besoin d’être interprété par le serveur, juste d’être servi ;\nSimplicité : pas de base de données à maintenir car les données sont stockées dans des fichiers plats (Markdown + YAML) ;\nPortabilité : peut être hébergé sur n’importe serveur web et peut donc être migré facilement selon les besoins.\n\nDans le cas de ce projet j’ai donc utilisé mon propre générateur de site statique : Cecil.\nPourquoi Snipcart ?\nSnipcart n’est pas une solution e-commerce clef en main mais plutôt un « checkout » (tunnel d’achat) à ajouter à n’importe quel site web.\nIl 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.\nLe 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.\nIntérêt de cette approche et de Snipcart en particulier :\n\nIndépendance concernant la gestion du catalogue ;\nPeu ou pas de développement spécifique, principalement de la personnalisation ;\nTarif honnête (2% des ventes) ;\nSécurisation des transactions portée par la solution de paiement (ici Stripe).\n\nMise en œuvre\nCréation du catalogue\nLe 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).\nEn pratique nous avons 6 modèles composés d’1 variant « format ».\nLes attributs et le texte de la fiche produit sont définis dans un fichier Markdown (avec un « front matter ») :\npages\/products\n|_ index.md\n|_ 1.pink-gravel.md\n|_ 2.purple-cargo.md\n|_ 3.yellow-longtail.md\n|_ 4.blue-folding-bike.md\n|_ 5.ultra-violet-gang.md\n|_ 6.lemon-lovers.md\nLes 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.\nLes attributs sont définis via des variables au format YAML :\n---\ncascade:\n price: 23\n variants:\n - name: Format\n options:\n - value: A3\n html: \"Affiche A3 - 23 €\"\n price: 0\n - value: A5\n html: \"Carte A5 - 8 €\"\n price: -15\n---\nJ’ai utilisé la variable spéciale cascade qui permet de faire hériter à toutes pages de la section les variables qu’elle contient :\n\nprice : le prix de référence\nvariants : qui caractérise les déclinaisons pour chacun des produits, en l’occurrence le format d’impression\noptions :\nvalue : la valeur du format (ex : « A3 »)\nhtml : le texte affiché dans la liste déroulante\nprice : le prix modifié par rapport au prix de référence (qui peut être négatif)\n\n\n\n\n\nEnsuite chacun des produits est caractérisé via son propre fichier Markdown, par exemple pages\/products\/1.pink-gravel.md :\n---\ntitle: \"Pink gravel\"\ndescription: \"Femme ridant en toute liberté au pieds des montagnes.\"\nname: \"#01 Pink gravel\"\nimage: \"\/images\/products\/01-Pink-gravel-A3_S.png\"\ngallery:\n- \"\/images\/products\/01-Pink-gravel-A5_S.png\"\n- \"\/images\/products\/01-Pink-gravel-ZOOM_S.png\"\npublished: true\n---\n**Gavarnie, Hautes-Pyrénées.** \n**Femme ridant en toute liberté au pieds des montagnes.**\n\n_Impression numérique sans bordure sur papier couché premium semi mat 200 g (carte A5 300 g). \nLes affiches sont toutes signées à la main._\nTemplates et intégration Snipcart\nListe des produits\nLa 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.\nAinsi 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) :\n{% extends 'page.html.twig' %}\n\n{% block content %}\n<div class=\"hero\">\n {{~ page.content ~}}\n<\/div>\n<div class=\"products\">\n {%- for product in site.pages.all|filter_by('section', 'products')|sort_by_weight|reverse ~%}\n {%~ include 'components\/product.html.twig' with {'product': product, 'home': true} only ~%}\n {%- endfor ~%}\n<\/div>\n{% endblock %}\nFiche produit\nLa fiche produit (un composant Twig réutilisable) va afficher :\n\nLes informations : nom, description, photos, etc.\nLe choix du format (options du variant format), la saisie de la quantité souhaitée et le bouton « Ajouter au panier »\n\nConcentrons nous sur le cœur de la fiche produit, à savoir l’ajout au panier :\n\n\n\n\n\n\nFormulaire d’ajout au panier\n\n<div class=\"product__details\">\n {%- if product.variants is defined ~%}\n <div>\n {%- for variant in product.variants ~%}\n {%- if variant.options is defined ~%}\n <label for=\"{{ productId }}-{{ variant.name|lower }}\">{{ variant.name }}<\/label>\n <select id=\"{{ productId }}-{{ variant.name|lower }}\" class=\"{{ variant.name|lower }}\">\n {%- for option in variant.options ~%}\n <option value=\"{{ option.value }}\">{{ option.html }}<\/option>\n {%- endfor ~%}\n <\/select>\n {%- endif ~%}\n {%- endfor ~%}\n <\/div>\n {%- endif ~%}\n <div>\n <label for=\"{{ productId }}-qty\">Quantité<\/label>\n <input type=\"number\" id=\"{{ productId }}-qty\" class=\"qty\" min=\"1\" max=\"10\" value=\"1\" \/>\n <\/div>\n {%~ include 'components\/add-item.html.twig' with {'productId':productId,'product':product} only ~%}\n<\/div>\nCette portion du template layouts\/components\/product.html.twig est composée de 3 parties :\n\nLa 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) ;\nLe champ de saisi de la quantité ;\nLe bouton d’ajout au panier (représenté par le composant add-item.html.twig).\n\nC’est le composant bouton qui porte les attributs permettant l’ajout du produit au panier Snipcart.\nIntégration Snipcart\nL’intégration de Snipcart est simple, et nécessite :\n\nLa feuille de style de référence ;\nUn ou plusieurs boutons d’ajout au panier, portant les attributs du produit : identifiant, URL, nom, prix, etc. ;\nUne balise <div> invisible (permettant affichage du panier) portant la clef d’API Snipcart ;\nL’applicatif à proprement parlé via un fichier JavaScript.\n\n<link rel=\"stylesheet\" href=\"https:\/\/cdn.snipcart.com\/themes\/v3.0.11\/default\/snipcart.css\" \/>\n\n<button class=\"snipcart-add-item\"\n data-item-id=\"product-1\"\n data-item-url=\"\/\"\n data-item-name=\"Product #1\"\n data-item-price=\"10.99\"\n>Add to cart<\/button>\n\n<div hidden id=\"snipcart\" data-api-key=\"MzMxN2Y0ODMtOWNhMy00YzUzLWFiNTYtZjMwZTRkZDcxYzM4\"><\/div>\n\n<script src=\"https:\/\/cdn.snipcart.com\/themes\/v3.0.11\/default\/snipcart.js\"><\/script>\n\nDémo : https:\/\/codepen.io\/thatfrankdev\/pen\/xxwRXQw?editors=1000\nTemplate de Paysages à vélo : layouts\/components\/add-item.html.twig\n\nPersonnalisation du tunnel d’achat\nJ’ai également pris le temps de personnaliser le tunnel d’achat à la fois au niveau du rendu graphique et des étapes.\n\n\n\n\n\n\nExemple de panier\n\nPersonnalisation du rendu\nConcernant 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.\nPar exemple, pour remplacer la police de caractère :\n.snipcart {\n font-family: 'Roboto Condensed', sans-serif;\n}\nLa feuille de style Sass de Paysages à vélo disponible sur GitHub.\n\nRemarque : depuis la version 3.2, Snipcart a introduit la notion de « Theming » qui facilite grandement la personnalisation via des propriétés CSS.\n\nPersonnalisation des textes\nLes 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 :\ndocument.addEventListener('snipcart.ready', function() {\n fetch('\/snipcart\/{{ language }}.json')\n .then(response => response.json())\n .then(translation => Snipcart.api.session.setLanguage('{{ language }}', translation))\n});\nPersonnalisation des formulaires\nSnipcart permet également de modifier et d’enrichir les étapes du tunnel d’achat via des templates Vue.js :\n<div hidden id=\"snipcart\" data-api-key=\"{{ site.snipcart.apikey }}\" data-templates-url=\"\/snipcart\/templates.tpl\"><\/div>\nAinsi, dans le cas de Paysages à vélo j’ai :\n\nModifié l’affichage des lignes du panier afin d’y indiquer le format d’impression sélectionné à côté du nom du produit ;\nDésactivé la suggestion d’adresse (qui n’est pas très fiable sur le territoire français) ;\nAjouté un champ de saisi d’un message cadeau.\n\nPar exemple, dans le cas du champ de saisi du message cadeau, le code ressemble à ça :\n<shipping-address section=\"bottom\">\n <fieldset class=\"snipcart-form__set\">\n <hr class=\"snipcart-form__separator\" \/>\n <!-- Gift message -->\n <div class=\"snipcart-form__field\">\n <snipcart-label class=\"snipcart__font--tiny\" for=\"Message cadeau\">Message cadeau<\/snipcart-label>\n <snipcart-input name=\"Message cadeau\"><\/snipcart-input>\n <p class=\"snipcart__font--tiny snipcart-form__footer\">\n (Votre message sera écrit à la main sur une carte, ajoutée au colis)\n <\/p>\n <\/div>\n <\/fieldset>\n<\/shipping-address>\n\nSi vous voulez en voir plus le code source est disponible sur GitHub.\n\nGestion de contenu (CMS)\nLa 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.\nNé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.\nDe plus Forestry offre un fonctionnalité de prévisualisation, en contexte, très efficace !\n\n\n\nDémo Forestry\n\nConclusion\nJ’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).\nEt 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 ! 🛒😊\nEnfin, je vous invite à :\n\nÉtudier le code source du projet si vous souhaitez en savoir plus et vous inspirer ;\nJeter un œil à mon générateur de site statique : Cecil ;\nConsulter le site officiel de Snipcart.\n", "content_html": "\n

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.

\n

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.
\nNé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.

\n

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.

\n\n
\n

Pourquoi un site statique ?

\n

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

\n\n

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

\n

Pourquoi Snipcart ?

\n

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.

\n

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.

\n

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.

\n

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

\n\n

Mise en œuvre

\n

Création du catalogue

\n

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).
\nEn pratique nous avons 6 modèles composés d’1 variant « format ».

\n

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

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

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.
\nLes attributs sont définis via des variables au format YAML :

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

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

\n\n

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

\n
---\ntitle: \"Pink gravel\"\ndescription: \"Femme ridant en toute liberté au pieds des montagnes.\"\nname: \"#01 Pink gravel\"\nimage: \"/images/products/01-Pink-gravel-A3_S.png\"\ngallery:\n- \"/images/products/01-Pink-gravel-A5_S.png\"\n- \"/images/products/01-Pink-gravel-ZOOM_S.png\"\npublished: true\n---\n**Gavarnie, Hautes-Pyrénées.**  \n**Femme ridant en toute liberté au pieds des montagnes.**\n\n_Impression numérique sans bordure sur papier couché premium semi mat 200 g (carte A5 300 g). \nLes affiches sont toutes signées à la main._
\n

Templates et intégration Snipcart

\n

Liste des produits

\n

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.

\n

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) :

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

Fiche produit

\n

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

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

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

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

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

\n
    \n
  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. \n
  2. Le champ de saisi de la quantité ;
    3. \n
  3. Le bouton d’ajout au panier (représenté par le composant add-item.html.twig).
    4. \n
\n

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

\n

Intégration Snipcart

\n

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

\n
    \n
  1. La feuille de style de référence ;
    2. \n
  2. Un ou plusieurs boutons d’ajout au panier, portant les attributs du produit : identifiant, URL, nom, prix, etc. ;
    3. \n
  3. Une balise <div> invisible (permettant affichage du panier) portant la clef d’API Snipcart ;
    4. \n
  4. L’applicatif à proprement parlé via un fichier JavaScript.
    5. \n
\n
<link rel=\"stylesheet\" href=\"https://cdn.snipcart.com/themes/v3.0.11/default/snipcart.css\" />\n\n<button class=\"snipcart-add-item\"\n  data-item-id=\"product-1\"\n  data-item-url=\"/\"\n  data-item-name=\"Product #1\"\n  data-item-price=\"10.99\"\n>Add to cart</button>\n\n<div hidden id=\"snipcart\" data-api-key=\"MzMxN2Y0ODMtOWNhMy00YzUzLWFiNTYtZjMwZTRkZDcxYzM4\"></div>\n\n<script src=\"https://cdn.snipcart.com/themes/v3.0.11/default/snipcart.js\"></script>
\n\n

Personnalisation du tunnel d’achat

\n

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

\n
\n\n\n\n\"Exemple\n\n
Exemple de panier
\n
\n

Personnalisation du rendu

\n

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.

\n

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

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

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

\n
\n

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

\n
\n

Personnalisation des textes

\n

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 :

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

Personnalisation des formulaires

\n

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

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

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

\n
    \n
  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. \n
  2. Désactivé la suggestion d’adresse (qui n’est pas très fiable sur le territoire français) ;
    3. \n
  3. Ajouté un champ de saisi d’un message cadeau.
    4. \n
\n

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

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

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

\n
\n

Gestion de contenu (CMS)

\n

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

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.

\n

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

\n\n

\n

\n

Conclusion

\n

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).

\n

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 ! 🛒😊

\n

Enfin, je vous invite à :

\n", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2021/03/09/11000-pages-statiques/", "url": "https://jamstatic.fr/2021/03/09/11000-pages-statiques/", "title": "Un site statique de 11 000 pages, c'est possible ?", "summary": "Les sites statiques pour un site de média c'est l'idéal. Rapide, léger, sécurisé, tout semble coller sur le papier. Mais est-il possible de créer un site statique avec un grand nombre de pages ?", "date_published": "2021-03-09T14:00:00+00:00","content_text": "Les sites statiques pour un site de média c'est l'idéal. Rapide, léger, sécurisé, tout semble coller sur le papier. Mais est-il possible de créer un site statique avec un grand nombre de pages ?\nLe contexte\nTout 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. \nAu 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.\nIl désire donc basculer une bonne partie des sites actuels sur des sites statiques. \nMais 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.\nChoix des générateurs et du CMS Headless\nCô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.\nLe 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.\nComme 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é.\nOn 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.\nGastby 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.\nPour être 100% honnête, cet article a mis de côté Gastby au profit de Next.js dès le départ.\nNext.js\nNext.js est un framework JavaScript basé sur React. Il permet de générer des applications React sous trois modes de rendu : SSR (rendu serveur), hybride (statique dynamique) et 100% statique (export des pages sous forme HTML).\nUniquement dans le mode hybride, il offre les fonctionnalités suivantes : le mode prévisualisation des pages non générées, la regénération statique incrémentale (la (re)génération de pages existantes ou non, sous forme de fichiers statiques).\nNuxt.js\nNuxt.js est un framework JavaScript basé sur Vue.js. Il permet de générer des applications Vue.js sous trois modes de rendu : SSR (rendu serveur), SPA (single page application) et 100% statique (export des pages HTML).\nIl propose également un système de prévisualisation, mais dans le mode 100% statique. À ce jour, il ne propose pas de système de génération de page dynamique comme Next.js.\nRien de confirmé pour le moment, mais la version 3.0 de Nuxt.js devrait proposer une fonctionnalité équivalente.\nCommençons avec Next.js\nNous 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.\nNé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.\nGénération des 11 000 pages et premier blocage\nDurant 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.\nIl 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.\nPour 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.\nTout fonctionne parfaitement. Les 11 000 pages prennent entre 5 et 8 minutes pour être créées.\nLa surprise ou le blocage qu'on attendait pas\nBon 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.\nMais là où nous avons été surpris, c'est quand nous avons testé le déploiement sur Vercel.\nUne 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 !\nClairement, 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 !\n\n\n\n\n\n\n39 minutes de temps de déploiement\n\nLe 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.\nLa régénération incrémentale à la rescousse\nC'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.\nOn 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.\nEnsuite, 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.\nRésultat, un temps de génération entre deux et quatre minutes pour un site statique hybride de 10 991 articles !\n\n\n\n\n\n\n10991 articles\n\n\n\n\n\n\n\n4 minutes de temps de déploiement\n\nCerise 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 !\n\n\n\nLa solution retenue\nBien 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.\nNous 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.\nDonc 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.\nL'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.\nFinalement, 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.\nPrototype privé\nLe projet est confidentiel et le code privé. Je ne peux pas fournir les données pour faire des tests.", "content_html": "

Les sites statiques pour un site de média c'est l'idéal. Rapide, léger, sécurisé, tout semble coller sur le papier. Mais est-il possible de créer un site statique avec un grand nombre de pages ?

\n

Le contexte

\n

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.

\n

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.
\nIl désire donc basculer une bonne partie des sites actuels sur des sites statiques.

\n

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.

\n

Choix des générateurs et du CMS Headless

\n

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.

\n

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.

\n

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é.
\nOn 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.

\n

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.

\n

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

\n\n\n

Commençons avec Next.js

\n

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

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.

\n

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

\n

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.

\n

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.

\n

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.
\nTout fonctionne parfaitement. Les 11 000 pages prennent entre 5 et 8 minutes pour être créées.

\n

La surprise ou le blocage qu'on attendait pas

\n

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.

\n

Mais là où nous avons été surpris, c'est quand nous avons testé le déploiement sur Vercel.
\nUne 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 !

\n

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 !

\n
\n\n\n\n\"39\n\n
39 minutes de temps de déploiement
\n
\n

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.

\n

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

\n

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.

\n

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.

\n

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.

\n

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

\n
\n\n\n\n\"10991\n\n
10991 articles
\n
\n
\n\n\n\n\"4\n\n
4 minutes de temps de déploiement
\n
\n

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 !

\n

\n\n

\n

La solution retenue

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

Prototype privé

\n

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

", "authors": [ { "name": "patrickF" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2020/12/08/hebergement-statique-en-france/", "url": "https://jamstatic.fr/2020/12/08/hebergement-statique-en-france/", "title": "Héberger du statique en France, avec Matthias Dugué et Hubert Sablonnière", "summary": "Quelles différences entre les plate-formes françaises et les géants américains du cloud quand il s’agit de déployer des sites Jamstack ?", "date_published": "2020-12-08T00:00:00+00:00", "date_modified": "2021-09-10T00:00:00+00:00","content_text": "Dans ce deuxième épisode de Génération Statique Frank Taillandier et Arnaud Ligny reçoivent Matthias Dugué, en charge des relations avec les développeurs chez Alwaysdata, et Hubert Sablonnière, développeur web chez Clever Cloud. Avec eux nous évoquons la différence entre les plate-formes françaises et les géants américains du Cloud, quand il s’agit de déployer des sites Jamstack.\n\nL’é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.\nLes 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.\nMatthias 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.\nL’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.\nIl 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.\nHubert 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.\nMatthias 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.\nIl 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.\nLes gros acteurs comme AWS ne sont pas non plus à l’abri de pannes, comme on a pu le voir encore recemment.\nChez 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.\nArnaud 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.\nCette 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.\nLes 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.\nLe 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.", "content_html": "

Dans ce deuxième épisode de Génération Statique Frank Taillandier et Arnaud Ligny reçoivent Matthias Dugué, en charge des relations avec les développeurs chez Alwaysdata, et Hubert Sablonnière, développeur web chez Clever Cloud. Avec eux nous évoquons la différence entre les plate-formes françaises et les géants américains du Cloud, quand il s’agit de déployer des sites Jamstack.

\n\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

\n

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

\n

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.

\n

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.

\n

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.

\n

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.

\n

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.

", "authors": [ { "name": "podcast" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2020/11/19/jamstack-legere-et-performante/", "url": "https://jamstatic.fr/2020/11/19/jamstack-legere-et-performante/", "title": "Vers une Jamstack légère et performante, avec Nicolas Goutay", "summary": "Passer de Gatsby à Eleventy afin de pouvoir concevoir un site web plus performant et accessible à tous.", "date_published": "2020-11-19T00:00:00+00:00","content_text": "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.\n\nIntroduction\nJamstatic 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.\nPrè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.\nBataille d'égo de CEO\nLa 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.\nL'API de WordPress pour le blog de Gatsby\nGatsby, 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.\nLes annonces de la première Next.js conf\nL’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.\nBeaucoup 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.\nCes 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.\n\n\n\n\n\n\nLe tableau de bord des métriques de performance utilisateur de Vercel affiche un score d'expérience réelle, ici pour les 3\/4 des utilisateurs de téléphone mobile sur un site généré avec Next.js.\n\nÉ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.\nDevant 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.\nGatsby simplifie la génération de pages\nGatsby 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.\nNuxt.js de plus en plus statique\nNuxt.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…\nLe 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.\nStocker 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.\nDes 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.\nHugo de mieux en mieux outillé pour le JavaScript\nEnfin 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.\nTailwind 2.0\nLa 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.\nEleventy en route vers le million de téléchargements\nDe 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.\nComment ne pas faire subir le coût des frameworks à ses visiteurs ?\nDans 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.\nNicolas 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.\nGatsby 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é.\nNicolas 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é.\nTout 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.\nEven 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\nOn 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.\nTout 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.\nMalgré 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.\nLes 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.\nLe 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é.\nLe 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.\n\nL'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\n\nMozilla adopte cette approche légère sur https:\/\/extensionworkshop.com\/.\nOn 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.\nIl est possible d'utiliser Vue avec Eleventy, c'est d'ailleurs ce qu'a fait Zach Leatherman sur netlify.com.\nLe statique moderne est toujours en plein évolution, beaucoup d'outils dans le seul but de produire des sites à la fois modernes, accessibles et performants.\nLa discussion continue sur Slack et Twitter…\nIntervenants\n\nFrank Taillandier, Customer Success Manager chez Forestry.io, initiateur de la communauté jamstatic.fr\nArnaud Ligny, consultant technique web & e-commerce, créateur du générateur de site statique Cecil\nNicolas Goutay, développeur web chez Orbit, organisateur des meetups Jamstack Paris, et de la conférence francophone We Love Speed\n", "content_html": "\n\n

Introduction

\n

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.

\n

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.

\n

Bataille d'égo de CEO

\n

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.

\n

L'API de WordPress pour le blog de Gatsby

\n

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.

\n

Les annonces de la première Next.js conf

\n

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.

\n

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.

\n

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.

\n
\n\n\n\n\"Le\n\n
Le tableau de bord des métriques de performance utilisateur de Vercel affiche un score d'expérience réelle, ici pour les 3/4 des utilisateurs de téléphone mobile sur un site généré avec Next.js.
\n
\n

É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.

\n

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.

\n

Gatsby simplifie la génération de pages

\n

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.

\n

Nuxt.js de plus en plus statique

\n

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…

\n

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.

\n

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.

\n

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.

\n

Hugo de mieux en mieux outillé pour le JavaScript

\n

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.

\n

Tailwind 2.0

\n

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.

\n

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

\n

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.

\n

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

\n

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.

\n

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.

\n

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é.

\n

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é.

\n

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.

\n

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
\n

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.

\n

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.

\n

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.

\n

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.

\n

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é.

\n

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.

\n
\n

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

\n
\n

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

\n

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.

\n

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

\n

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.

\n

La discussion continue sur Slack et Twitter…

\n

Intervenants

\n", "authors": [ { "name": "podcast" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2020/10/31/comparatif-performance-generateurs-de-site-statique/", "url": "https://jamstatic.fr/2020/10/31/comparatif-performance-generateurs-de-site-statique/", "title": "Comparaison des temps de compilation des générateurs de site statique", "summary": "Comment se comportent les principaux générateurs quand il s'agit de compiler 1, 1 000 ou 64 000 fichiers ?", "date_published": "2020-10-31T07:38:15+00:00", "date_modified": "2020-10-31T13:38:15+00:00","content_text": "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.\nJekyll 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.\nIl 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.\nJe 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.\n\n\n\n\n\n\nComparatif des principaux générateurs\n\nTous 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 ».\nIl 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.\nIl 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 !\nIl 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.\nLes tests\nLe 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 :\n\nEleventy\nGatsby\nHugo\nJekyll\nNext\nNuxt\n\nChaque test utilise l'approche et les conditions suivantes :\n\nLa 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.\nLe contenu ne contient pas d'images.\nLes 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.\nLa 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.\nChaque test est un essai à froid. Les caches sont effacés et les fichiers Markdown sont régénérés pour chaque test.\n\nCes 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.\nEn 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).\nPar 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é).\nOn 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.\nLes deux types de générateurs de sites statiques\nAvant 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é.\n\nLes 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).\nLes 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.\n\nJ'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.\n\n\n\nGénérateurs Basiques\nGénérateurs Avancés\n\n\n\n\nEleventy\nGatsby\n\n\nHugo\nNext\n\n\nJekyll\nNuxt\n\n\n\nMon hypothèse\nAppliquons la méthode scientifique à cette approche car la science est amusante (et utile) !\nMon 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.\nPermettez-moi de développer un peu plus cette hypothèse.\nLinéaire et rapide\nHugo 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.\nLent, puis rapide, mais toujours lent\nLes 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.\nLes 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).\nMais, à 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.\nDans 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.\nJekyll : le vilain petit canard\nRuby 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.\nAu 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.\n\n\n\n\n\n\nLes résultats auxquels on pourrait s'attendre, Hugo le plus rapide et Next.js le plus lent\n\nLes résultats sont arrivés\nLe code de ces tests se trouve sur GitHub. Il y a aussi un site qui montre les résultats relatifs.\nAprè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 :\n\nBasique : Un seul fichier, pour comparer les temps de génération de base\nPetits 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)\nGrands 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.\n\n\n\n\n\n\n\nPerformance de base, Hugo est largement vainqueur\n\n\n\n\n\n\n\nGénération sur des petits sites (< 1024 fichiers) : Hugo est de loin le plus rapide, Gatsby devient plus lent dès 128 fichiers\n\n\n\n\n\n\n\nGénération de gros sites (entre 1000 et 64000 fichiers): Hugo est de loin le plus rapide, Gatsby est exponentiellement plus lent\n\nSynthèse des résultats\nCertains résultats m'ont surpris, alors que d'autres étaient prévisibles. Voici les points les plus importants :\n\nComme 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.)\nLes 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.\nAucun 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.\nJe 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.\nBien 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.\n\nQu'en conclure ?\nLorsque 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 :\n\nLes 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.\n\nNous sommes d'accord.\nPour résumer : La mise à l'échelle des sites Jamstack est difficile.\nLes 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.\nCe qui compte vraiment, c'est votre niveau de tolérance à l'attente en échange de l'expérience de développement.\nPar 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.\nAu 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.\nDe 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.\nEn 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.\nConclusion\nCe 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.\nQuelles 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 ?\nVoilà les questions auxquelles j'aimerais que vous m'aidiez à répondre. Parlons-en.", "content_html": "\n

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.

\n

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.

\n
\n\n\n\n\"Comparatif\n\n
Comparatif des principaux générateurs
\n
\n

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 ».

\n

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.

\n

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 !

\n

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.

\n

Les tests

\n

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 :

\n\n

Chaque test utilise l'approche et les conditions suivantes :

\n\n

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.

\n

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).

\n

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é).

\n

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.

\n

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

\n

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é.

\n\n

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.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Générateurs BasiquesGénérateurs Avancés
EleventyGatsby
HugoNext
JekyllNuxt
\n

Mon hypothèse

\n

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

\n

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.

\n

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

\n

Linéaire et rapide

\n

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.

\n

Lent, puis rapide, mais toujours lent

\n

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.

\n

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).

\n

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.

\n

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.

\n

Jekyll : le vilain petit canard

\n

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.

\n

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.

\n
\n\n\n\n\"Les\n\n
Les résultats auxquels on pourrait s'attendre, Hugo le plus rapide et Next.js le plus lent
\n
\n

Les résultats sont arrivés

\n

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

\n

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 :

\n\n
\n\n\n\n\"Performance\n\n
Performance de base, Hugo est largement vainqueur
\n
\n
\n\n\n\n\"Génération\n\n
Génération sur des petits sites (< 1024 fichiers) : Hugo est de loin le plus rapide, Gatsby devient plus lent dès 128 fichiers
\n
\n
\n\n\n\n\"Génération\n\n
Génération de gros sites (entre 1000 et 64000 fichiers): Hugo est de loin le plus rapide, Gatsby est exponentiellement plus lent
\n
\n

Synthèse des résultats

\n

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

\n\n

Qu'en conclure ?

\n

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 :

\n
\n

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.

\n
\n

Nous sommes d'accord.

\n

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

\n

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.

\n

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

\n

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.

\n

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.

\n

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.

\n

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.

\n

Conclusion

\n

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.

\n

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 ?

\n

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

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2020/10/05/la-jamstack-n-est-rapide-que-si-vous-la-rendez-rapide/", "url": "https://jamstatic.fr/2020/10/05/la-jamstack-n-est-rapide-que-si-vous-la-rendez-rapide/", "title": "La Jamstack n'est rapide que si vous y veillez", "summary": "Pour en finir avec l'incompréhension selon laquelle votre site statique doit forcément utiliser du JavaScript et des APIs.", "date_published": "2020-10-05T00:00:00+00:00","content_text": "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 !\nLa 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 guide1 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.\nVous avez peut-être vu les diatribes fréquentes d'Alex Russell à propos de Gatsby :\nLooking 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\nGatsby 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.\nEleventy est très différent, comme Zach Leatherman nous le rappelle dans Eleventy’s New Performance Leaderboard :\n\nEleventy 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.\n\nLe 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.\nParfois, 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.\nPar 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.\nPrivilégier le côté serveur\nJe préfère le faire sur le serveur.\nCela permet :\n\nD'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.\nDe 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.\n\nCela 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.\nPar exemple :\n\nMon 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.\nPendant 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.\n\nUtiliser la génération côté serveur pour récupérer les Webmentions offre de multiples avantages :\n\nLa performance pour les utilisateurs est largement meilleure, avec du HTML déjà compilé sur le serveur et servi de manière statique.\nBeaucoup moins d’appels d’API, ce qui requiert beaucoup moins de temps de compilation et d’énergie.\nTout 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.\n\nAméliorer le côté client, s’il est indispensable\nSi 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.\nMais rappelez-vous que chaque JavaScript ajouté à la page a un coût, donc les quelques Webmentions supplémentaires doivent être vraiment utiles.\nAlors, au lieu de le faire pour chaque page vue :\n\nEssayez 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.\nGardez 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.\n\nLes appels à l’API uniquement côté client ont parfois plus de sens\nJe 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 :\n\nLes Webmentions à afficher sont les mêmes pour tous les visiteurs.\nNe pas générer les plus récentes n’est sûrement pas un problème.\n\nAlors 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.\nCe que je dis c’est que ça ne devrait pas être le cas par défaut.\nPromouvoir la AJMstack Mstack\nC’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).\nVoici pour l’exemple ce que vous pouvez voir sur jamstack.wtf (simplifié) :\n\n\nJamstack version aplatie\n\nComme suggéré par Yann, j’aimerais commencer par utiliser cette meilleure présentation :\n\n\nJamstack version empilée\n\nCela 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).\nMais j’aimerais suggérer cette modification :\n\n\nJavaScript fait la liaison\n\nBien sûr, cela se lit AJMstack au lieu de Jamstack, donc je parie que je n’aurais pas de succès dans la promotion… 🤷‍♂️\nMais au final ça semble plus adéquat, et cela montre que JavaScript fait le lien entre les APIs et le balisage.\nCela 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…\nVoici la Mstack :\n\n\nMstack\n\nAssurez-vous déjà que cette « couche » soit au top, et ensuite améliorez-la avec du JavaScript et des APIs au besoin.\n\n\n\n\nIl existe une version française de ce guide. ↩\n\n\n", "content_html": "\n

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 guide1 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.

\n

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

\n

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
\n

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.

\n

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

\n
\n

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.

\n
\n

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.

\n

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.

\n

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.

\n

Privilégier le côté serveur

\n

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

\n

Cela permet :

\n\n

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.

\n

Par exemple :

\n\n

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

\n\n

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

\n

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.

\n

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

\n

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

\n\n

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

\n

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 :

\n\n

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.

\n

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

\n

Promouvoir la AJMstack Mstack

\n

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).

\n

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

\n
\n\"Jamstack\n
Jamstack version aplatie
\n
\n

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

\n
\n\"Jamstack\n
Jamstack version empilée
\n
\n

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).

\n

Mais j’aimerais suggérer cette modification :

\n
\n\"JavaScript\n
JavaScript fait la liaison
\n
\n

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… 🤷‍♂️

\n

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

\n

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…

\n

Voici la Mstack :

\n
\n\"Mstack\"\n
Mstack
\n
\n

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

\n
\n
\n
    \n
  1. \n

    Il existe une version française de ce guide. ↩

    \n
    2. \n
\n
", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2020/09/05/tout-savoir-sur-les-modules-hugo/", "url": "https://jamstatic.fr/2020/09/05/tout-savoir-sur-les-modules-hugo/", "title": "Tout ce que vous devez savoir sur les modules Hugo", "summary": "Les modules Hugo permettent d'utiliser des fichiers stockés dans n'importe quel dépôt Git dans vos projets.", "date_published": "2020-09-05T11:55:22+00:00", "date_modified": "2020-09-05T11:55:22+00:00","content_text": "Les modules Hugo, apparus dans la version 0.56.0, ajoutent un puissant système de dépendances dont vous auriez tort de vous passer. Ils permettent de rappatrier des fichiers stockés dans des dépôts Git dans vos projets. Les cas d'utilisation vont du simple usage d'un thème complet, à celui de sélection de composants de thèmes distants, comme des icônes, ou au partage de composants réutilisables (modèles, fichiers partiels, shortcodes, etc.) entre plusieurs projets.\nCet 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!\nInitialiser votre projet en tant que module\nTout est module\nIl est important de comprendre qu'avant d'importer un module Hugo, votre projet doit lui même être un module !\nPour initialiser votre projet en tant que module, vous devez faire reférence à une URL de dépôt Git.\nPartons du principe que votre projet Hugo est déjà sur GitHub à l'adresse https:\/\/github.com\/chez-moi\/mon-depot.\nDans un terminal, à la racine de votre projet, lancez :\nhugo mod init github.com\/chez-moi\/mon-depot\n☝️ Cette commande génère un fichier go.mod à la racine du projet. Il ressemble à quelque chose comme :\nmodule github.com\/chez-moi\/mon-depot\n\ngo 1.15\nUn fichier go.sum est également généré, mais ne nous en préoccupons pas pour le moment.\nImporter un dépôt distant\nPrenons 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.\nLa déclaration se fait dans votre fichier de configuration à l'aide du mot clé module et de sa liste d'imports:\nmodule:\n imports:\n - path: github.com\/twbs\/icons\nMaintenant lancez la commande hugo et vous pouvez remarquer que le fichier go.mod comporte une nouvelle ligne:\nmodule github.com\/chez-moi\/mon-depot\n\ngo 1.15\n\nrequire github.com\/twbs\/icons v1.0.0 \/\/ indirect\nC'est bien, mais cela ne dit pas à Hugo ce qu'il doit faire de ces fichiers.\nGrâce à la clé mounts, relative à notre import de Bootstrap, donnons plus de directives à Hugo :\nmodule:\n imports:\n - path: github.com\/twbs\/bootstrap\n mounts:\n - source: icons\n target: assets\/icons\nComme pour les imports, on peut utiliser plusieurs mounts, pour le moment nous contenterons d'un seul avec les paramètres suivants:\n\nle 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.\nle paramètre target désigne l'endroit où Hugo doit monter les fichiers dans notre systéme de fichier Hugo unifié.\n\nUne 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 :\n{{ with resources.Get \"icons\/cart.svg\" }}\n <div class=\"w-4 fill-current\">\n {{ .Content | safeHTML }}\n <\/div>\n{{ end }}\nEt voilà !\nNous pouvons afficher cette icône de panier SVG sans avoir à la recopier dans notre projet.\nDans l'éventualité où vous voulez personnaliser cette icône de panier nous pouvons compter sur le système de fichiers unifié d'Hugo !\nTout 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.\nOu si nous voulions, nous pourrions aussi importer le fichier d'un autre dépôt distant pour une simple icône 🤪 :\n- path: github.com\/refactoringui\/heroicons\n mounts:\n - source: src\/solid\/shopping-cart.svg\n target: assets\/icons\/cart.svg\n- path: github.com\/twbs\/icons\n mounts:\n - source: icons\n target: assets\/icons\n☝️ Ici nous importons deux dépôts, chacun avec son propre point de montage.\nPeu importe le nombre de fichiers montés, Hugo téléchargera quand même l'intégralité du dépôt, donc pensez-y à deux fois avant d'importer un dépôt de plusieurs MB pour un simple fichier SVG.\nMise à jour\nEt 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.\nSi github.com\/twbs\/icons sort une version v1.1.0 et que vous souhaitez faire la mise à jour :\nhugo mod get -u github.com\/twbs\/bootstrap\nCette commande mettra votre fichier go.mod à jour avec la dernière version publiée.\nCibler une version\nSi 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):\nhugo mod get github.com\/twbs\/bootstrap@v3.4.1\nSi vous souhaitez utiliser un commit bien précis, pointez vers son hash avec @ comme ceci :\nhugo mod get github.com\/twbs\/bootstrap@394812b61d4dc80bfb2e090de925ae0dfc4cc29b\nVous devez bien entendu versionner les fichiers go.mod et go.sum afin que tous les collaborateurs du projet utilisent les mêmes versions !\nDévelopper un module en local\nCet article ne couvre pas le développemeent local d'un module, nous vous invitons à lire notre note sur le sujet avant d'embarquer pour le joyeux monde des modules Hugo.\nCréer un module Hugo\nBon 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 !\nEt quel meilleur moyen d'apprendre que de créer nous-mêmes notre propre module ?\nCréons pour l'exemple un petit module d'icônes. Pour cela nous voulons :\n\nImporter les fichiers SVG d'un dépôt distant\nCréer une page qui liste toutes les icônes disponibles\nUtiliser notre propre fichier partiel icon pour faciliter l'affichage de n'importe quelle icône du projet.\n\nCréons d'abord un dossier sur notre ordinateur et nommons-le assets\/hugo-icons pour éviter tout conflit avec un dossier assets\/icons existant.\n1. Les imports\nNous avons tout d'abord besoin de lister les imports des fichiers de notre module dans un fichier config.yaml.\nEn 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 !\nNos 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 :\n# config.yaml\nmodule:\n imports:\n - path: github.com\/twbs\/bootstrap\n mounts:\n - source: icons\n target: assets\/hugo-icons\/icons\n2. La page de listing\nPour cela nous avons besoin de deux fichiers :\n\nUn fichier de contenu ;\nUn fichier de modèle pour qu'Hugo puisse effectuer le rendu de notre fichier.\n\nPuisque 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 :\n\npage\/layout.html\npage\/content.md\n\nMettons à jour notre fichier config.yaml, vous pouveez noter que les paramètres mounts se situent à la racine de notre map module.\nLes 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 :\n# config.yaml\nmodule:\n mounts:\n - source: page\/index.md\n target: content\/hugo-icons-listing.md\n lang: en\n - source: page\/template.html\n target: layouts\/_default\/hugo-icons-listing.html\n imports: [...]\nLe paramètre lang n'a d'importance que pour les sites multilingues et même si vous l'omettez la page sera montée pour la langue par défaut du site.\nNos deux fichiers eux ressemblent à ça :\n# page\/index.md\n---\ntitle: Liste des icônes\nlayout: hugo-icons-listing\n---\n\n{{\/* page\/template.html *\/}}\n{{ define \"main\" }}\n {{ range resources.Match \"hugo-icons\/icons\/*.svg\" }}\n <div style=\"fill:currentColor;width:3rem;margin:1rem 0\">\n {{ .Content | safeHTML }}\n <\/div>\n {{ end }}\n{{ end }}\nNotez qu'ici nous partons du principe que votre modèle baseof.html contient un block main, sans quoi Hugo affichera une erreur.\n3. Le fichier partiel\nPlaçons notre fichier dans partials\/icon.html et déclarons un nouveau point de montage :\n# config.yaml\nmodule:\n mounts:\n [...]\n - source: partials\n target: layouts\/partials\/hugo-icons\n imports:\n [...]\nIci 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é.\nNotre fichier partiel :\n{{\/*\n icon\n Affiche l'icône correspondant à la chaîne passée comme contexte\n\n @author @regisphilibert\n\n @context String (.)\n\n @access public\n\n @example - Go Template\n {{ partial \"hugo-icons\/icon\" \"cart\" }}\n*\/}}\n{{- with resources.Get (print \"hugo-icons\/icons\/\" .) -}}\n {{- .Content | safeHTML -}}\n{{- end -}}\nFinitions de notre module\nNotre 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.\nNous 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.\nIl nous faut donc indiquer que notre module ne marchera qu'avec une version d'Hugo au moins égale à 0.64.0 ou sinon… patatra !\n# config.yaml\nmodule:\n hugoVersion:\n # La version extended (Sass) n'est pas requise\n extended: false\n # Il n'y a pas de version maximale\n max: \"\"\n # Par contre il y a une version minimale\n min: \"0.64.0\"\nNotre fichier config.yaml final :\nmodule:\n hugoVersion:\n min: \"0.64.0\"\n mounts:\n - source: page\/index.md\n target: content\/hugo-icons-listing.md\n lang: en\n - source: page\/template.html\n target: layouts\/_default\/hugo-icons-listing.html\n - source: partials\n target: layouts\/partials\/hugo-icons\n imports:\n - path: github.com\/twbs\/icons\n mounts:\n - source: icons\n target: assets\/hugo-icons\/icons\nVous pouvez consulter le dépôt de notre module d'exemple pour cet article.\nPense-bête\nNous avons vu les commandes hugo mod init et hugo mod get -u. Ces deux commandes sont aussi très utiles:\nhugo mod clean\nCette commande va supprimer le cache du module. Je l'utiliss dès que quelque chose de marche pas comme prévu.\nhugo mod tidy\nCette commande supprimera les entrées inutilisées dans votre fichier go.sum.\nConclusion\nLes 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.\nEt 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:\nRessources complémentaires\n\nDocumentation officielle\nLes modules Hugo pour les nuls\nMaîtriser les modules Hugo\n", "content_html": "

Les modules Hugo, apparus dans la version 0.56.0, ajoutent un puissant système de dépendances dont vous auriez tort de vous passer. Ils permettent de rappatrier des fichiers stockés dans des dépôts Git dans vos projets. Les cas d'utilisation vont du simple usage d'un thème complet, à celui de sélection de composants de thèmes distants, comme des icônes, ou au partage de composants réutilisables (modèles, fichiers partiels, shortcodes, etc.) entre plusieurs projets.

\n

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!

\n

Initialiser votre projet en tant que module

\n\n

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

\n

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

\n

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

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

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

\n
module github.com/chez-moi/mon-depot\n\ngo 1.15
\n

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

\n

Importer un dépôt distant

\n

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.

\n

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

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

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

\n
module github.com/chez-moi/mon-depot\n\ngo 1.15\n\nrequire github.com/twbs/icons v1.0.0 // indirect
\n

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

\n

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

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

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

\n\n

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 :

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

Et voilà !

\n

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

\n

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

\n

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.

\n

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

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

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

\n\n

Mise à jour

\n

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.

\n

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

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

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

\n

Cibler une version

\n

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):

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

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

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

Créer un module Hugo

\n

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 !

\n

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

\n

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

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

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.

\n

1. Les imports

\n

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

\n

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 !

\n

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 :

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

2. La page de listing

\n

Pour cela nous avons besoin de deux fichiers :

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

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 :

\n\n

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

\n

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 :

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

Nos deux fichiers eux ressemblent à ça :

\n
# page/index.md\n---\ntitle: Liste des icônes\nlayout: hugo-icons-listing\n---\n
\n
{{/* page/template.html */}}\n{{ define \"main\" }}\n  {{ range resources.Match \"hugo-icons/icons/*.svg\" }}\n    <div style=\"fill:currentColor;width:3rem;margin:1rem 0\">\n    {{ .Content | safeHTML }}\n    </div>\n  {{ end }}\n{{ end }}
\n\n

3. Le fichier partiel

\n

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

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

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é.

\n

Notre fichier partiel :

\n
{{/*\n  icon\n  Affiche l'icône correspondant à la chaîne passée comme contexte\n\n  @author @regisphilibert\n\n  @context String (.)\n\n  @access public\n\n  @example - Go Template\n    {{ partial \"hugo-icons/icon\" \"cart\" }}\n*/}}
\n
{{- with resources.Get (print \"hugo-icons/icons/\" .) -}}\n  {{- .Content | safeHTML -}}\n{{- end -}}
\n

Finitions de notre module

\n

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.

\n

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.

\n

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 !

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

Notre fichier config.yaml final :

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

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

\n\n

Conclusion

\n

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.

\n

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:

\n

Ressources complémentaires

\n", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/12/27/webmentions-eleventy/", "url": "https://jamstatic.fr/2019/12/27/webmentions-eleventy/", "title": "Guide complet des Webmentions avec Eleventy", "summary": "Ajoutez les Webmentions à votre site statique Eleventy grâce à ce guide pas à pas.", "date_published": "2019-12-27T07:48:32+00:00", "date_modified": "2019-12-27T16:05:32+00:00","content_text": "Je suis toujours une grande fan du générateur de site statique Eleventy, et j'étais impatiente de gérer les Webmentions avec.\n\nWebmention 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é.\n— IndieWeb.org\n\nC'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.\nAlors 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.\nLe 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.\nLe 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.\nÉtape 1 : s'inscrire sur webmentions.io\nIl 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.\n\nConfigurer 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.\nAllez sur webmention.io.\nEntrez l'URL de votre site web dans le champ \"Web Sign-In\" , et cliquez sur \"Sign in\".\n\nSi 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 :\n<!-- _includes\/layouts\/base.njk -->\n<link rel=\"webmention\" href=\"https:\/\/webmention.io\/<your.domain>\/webmention\" \/>\n<link rel=\"pingback\" href=\"https:\/\/webmention.io\/<your.domain>\/xmlrpc\" \/>\nVous 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 :\nnpm install dotenv\nCréez un fichier .env à la racine de votre projet et ajoutez votre token d'API pour webmention.io.\nWEBMENTION_IO_TOKEN=v07r370k3n1c1.\nN'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 :\n_cache\/\n_site\/\nnode_modules\/\n.env\nVous 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.\nComment tout ça va marcher\nQuand 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.\nLors de chaque génération, pour chaque page :\n\nDepuis 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).\nFaire appel à la fonction webmentionsByType pour les filtrer par type (par exemple des likes ou des réponses)\nUtiliser la fonction size pour calculer le nombre de mentions par type\nAfficher le total avec le type de mention sous forme d'entête (ex: \"7 réponses\")\nAfficher la liste des mentions de ce type (par exemple sous forme d'avatar avec un lien vers le profil Twitter pour chaque like.)\n\nRécupération des webmentions\nTout 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 :\n\/\/ _data\/metadata.json\n{\n \/\/...other metadata\n \"domain\": \"example.com\",\n \"url\": \"https:\/\/example.com\"\n}\nEnsuite, installons quelques dépendances supplémentaires :\nnpm install lodash node-fetch\nEt mettons à jour notre script de build pour y préciser la variable d'environnement NODE_ENV dans notre package.json :\n\/\/ package.json\n{\n \/\/ …config\n \"scripts\": {\n \"build\": \"NODE_ENV=production npx eleventy\",\n \/\/ scripts…\n}\nNous 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 :\n\nLire les mentions depuis le cache enregistré dans _cache\/webmentions.json.\nSi 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.\nSi notre environnement n’est pas production, retourner les mentions depuis le cache.\n\n\/\/ _data\/webmentions.js\n\/\/ Déclaration des dépendances\nconst fs = require('fs')\nconst fetch = require('node-fetch')\nconst unionBy = require('lodash\/unionBy')\nconst domain = require('.\/metadata.json').domain\n\n\/\/ Charger les variables d'environnement avec `dotenv`\nrequire('dotenv').config()\n\n\/\/ Définir l'emplacement du cache et les paramètres d'appel de l'API\nconst CACHE_FILE_PATH = '_cache\/webmentions.json'\nconst API = 'https:\/\/webmention.io\/api'\nconst TOKEN = process.env.WEBMENTION_IO_TOKEN\n\nasync function fetchWebmentions(since, perPage = 10000) {\n \/\/ Avertir et s'arrêter là si le nom de domaine et le token d'API ne sont pas définis\n if (!domain || !TOKEN) {\n console.warn('>>> Impossible de récupérer les webmentions : domaine ou token manquant')\n return false\n }\n\n let url = `${API}\/mentions.jf2?domain=${domain}&token=${TOKEN}&per-page=${perPage}`\n if (since) url += `&since=${since}` \/\/ ne récupérer que les nouvelles webmentions\n\n const response = await fetch(url)\n if (response.ok) {\n const feed = await response.json()\n console.log(`>>> ${feed.children.length} nouvelles webmentions récupérées depuis ${API}`)\n return feed\n }\n\n return null\n}\n\n\/\/ Fusionner les nouvelles webmentions avec celles du cache, unique par id\nfunction mergeWebmentions(a, b) {\n return unionBy(a.children, b.children, 'wm-id')\n}\n\n\/\/ sauvegarder les webmentions combinnées dans le fichier de cache\nfunction writeToCache(data) {\n const dir = '_cache'\n const fileContent = JSON.stringify(data, null, 2)\n \/\/ créer le dossier de cache s'il n'existe pas déjà\n if (!fs.existsSync(dir)) {\n fs.mkdirSync(dir)\n }\n \/\/ écrire les données dans le fichier de cache JSON\n fs.writeFile(CACHE_FILE_PATH, fileContent, err => {\n if (err) throw err\n console.log(`>>> webmentions mise en cache dans ${CACHE_FILE_PATH}`)\n })\n}\n\n\/\/ Lire le contenu du cache à partir du fichier JSON\nfunction readFromCache() {\n if (fs.existsSync(CACHE_FILE_PATH)) {\n const cacheFile = fs.readFileSync(CACHE_FILE_PATH)\n return JSON.parse(cacheFile)\n }\n\n \/\/ Pas de cache trouvé.\n return {\n lastFetched: null,\n children: []\n }\n}\n\nmodule.exports = async function () {\n console.log('>>> Lectures des webmentions depuis le cache…');\n\n const cache = readFromCache()\n\n if (cache.children.length) {\n console.log(`>>> ${cache.children.length} webmentions chargées depuis le cache`)\n }\n\n \/\/ Ne télécharger les nouvelles webmentions qu'en production\n if (process.env.NODE_ENV === 'production') {\n console.log('>>> Vérification de nouvelles webmentions...');\n const feed = await fetchWebmentions(cache.lastFetched)\n if (feed) {\n const webmentions = {\n lastFetched: new Date().toISOString(),\n children: mergeWebmentions(cache, feed)\n }\n\n writeToCache(webmentions)\n return webmentions\n }\n }\n\n return cache\n}\nFiltres pour la génération\nMaintenant 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.\nD'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 :\n\/\/ _11ty\/filters.js\nconst { DateTime } = require(\"luxon\"); \/\/ Déjà présent dans eleventy-base-blog\n\nmodule.exports = {\n getWebmentionsForUrl: (webmentions, url) => {\n return webmentions.children.filter(entry => entry['wm-target'] === url)\n },\n size: (mentions) => {\n return !mentions ? 0 : mentions.length\n },\n webmentionsByType: (mentions, mentionType) => {\n return mentions.filter(entry => !!entry[mentionType])\n },\n readableDateFromISO: (dateStr, formatStr = \"dd LLL yyyy 'at' hh:mma\") => {\n return DateTime.fromISO(dateStr).toFormat(formatStr);\n }\n}\nMaintenant 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 :\n\/\/ .eleventy.js\n\/\/ ...Autres imports\nconst filters = require('.\/_11ty\/filters')\n\nmodule.exports = function(eleventyConfig) {\n \/\/ Filters\n Object.keys(filters).forEach(filterName => {\n eleventyConfig.addFilter(filterName, filters[filterName])\n })\n\n \/\/ Autres configs...\nIci je n'utilise pas de filtre d’assainissement du HTML car j'ai remarqué que les données sont contenues dans un champ text qui est déjà nettoyé. C'est peut-être nouveau ou bien ce n'est pas valable pour toutes les webmentions. Je mettrais cet article à jour si je dois l'ajouter.\nAfficher les mentions\nNous 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 :\n<!-- _includes\/layouts\/post.njk -->\n<section>\n <h2>Webmentions<\/h3>\n {% set webmentionUrl %}{{ page.url | url | absoluteUrl(site.url) }}{% endset %}\n {% include 'webmentions.njk' %}\n<\/section>\nNous 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 :\n<!-- _includes\/webmentions.njk -->\n <!-- Filtrer les webmentions du cache pour n’inclure que celles relatives à l’URL de l’article en cours -->\n {% set mentions = webmentions | getWebmentionsForUrl(metadata.url + webmentionUrl) %}\n <!-- Définir les reposts comme des mentions de type `repost-of` -->\n {% set reposts = mentions | webmentionsByType('repost-of') %}\n <!-- Calcul du total de reposts -->\n {% set repostsSize = reposts | size %}\n <!-- Définir les likes comme des mentions de type `like-of` -->\n {% set likes = mentions | webmentionsByType('like-of') %}\n <!-- Calcul du total de likes -->\n {% set likesSize = likes | size %}\n <!-- Définir les réponses comme des mentions de type `in-reply-to` -->\n {% set replies = mentions | webmentionsByType('in-reply-to') %}\n <!-- Calcul du total de réponses -->\n {% set repliesSize = replies | size %}\nUne 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.\nL'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 :\n<!-- _includes\/webmentions.njk -->\n<!-- …définition des variables… -->\n{% if repliesSize > 0 %}\n<div class=\"webmention-replies\">\n <h3>{{ repliesSize }} {% if repliesSize == \"1\" %}Reply{% else %}Replies{% endif %}<\/h3>\n\n {% for webmention in replies %}\n {% include 'webmention.njk' %}\n {% endfor %}\n<\/div>\n{% endif %}\nNous 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 :\n<!-- _includes\/webmention.njk -->\n<article class=\"webmention\" id=\"webmention-{{ webmention['wm-id'] }}\">\n <div class=\"webmention__meta\">\n {% if webmention.author %}\n {% if webmention.author.photo %}\n <img src=\"{{ webmention.author.photo }}\" alt=\"{{ webmention.author.name }}\" width=\"48\" height=\"48\" loading=\"lazy\">\n {% else %}\n <img src=\"{{ '\/img\/avatar.svg' | url }}\" alt=\"\" width=\"48\" height=\"48\">\n {% endif %}\n <span>\n <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>\n <\/span>\n {% else %}\n <span>\n <strong>Anonymous<\/strong>\n <\/span>\n {% endif %}\n\n {% if webmention.published %}\n <time class=\"postlist-date\" datetime=\"{{ webmention.published }}\">\n {{ webmention.published | readableDateFromISO }}\n <\/time>\n {% endif %}\n <\/div>\n <div>\n {{ webmention.content.text }}\n <\/div>\n<\/article>\nSautons courageusement dans l’inconnu…\nÇ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. 😁\nVous 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 !\nPoursuivez en ajoutant des Microformats\nKeith 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.\nRessources additionnelles\n\nLa 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.\nComment ajouter le support de dotenv sur Netlify est abordé dans cette réponse sur Stack Overflow.\nComment 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.\n", "content_html": "

Je suis toujours une grande fan du générateur de site statique Eleventy, et j'étais impatiente de gérer les Webmentions avec.

\n
\n

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é.\n— IndieWeb.org

\n
\n

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.

\n

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.

\n

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.

\n

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.

\n

Étape 1 : s'inscrire sur webmentions.io

\n

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.

\n
    \n
  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. \n
  2. Allez sur webmention.io.
    3. \n
  3. Entrez l'URL de votre site web dans le champ \"Web Sign-In\" , et cliquez sur \"Sign in\".
    4. \n
\n

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 :

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

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 :

\n
npm install dotenv
\n

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

\n
WEBMENTION_IO_TOKEN=v07r370k3n1c1.
\n

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 :

\n
_cache/\n_site/\nnode_modules/\n.env
\n

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.

\n

Comment tout ça va marcher

\n

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.

\n

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

\n\n

Récupération des webmentions

\n

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 :

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

Ensuite, installons quelques dépendances supplémentaires :

\n
npm install lodash node-fetch
\n

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

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

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 :

\n
    \n
  1. Lire les mentions depuis le cache enregistré dans _cache/webmentions.json.
    2. \n
  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. \n
  3. Si notre environnement n’est pas production, retourner les mentions depuis le cache.
    4. \n
\n
// _data/webmentions.js\n// Déclaration des dépendances\nconst fs = require('fs')\nconst fetch = require('node-fetch')\nconst unionBy = require('lodash/unionBy')\nconst domain = require('./metadata.json').domain\n\n// Charger les variables d'environnement avec `dotenv`\nrequire('dotenv').config()\n\n// Définir l'emplacement du cache et les paramètres d'appel de l'API\nconst CACHE_FILE_PATH = '_cache/webmentions.json'\nconst API = 'https://webmention.io/api'\nconst TOKEN = process.env.WEBMENTION_IO_TOKEN\n\nasync function fetchWebmentions(since, perPage = 10000) {\n  // Avertir et s'arrêter là si le nom de domaine et le token d'API ne sont pas définis\n  if (!domain || !TOKEN) {\n    console.warn('>>> Impossible de récupérer les webmentions : domaine ou token manquant')\n    return false\n  }\n\n  let url = `${API}/mentions.jf2?domain=${domain}&token=${TOKEN}&per-page=${perPage}`\n    if (since) url += `&since=${since}` // ne récupérer que les nouvelles webmentions\n\n  const response = await fetch(url)\n  if (response.ok) {\n    const feed = await response.json()\n    console.log(`>>> ${feed.children.length} nouvelles webmentions récupérées depuis ${API}`)\n    return feed\n  }\n\n  return null\n}\n\n// Fusionner les nouvelles webmentions avec celles du cache, unique par id\nfunction mergeWebmentions(a, b) {\n  return unionBy(a.children, b.children, 'wm-id')\n}\n\n// sauvegarder les webmentions combinnées dans le fichier de cache\nfunction writeToCache(data) {\n  const dir = '_cache'\n  const fileContent = JSON.stringify(data, null, 2)\n  // créer le dossier de cache s'il n'existe pas déjà\n  if (!fs.existsSync(dir)) {\n    fs.mkdirSync(dir)\n  }\n  // écrire les données dans le fichier de cache JSON\n  fs.writeFile(CACHE_FILE_PATH, fileContent, err => {\n    if (err) throw err\n    console.log(`>>> webmentions mise en cache dans ${CACHE_FILE_PATH}`)\n  })\n}\n\n// Lire le contenu du cache à partir du fichier JSON\nfunction readFromCache() {\n  if (fs.existsSync(CACHE_FILE_PATH)) {\n    const cacheFile = fs.readFileSync(CACHE_FILE_PATH)\n    return JSON.parse(cacheFile)\n  }\n\n  // Pas de cache trouvé.\n  return {\n    lastFetched: null,\n    children: []\n  }\n}\n\nmodule.exports = async function () {\n  console.log('>>> Lectures des webmentions depuis le cache…');\n\n  const cache = readFromCache()\n\n  if (cache.children.length) {\n    console.log(`>>> ${cache.children.length} webmentions chargées depuis le cache`)\n  }\n\n  // Ne télécharger les nouvelles webmentions qu'en production\n  if (process.env.NODE_ENV === 'production') {\n    console.log('>>> Vérification de nouvelles webmentions...');\n    const feed = await fetchWebmentions(cache.lastFetched)\n    if (feed) {\n      const webmentions = {\n        lastFetched: new Date().toISOString(),\n        children: mergeWebmentions(cache, feed)\n      }\n\n      writeToCache(webmentions)\n      return webmentions\n    }\n  }\n\n  return cache\n}
\n

Filtres pour la génération

\n

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.

\n

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 :

\n
// _11ty/filters.js\nconst { DateTime } = require(\"luxon\"); // Déjà présent dans eleventy-base-blog\n\nmodule.exports = {\n  getWebmentionsForUrl: (webmentions, url) => {\n    return webmentions.children.filter(entry => entry['wm-target'] === url)\n  },\n  size: (mentions) => {\n    return !mentions ? 0 : mentions.length\n  },\n  webmentionsByType: (mentions, mentionType) => {\n    return mentions.filter(entry => !!entry[mentionType])\n  },\n  readableDateFromISO: (dateStr, formatStr = \"dd LLL yyyy 'at' hh:mma\") => {\n    return DateTime.fromISO(dateStr).toFormat(formatStr);\n  }\n}
\n

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 :

\n
// .eleventy.js\n// ...Autres imports\nconst filters = require('./_11ty/filters')\n\nmodule.exports = function(eleventyConfig) {\n  // Filters\n  Object.keys(filters).forEach(filterName => {\n    eleventyConfig.addFilter(filterName, filters[filterName])\n  })\n\n  // Autres configs...
\n\n

Afficher les mentions

\n

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 :

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

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 :

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

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.

\n

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 :

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

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 :

\n
<!-- _includes/webmention.njk -->\n<article class=\"webmention\" id=\"webmention-{{ webmention['wm-id'] }}\">\n  <div class=\"webmention__meta\">\n    {% if webmention.author %}\n      {% if webmention.author.photo %}\n      <img src=\"{{ webmention.author.photo }}\" alt=\"{{ webmention.author.name }}\" width=\"48\" height=\"48\" loading=\"lazy\">\n      {% else %}\n      <img src=\"{{ '/img/avatar.svg' | url }}\" alt=\"\" width=\"48\" height=\"48\">\n      {% endif %}\n      <span>\n        <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>\n      </span>\n    {% else %}\n      <span>\n        <strong>Anonymous</strong>\n      </span>\n    {% endif %}\n\n    {% if webmention.published %}\n      <time class=\"postlist-date\" datetime=\"{{ webmention.published }}\">\n        {{ webmention.published | readableDateFromISO }}\n      </time>\n    {% endif %}\n  </div>\n  <div>\n    {{ webmention.content.text }}\n  </div>\n</article>
\n

Sautons courageusement dans l’inconnu…

\n

Ç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. 😁

\n

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 !

\n

Poursuivez en ajoutant des Microformats

\n

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.

\n

Ressources additionnelles

\n", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/12/22/partiels-fonction-hugo/", "url": "https://jamstatic.fr/2019/12/22/partiels-fonction-hugo/", "title": "Des fonctions dans nos partiels Hugo !", "summary": "Maintenant que les partiels peuvent retourner tout type de donnée, nous pouvons écrire des fonctions réutilisables dans nos différents modèles de page !", "date_published": "2019-12-22T09:36:56+00:00", "date_modified": "2019-12-22T15:21:43+00:00","content_text": "\n\n\n\n\n\nDes fonctions dans nos partiels Hugo\n\nComme 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.\nTout 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.\nDans cet article, nous aborderons les bases de cette fonctionnalité avant de nous plonger dans des cas d'utilisation bien précis.\nAvant return\nAvant 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:\n# layouts\/partial\/FormatURL.html\n{{- $S3Domain := site.Params.s3Domain -}}\n{{- printf \"%s\/%s\" $S3Domain . | safeHTMLAttr -}}\n# layout\/_default\/single.html\n{{- with .Params.image -}}\n<img src=\"{{ partial \"FormatURL.html\" . }}\" \/>\n{{ end }}\nIci 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.\nOn pourrait même aller plus loin et afficher des données au format JSON à l'appel du partiel :\n# layouts\/partial\/GetSEOData.html\n{{- with . -}}\n {{- $title := .Title -}}\n {{- $description := .Summary -}}\n {{- with .Params.seo.title -}}\n {{- $title = . -}}\n {{- end -}}\n {{- with .Params.seo.description -}}\n {{- $description = . -}}\n {{- end -}}\n {{- dict \"title\" $title \"description\" $description | jsonify -}}\n{{- end -}}\n\n# layouts\/partial\/head.html\n{{ $seo := partial \"GetSEOData.html\" . | transform.Unmarshal }}\n{{ with $seo }}\n # seo tags...\n{{ end }}\nMais 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.\nIl n'y avait aucun moyen de facilement retourner un objet complexe comme une page ou un fichier, encore moins une collection de pages.\nPuis vint Hugo 0.55.0 , l'instruction return et les partiels de fonction!\nQuelques points à retenir\nAvant de nous plonger dans le code, il y a certaines choses à faire et à ne pas faire que nous devons passer en revue.\n🚫 Pas de return dans les clauses\n{{ if gt .Params.temperature 70 }}\n {{ return 😎 }}\n{{ end }}\nIci ☝️ 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.\n{{ with .Params.temperature }}\n {{ return . }}\n{{ end }}\nMême chose ici ☝️, return doit se trouver à la racine et ne peut pas être appelé dans une instruction imbriquée.\n🚫 Pas de multiples instructions return\n{{ if gt .Params.temperature 70 }}\n {{ return 😎 }}\n{{ else }}\n {{ return ⛸️ }}\n{{ end }}\nCet exemple ne marchera pas, car les retours multiples ne sont pas supportés.\n👍 Une unique variable retournée\nOn tire donc des exemples précédents la règle générique : une variable retournée unique à la racine.\nLe meilleur moyen de se conformer à cette règle est de porter notre attention sur l'unique variable retournée.\nLa variable retournée c'est votre base de départ, celle que vous allez manipuler et éventuellement retourner.\n\n🍽️ Affecter une valeur de départ,\n🔪 la travailler,\n💁‍♂️ et la retourner à la fin.\n\n{{ $emoji := ⛸️ }}\n{{ if gt .Params.temperature 70 }}\n {{ $emoji = 😎}}\n{{ else if gt .Params.temperature 100 }}\n {{ $emoji = 🥵}}\n{{ end }}\n{{ return $emoji }}\nQuel 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.\n{{< notice info >}}\nTout comme pour if, with, range et leurs amis, ce qui suit return n'a pas besoin d'être entre parenthèses.\n{{ return gt .Params.temperature 50 }}\n☝️ Cette notation est valide et retournera un booléen.\n{{< \/notice >}}\n🤙 Appeler nos partiels de fonction\nComme pour n'importe quel autre partiel on écrit :\nEmoji: {{ partial \"emoji.html\" . }}\nLà où ça devient intéressant c'est qu'on peut stocker la valeur retournée !\n{{ $emoji := partial \"emoji.html\" . }}\n📏 Quelques conventions\nDu moins celles que j'ai adoptées…\nPour 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.\n{{ partial \"func\/emoji.html\" . }}\nHugo 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 :\n{{ partial \"func\/emoji\" . }}\nEnfin, j'aime bien utiliser la casse CamelCase ainsi qu'un verbe autant que possible :\n{{ partial \"func\/GetEmoji\" . }}\nEt voilà mon code Hugo est tout beau :\n{{ with partial \"func\/GetEmoji\" . }}\n Emoji: {{ . }}\n{{ end }}\nCoder nos partiels de fonction\nBien, 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.\nCette 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 :\n---\ntitle: Une nuit au Louvre\ntags:\n - Art\n - Paris\n - Musée\n---\n\nPour 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.\nCe 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.\nQuant à l'appel de ce type de partiel, il devrait être aussi concis que cela :\n{{ range .Params.tags }}\n {{ with partial \"func\/GetTagPage\" . }}\n <a href=\"{{ .RelPermalink }}\">{{ .Title }}<\/a>\n {{ end }}\n{{ end }}\n🙌 ⌨️ C'est parti\n{{\/* 1. *\/}}\n{{ $tag := false }}\n{{\/* 2. *\/}}\n{{ with index site.Taxonomies.tags (urlize .) }}\n {{\/* 3. *\/}}\n {{ with .Page }}\n {{\/* 4. *\/}\n {{ $tag = . }}\n {{ end }}\n{{ end }}\n\n{{\/* 5. *\/}\n{{ return $tag }}\n\nNous commençons par initialiser notre variable retournée à sa valeur par défaut\nsite.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.\nNous 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.\nNous stockons le tag de la page dans notre variable retournée.\n🎉\n\n👍 Beau boulot !\nEt 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. 🙅‍♀️\nNous voulons pouvoir écrire ceci :\n{{ range .Params.categories }}\n {{ with partial \"func\/GetTermPage\" (dict \"taxonomy\" \"categories\" \"term\" .) }}\n <a href=\"{{ .RelPermalink }}\">{{ .Title }}<\/a>\n {{ end }}\n{{ end }}\nGestion des arguments\nJusqu'à 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.\nNous mettons donc notre partiel à jour :\n{{ $return := false }}\n\n{{\/* 1. *\/}}\n{{ $taxonomy := \"tags\" }}\n{{ with .taxonomy }}\n {{ $taxonomy = . }}\n{{ end }}\n\n{{\/* 2. *\/}}\n{{ with $term := .term }}\n {{ with index site.Taxonomies $taxonomy }}\n {{ with index . (urlize $term) }}\n {{ with .Page }}\n {{ $return = . }}\n {{ end }}\n {{ end }}\n {{ end }}\n{{ end }}\n\n{{\/* 3. *\/}}\n{{ return $return }}\n\nMaintenant 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.\nSi 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 !\n🎉\n\nMise en cache !\nOK 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.\nC'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:\n#layout\/partials\/func\/GetTags.html\n{{\/* 1. *\/}}\n{{ $return := slice }}\n{{\/* 2. *\/}}\n{{ with .Params.tags }}\n {{ range . }}\n {{\/* 3. *\/}}\n {{ with partialCached \"func\/GetTerm\" (dict \"taxonomy\" \"tags\" \"term\" .) \"tags\" . }}\n {{\/* 4. *\/}}\n {{ $tag := dict \"URL\" .RelPermalink \"Name\" .Title }}\n {{\/* 5. *\/}}\n {{ $return := $return | append $tag }}\n {{ end }}\n {{ end }}\n{{ end }}\n\n{{\/* 6. *\/}}\n{{ return $return }}\n\nNous 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.\nLa 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.\nNous 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.\nNous 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.\nNous utilisons la fonction append pour ajouter notre tableau associatif $tag au tableau que nous retournons.\n🎉\n\nMaintenant dans notre modèle nous pouvons écrire :\n# layouts\/_default\/single.html\n{{\/* 1. *\/}}\n{{ range partial \"func\/GetTags\" $ }}\n {{\/* 2. *\/}}\n <a href=\"{{ .URL }}\">{{ .Name }}<\/a>\n{{ end }}\n\nNous 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.\nNous pouvons maintenant utiliser les clefs personnalisées de nos tableaux associatifs.\nC'est tout !\n\nDes améliorations possibles ?\nBien entendu ! Nous pourrions :\n\nExclure certains tags du tableau retourné par la fonction GetTags\nTransformer GetTags en GetTerms, afin de pouvoir l'utiliser pour n'importe quelle taxonomie.\nTrouver la bonne variante de notre partiel de fonction GetTags et utiliser partialCached.\nDévelopper bien plus de partiels de fonction pour répondre à d'autres besoins !\n\nConclusion\nAprè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.\nEt 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 !\nAvec 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 !\nEst-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 ?\nSi 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 !", "content_html": "
\n\n\n\n\"Des\n\n
Des fonctions dans nos partiels Hugo
\n
\n

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.

\n

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.

\n

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

\n

Avant return

\n

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:

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

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.

\n

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

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

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.\nIl n'y avait aucun moyen de facilement retourner un objet complexe comme une page ou un fichier, encore moins une collection de pages.

\n

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

\n

Quelques points à retenir

\n

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

\n

🚫 Pas de return dans les clauses

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

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.

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

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

\n

🚫 Pas de multiples instructions return

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

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

\n

👍 Une unique variable retournée

\n

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

\n

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

\n

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

\n
    \n
  1. 🍽️ Affecter une valeur de départ,
    2. \n
  2. 🔪 la travailler,
    3. \n
  3. 💁‍♂️ et la retourner à la fin.
    4. \n
\n
{{ $emoji := ⛸️ }}\n{{ if gt .Params.temperature 70 }}\n  {{ $emoji = 😎}}\n{{ else if gt .Params.temperature 100 }}\n  {{ $emoji = 🥵}}\n{{ end }}\n{{ return $emoji }}
\n

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.

\n

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

\n
{{ return gt .Params.temperature 50 }}
\n

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

\n

🤙 Appeler nos partiels de fonction

\n

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

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

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

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

📏 Quelques conventions

\n

Du moins celles que j'ai adoptées…

\n

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.

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

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 :

\n
{{ partial \"func/emoji\" . }}
\n

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

\n
{{ partial \"func/GetEmoji\" . }}
\n

Et voilà mon code Hugo est tout beau :

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

Coder nos partiels de fonction

\n

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.

\n

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 :

\n
---\ntitle: Une nuit au Louvre\ntags:\n  - Art\n  - Paris\n  - Musée\n---\n
\n

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.

\n

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.

\n

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

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

🙌 ⌨️ C'est parti

\n
{{/* 1. */}}\n{{ $tag := false }}\n{{/* 2. */}}\n{{ with index site.Taxonomies.tags (urlize .) }}\n  {{/* 3. */}}\n  {{ with .Page }}\n    {{/* 4. */}\n    {{ $tag = . }}\n  {{ end }}\n{{ end }}\n\n{{/* 5. */}\n{{ return $tag }}
\n
    \n
  1. Nous commençons par initialiser notre variable retournée à sa valeur par défaut
    2. \n
  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. \n
  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. \n
  4. Nous stockons le tag de la page dans notre variable retournée.
    5. \n
  5. 🎉
    6. \n
\n

👍 Beau boulot !

\n

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. 🙅‍♀️

\n

Nous voulons pouvoir écrire ceci :

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

Gestion des arguments

\n

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.

\n

Nous mettons donc notre partiel à jour :

\n
{{ $return := false }}\n\n{{/* 1. */}}\n{{ $taxonomy := \"tags\" }}\n{{ with .taxonomy }}\n  {{ $taxonomy = . }}\n{{ end }}\n\n{{/* 2. */}}\n{{ with $term := .term }}\n  {{ with index site.Taxonomies $taxonomy }}\n    {{ with index . (urlize $term) }}\n      {{ with .Page }}\n        {{ $return = . }}\n      {{ end }}\n    {{ end }}\n  {{ end }}\n{{ end }}\n\n{{/* 3. */}}\n{{ return $return }}
\n
    \n
  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. \n
  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. \n
  3. 🎉
    4. \n
\n

Mise en cache !

\n

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.

\n

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:

\n
#layout/partials/func/GetTags.html\n{{/* 1. */}}\n{{ $return := slice }}\n{{/* 2. */}}\n{{ with .Params.tags }}\n  {{ range . }}\n    {{/* 3. */}}\n    {{ with partialCached \"func/GetTerm\" (dict \"taxonomy\" \"tags\" \"term\" .) \"tags\" . }}\n      {{/* 4. */}}\n      {{ $tag := dict \"URL\" .RelPermalink \"Name\" .Title }}\n      {{/* 5. */}}\n      {{ $return := $return | append $tag }}\n    {{ end }}\n  {{ end }}\n{{ end }}\n\n{{/* 6. */}}\n{{ return $return }}
\n
    \n
  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. \n
  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. \n
  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. \n
  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. \n
  5. Nous utilisons la fonction append pour ajouter notre tableau associatif $tag au tableau que nous retournons.
    6. \n
  6. 🎉
    7. \n
\n

Maintenant dans notre modèle nous pouvons écrire :

\n
# layouts/_default/single.html\n{{/* 1. */}}\n{{ range partial \"func/GetTags\" $ }}\n  {{/* 2. */}}\n  <a href=\"{{ .URL }}\">{{ .Name }}</a>\n{{ end }}
\n
    \n
  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. \n
  2. Nous pouvons maintenant utiliser les clefs personnalisées de nos tableaux associatifs.
    3. \n
  3. C'est tout !
    4. \n
\n

Des améliorations possibles ?

\n

Bien entendu ! Nous pourrions :

\n\n

Conclusion

\n

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.

\n

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 !

\n

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 !

\n

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 ?

\n

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 !

", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/12/10/jamstack-pour-les-clients/", "url": "https://jamstatic.fr/2019/12/10/jamstack-pour-les-clients/", "title": "Jamstack pour les clients", "summary": "Comment communiquer clairement et efficacement les avantages de la Jamstack à vos prospects et vos clients ?", "date_published": "2019-12-10T12:54:24+00:00", "date_modified": "2019-12-14T14:24:18+00:00","content_text": "Savoir choisir les bon outils pour un projet représente une part importante de ce qui fait le succès d'une agence de développement web. S'il est facile de s'enthousiasmer sur les dernières technologies en vogue, il est plus difficile d'expliquer à son client les bénéfices de la technologie que nous lui suggérons d'adopter.\nDe 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.\nC'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.\nMais ça ne marchera pas avec vos clients.\nDonc, 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.\nLes bénéfices de la Jamstack\nJe 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.\nAvec 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.\nToutefois, 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.\nFocalisez-vous plutôt sur comment cela pour être bénéfique pour leur activité.\nEn général, cela se résume à des revenus ou à une meilleure expérience pour eux, leur développeurs et leur audience.\nDe meilleures performances\n\nPlus 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\n\nLa 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.\nC'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.\nD'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.\nSécurité accrue et mise à l'échelle plus facile\nPersonne 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.\nPour 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.\nHébergement\nNous 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.\nExpliquer la Jamstack au client\nLorsqu'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.\nAlors, comment communiquez-vous tous les avantages avec votre client ?\nPosez des questions et informez vos clients\nCommencez 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.\nEnsuite, 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).\nFaites 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.\nFaîtes des études de cas\nLes é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.\nSi 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.\nDonnez-leur des options, laissez-les choisir\nSi 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.\nEn résumé…\nLa 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.\nC'est votre travail de vous assurer qu'ils obtiennent ce dont ils ont besoin et de comprendre la logique et la technologie sous-jacente.", "content_html": "

Savoir choisir les bon outils pour un projet représente une part importante de ce qui fait le succès d'une agence de développement web. S'il est facile de s'enthousiasmer sur les dernières technologies en vogue, il est plus difficile d'expliquer à son client les bénéfices de la technologie que nous lui suggérons d'adopter.

\n

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.

\n

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.

\n

Mais ça ne marchera pas avec vos clients.

\n

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.

\n

Les bénéfices de la Jamstack

\n

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.

\n

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.

\n

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.

\n

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

\n

De meilleures performances

\n
\n

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

\n
\n

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.

\n

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.

\n

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.

\n

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

\n

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.

\n

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.

\n

Hébergement

\n

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.

\n

Expliquer la Jamstack au client

\n

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.

\n

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

\n

Posez des questions et informez vos clients

\n

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.

\n

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).

\n

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.

\n

Faîtes des études de cas

\n

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.

\n

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.

\n

Donnez-leur des options, laissez-les choisir

\n

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.

\n

En résumé…

\n

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.

\n

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.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/12/03/mise-en-cache-fichiers-partiels-hugo/", "url": "https://jamstatic.fr/2019/12/03/mise-en-cache-fichiers-partiels-hugo/", "title": "Gestion du cache des fichiers partiels avec Hugo", "summary": "Apprenez à optimiser le cache des fichiers partiels pour reduire plus encore vos temps de génération avec Hugo.", "date_published": "2019-12-03T17:10:24+00:00", "date_modified": "2019-12-07T17:13:54+00:00","content_text": "\n\n\n\n\n\nIllustration des partiels d'Hugo\n\nLes 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.\nNous n'allons pas revenir dans cet article sur les bases des partiels comme leur contexte que nous avons déjà détaillé auparavant.\nNous 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é.\nEntrons dans le vif du sujet sans plus attendre avec la solution dédiée à la mise en cache des fichiers partiels : partialCached\nPourquoi utiliser partialCached ?\nComme 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.\nSi 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 !\nLe 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.\nSongez à l'entête de page de votre site par exemple.\nVotre 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.\nSi 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.\nAvec 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 :\n{{ partialCached \"header.html\" . }}\nC'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 ⏱️!\nMais notre entête de page est-il vraiment identique sur toutes les pages ?\nNon, 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.\nLe code de notre menu Hugo contient souvent quelque chose comme :\n<nav>\n{{ range .Site.Menus.main }}\n <a\n class=\"{{ if eq $currentPage.Section .Page.Section }} active {{ end }}\"\n href=\"{{ .URL }}\"\n >\n {{ .Name }}\n <\/a>\n{{ end }}\n<\/nav>\nLe 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).\nAvec 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.\nHeureusement il y a les variantes de partiel.\nLes variantes de partiel\nNous 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.\nContrairement à la fonction partial, les arguments de partialCached ne se limitent pas au contexte.\nPour nos cas d'utilisation, il est clair que la variante est la .Section de la page courante, nous pouvons donc écrire ceci :\n{{ partialCached \"navigation.html\" . .Section }}\n🎉 C'est 995 fois où Hugo n'aura pas à interpréter le code de ce partiel.\nBien. Cela fait une variante en moins, mais quid si quelque chose d'autre doit changer et que ce n'est pas lié à la section ?\nPar 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.\nLe code ressemble à ça :\n{{ if ne .Layout \"contact\" }}\n {{ range site.Socials }}\n {{\/* vous voyez l'idée *\/}}\n {{ end }}\n{{ end }}\nNous avons donc maintenant besoin de deux variantes, la variante .Section et la variante Est-ce la page de contact ?.\nHeureusement pour nous, le nombre de variantes n'est pas limité, alors allons-y gaiement :\n{{ partialCached \"navigation.html\" . .Section \"contact\" }}\nOK, c'était simplement à des fins de clarté et de lisibilité mais soyons réaliste, vous aurez vraisemblablement besoin de quelque chose de plus \"dynamique\" :\n{{ $layout := cond (eq .Layout \"contact\") \"contact\" \"other\" }}\n{{ partialCached \"navigation.html\" . .Section $layout }}\n🎉 C'est maintenant 994 fois où Hugo n'aura pas à interpréter le code de ce partiel.\nHaussons le niveau d'un cran 💪\nPlongeons-nous maintenant dans quelque chose d'un peu plus complexe.\nNotre 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.\nIci, 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 :\n{{ partialCached \"authors-box.html\" . .Params.authors }}\nMalheureusement à l'heure actuelle, les variantes passées en argument de la fonction partialCached doivent être des chaînes de caractères 🤷.\nPour 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.\nPersonnellement 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.\nAdmettons que nous ayons :\nauthors:\n - Bud Parr\n - Frank Taillandier\n - Régis Philibert\n{{ $variant := printf \"%x\" .Params.authors }}\n🖨️👇\n[42756420506172724672616e6b205461696c6c616e6469657252c3a9676973205068696c6962657274]\nNous avons maintenant une chaîne de caractères que nous pouvons passer comme variante du partiel :\n{{ with .Params.authors }}\n {{ $authors := sort . }}\n {{ $variant := printf \"%x\" $authors }}\n {{ partialCached \"authors-box.html\" . $variant }}\n{{ end }}\nGrâ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.\nPourquoi ordonner les auteurs ?\nEn les classant par ordre alphabétique, nous nous assurons de ne pas créer des variantes inutiles, et ce que quel que soit l'ordre dans lequel les auteurs ont été listés dans le front matter.\nCette solution pour utiliser les variantes marche pour les listes et les tableaux associatifs simples. Effectuez des tests si vous l'utiliser pour des structures de données imbriquées plus complexes.\nEt les langues ? 🇫🇷🇬🇧\nDans 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 :\n{{ partialCached \"navigation.html\" . .Section .Lang }}\nMais 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.\nDans notre cas de figure, Hugo va donc calculer le balisage de notre entête dix fois.\nLa règle d'or pour connaître le \"calcul\" du nombre de partiels est :\npartiel x variantes x langues\nAméliorer votre temps de génération ⏱️\nPour 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.\nLa 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.\nCes options vous aideront à identifier les principaux goulots d'étranglement, cependant vous devriez tout le temps garder ces trois points en tête:\n\nLe niveau de complexité de votre fichier partiel et sa durée de génération ajoutée au temps total.\nLa comparaison entre le nombre de fois où un partiel sera traité et son potentiel de variantes.\nL'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)\n\nConclusion\nLorsque 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!\nAllez 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 !", "content_html": "
\n\n\n\n\"Illustration\n\n
Illustration des partiels d'Hugo
\n
\n

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.

\n

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

\n

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é.

\n

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

\n

Pourquoi utiliser partialCached ?

\n

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.

\n

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 !

\n

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.

\n

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

\n

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.

\n

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.

\n

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 :

\n
{{ partialCached \"header.html\" . }}
\n

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 ⏱️!

\n

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

\n

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.

\n

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

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

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).

\n

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.

\n

Heureusement il y a les variantes de partiel.

\n

Les variantes de partiel

\n

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.

\n

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

\n

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

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

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

\n

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 ?

\n

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.

\n

Le code ressemble à ça :

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

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

\n

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

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

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\" :

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

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

\n

Haussons le niveau d'un cran 💪

\n

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

\n

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.

\n

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 :

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

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

\n

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.

\n

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.

\n

Admettons que nous ayons :

\n
authors:\n  - Bud Parr\n  - Frank Taillandier\n  - Régis Philibert
\n
{{ $variant := printf \"%x\" .Params.authors }}
\n

🖨️👇\n[42756420506172724672616e6b205461696c6c616e6469657252c3a9676973205068696c6962657274]

\n

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

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

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.

\n\n\n

Et les langues ? 🇫🇷🇬🇧

\n

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 :

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

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.\nDans notre cas de figure, Hugo va donc calculer le balisage de notre entête dix fois.

\n\n

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

\n

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.

\n

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.

\n

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

\n
    \n
  1. Le niveau de complexité de votre fichier partiel et sa durée de génération ajoutée au temps total.
    2. \n
  2. La comparaison entre le nombre de fois où un partiel sera traité et son potentiel de variantes.
    3. \n
  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)
    4. \n
\n

Conclusion

\n

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!

\n

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 !

", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/10/30/git-based-cms-vs-api-first-cms/", "url": "https://jamstatic.fr/2019/10/30/git-based-cms-vs-api-first-cms/", "title": "Git-based, API-first headless CMS : lequel choisir ?", "summary": "Les différences à connaître entre les headless CMS qui reposent sur Git et ceux qui fournissent une API.", "date_published": "2019-10-30T09:26:33+00:00","content_text": "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.\nDans 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.\nIl 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.\nAlors 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.\nWordPress 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.\nMais il faut bien que le contenu de votre site web vive quelque part, n'est-ce pas ?\nBienvenue 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. 1\nLes CMS basés sur Git\n\n\n\n\n\nAvec 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.\nPour\n\nPas de verrou propriétaire sur vos contenus.\nGestion de version de tous les contenus par défaut.\nTous les contenus étant disponibles sous forme de fichiers texte, les développeurs peuvent continuer d'utiliser leurs outils habituels.\nFacilite l'annulation de changements.\nC'est l'approche la plus homogène pour la plupart des développeurs web, qui utilisent déjà un workflow basé sur Git.\nFacile à configurer.\n\nContre\n\nSi 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.\nSi 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.\nSi 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.\nMoins d'options de modélisation de contenu et de formatage.\n\nLes CMS API-first\n\n\n\n\n\nAvec 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.\nPour\n\nC'est la meilleure solution si vous maintenez plusieurs applications et sites web qui récupèrent le même contenu structuré.\nFacile à utiliser avec de multiples terminaux client.\nBeaucoup d'options disponibles pour vous permettre de personnaliser le CMS.\nVous avez des quantités très importantes de données à gérer.\n\nContre\n\nPas de gestion de version dans Git, ni d'intégration dans le workflow de développement.\nVa 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.\nDépendance aux développeurs pour des gros changements.\n\nMaintenant 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.\nLes bénéfices des CMS basés sur Git\nLa gestion de version multi-objets\nLes 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.\nCette 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.\nBien 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.\nLa 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é.\nC'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.\nDépôt distribué\nContrairement 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.\nLa gestion de version distribuée et le flux de développement sont simples et rapides.\nAvec 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.\nRamifications\nGrâ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.\nLes 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.\nNdT: 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.\n\n\n\nLes bénéfices des CMS basés sur des APIs\nAtteindre les consommateurs sur des terminaux variés\nBeaucoup 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.\nLes 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.\nVous pouvez alors fournir différentes expériences sur absolument n'importe quel périphérique sans restriction aucune.\nMeilleure intégration pour le marketing\nDans 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.\nRediffusion du contenu plus rapide\nAvec 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.\nLes défis posés par les CMS basés sur Git\nAdopter des mesures spécifiques pour le SEO\nFaute 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.\nLes limitations de GitHub Pages\nGitHub 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 2.\nLes défis posés par les CMS basés sur des APIs\nUne grande dépendance aux développeurs web\nCré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. 3\n(Pour certains) la prévisualisation de contenu est problématique\nLes 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.\nLes coûts\nVous 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.\nAlors quel CMS headless devez vous choisir ?\nCe 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.\nBien 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.\nListe de plate-formes CMS basées sur Git\n\nForestry - https:\/\/forestry.io\nNetlify CMS - https:\/\/www.netlifycms.org\nTinaCMS - https:\/\/tinacms.org\nPublii - https:\/\/getpublii.com\nProse - http:\/\/prose.io\nCrafter CMS - https:\/\/craftercms.org\n\nListe de plates-formes CMS basées sur des APis\n\nSanity - https:\/\/sanity.io\nDato CMS - https:\/\/www.datocms.com\/\nStrapi - https:\/\/strapi.io\nStoryblok - https:\/\/www.storyblok.com\/\nPrismic - https:\/\/prismic.io\nContentful - https:\/\/www.contentful.com\nGhost - https:\/\/ghost.org\nCloud CMS - https:\/\/www.cloudcms.com\nDirectus - https:\/\/directus.io\nRooftop - https:\/\/www.rooftopcms.com\n\n\n\n\n\nNdT: Les CMS basés sur Git, utilisent eux aussi une API pour communiquer avec votre dépôt Git, et vous permettent également de générer manuellement une API à consommer depuis différents terminaux clients. ↩\n\n\nIl existe d'autres solutions dédiées pour le déploiement de sites statiques comme Netlify ou Vercel pour n'en citer que deux. ↩\n\n\nC'est aussi vrai pour les CMS basés sur Git, le moindre changement apporté dans la structure de données devra être reporté pour être affiché sur le site généré. ↩\n\n\n", "content_html": "\n

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.

\n

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.

\n

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

\n

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. 1

\n

Les CMS basés sur Git

\n\n\n\n\"Les\n\n

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.

\n

Pour

\n\n

Contre

\n\n

Les CMS API-first

\n\n\n\n\"Les\n\n

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.

\n

Pour

\n\n

Contre

\n\n

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.

\n

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

\n

La gestion de version multi-objets

\n

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.

\n

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.

\n

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.

\n

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é.

\n

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.

\n

Dépôt distribué

\n

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.

\n

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

\n

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.

\n

Ramifications

\n

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.

\n

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.

\n

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.

\n

\n\n

\n

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

\n

Atteindre les consommateurs sur des terminaux variés

\n

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.

\n

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.

\n

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

\n

Meilleure intégration pour le marketing

\n

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.

\n

Rediffusion du contenu plus rapide

\n

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.

\n

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

\n

Adopter des mesures spécifiques pour le SEO

\n

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.

\n

Les limitations de GitHub Pages

\n

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 2.

\n

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

\n

Une grande dépendance aux développeurs web

\n

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. 3

\n

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

\n

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.

\n

Les coûts

\n

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.

\n

Alors quel CMS headless devez vous choisir ?

\n

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.

\n

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.

\n

Liste de plate-formes CMS basées sur Git

\n\n

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

\n\n
\n
\n
    \n
  1. \n

    NdT: Les CMS basés sur Git, utilisent eux aussi une API pour communiquer avec votre dépôt Git, et vous permettent également de générer manuellement une API à consommer depuis différents terminaux clients. ↩

    \n
    2. \n
  2. \n

    Il existe d'autres solutions dédiées pour le déploiement de sites statiques comme Netlify ou Vercel pour n'en citer que deux. ↩

    \n
    3. \n
  3. \n

    C'est aussi vrai pour les CMS basés sur Git, le moindre changement apporté dans la structure de données devra être reporté pour être affiché sur le site généré. ↩

    \n
    4. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/09/28/navigation-multilingue-eleventy/", "url": "https://jamstatic.fr/2019/09/28/navigation-multilingue-eleventy/", "title": "Navigation multilingue avec Eleventy", "summary": "Une approche pour gérer la navigation sur un site Jamstack multilingue généré avec Eleventy.", "date_published": "2019-09-28T00:00:00+00:00","content_text": "Mise en place\nDé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.\nIl 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.\nNotre 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.\nIci, nous utilisons Eleventy, mais l'approche serait similaire avec d'autres générateurs de site statique.\nPour parvenir à nos fins, il nous faut :\n\nPouvoir boucler sur les différents langages utilisés sur le site\nNous 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.\nDéfinir une clé commune unique nommée translationKey pour relier les traductions d'un contenu entre elles.\n\nLes langues du site\nNous 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.\nmodule.exports = {\n title: \"Webstoemp\",\n description:\n \"Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.\",\n url: \"https:\/\/www.webstoemp.com\",\n baseUrl: \"\/\",\n author: \"Jerôme Coupé\",\n authorTwitter: \"@jeromecoupe\",\n buildTime: new Date(),\n languages: [\n {\n label: \"english\",\n code: \"en\",\n },\n {\n label: \"français\",\n code: \"fr\",\n },\n ],\n};\nÀ 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.\nAjout des clés de traduction\nMaintenant 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.\nPar exemple, pour connecter entre elles nos pages de contact dans différentes langues, nous pouvons utiliser :\n.\/src\/en\/pages\/about.njk\n---\npermalink: \"\/{{ locale }}\/about\/index.html\"\ntranslationKey: \"about-page\"\n---\n.\/src\/fr\/pages\/about.njk\n---\npermalink: \"\/{{ locale }}\/a-propos\/index.html\"\ntranslationKey: \"about-page\"\n---\nNous pouvons appliquer le même principe à nos documents de collections, par exemple pour les articles de blog :\n.\/src\/en\/bogposts\/2019-09-12-my-awesome-blogpost.njk\n---\ntitle: \"My awesome blogpost\"\ntranslationKey: \"awesome-blogpost\"\n---\n.\/src\/fr\/bogposts\/2019-09-12-mon-magnifique-article-de-blog.njk\n---\ntitle: \"Mon magnifique article de blog\"\ntranslationKey: \"awesome-blogpost\"\n---\nNous disposons maintenant d'une relation explicite entre les traductions de nos contenus en différentes langues.\nCoder notre sélecteur de langue\nVoici le détail de ce que nous allons faire avec ce petit morceau de code:\n\nBoucler sur toutes les langues déclarées de notre site\nDé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.\nDans cette boucle, parcourir tous les contenues du site. Eleventy nous fourni une méthode très pratique avec collections.all.\nPour 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.\nUtiliser les valeurs de translatedUrl pour créer les liens de notre sélecteur de langue.\n\n{# Boucler sur les langues du site #}\n{% for lgg in site.languages %}\n {% if loop.first %}<ul class=\"c-lggnav\">{% endif %}\n\n {# Définir translatedUrl à la page d'accueil de cette langue par défaut #}\n {% set translatedUrl = \"\/\" + lgg.code + \"\/\" %}\n\n {# Définir la classe de la langue active #}\n {% set activeClass = \"is-active\" if lgg.code == locale else \"\" %}\n\n {# Parcourir tous les contenus du site #}\n {% for item in collections.all %}\n\n {# Pour chaque contenu, vérifier si\n - la valeur de sa translationKey correspond à celle du contenu en cours\n - sa locale correspond au code de langue parcourue #}\n {% if item.data.translationKey == translationKey and item.data.locale == lgg.code %}\n {% set translatedUrl = item.url %}\n {% endif %}\n\n {% endfor %}\n\n <li class=\"c-lggnav__item\">\n <a class=\"c-lggnav__link {{ activeClass }}\" href=\"{{ translatedUrl }}\">{{ lgg.label }}<\/a>\n <\/li>\n\n {% if loop.last %}<\/ul>{% endif %}\n{% endfor %}\nEt 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.", "content_html": "

Mise en place

\n

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.

\n

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.

\n

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.

\n

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

\n

Pour parvenir à nos fins, il nous faut :

\n
    \n
  1. Pouvoir boucler sur les différents langages utilisés sur le site
    2. \n
  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. \n
  3. Définir une clé commune unique nommée translationKey pour relier les traductions d'un contenu entre elles.
    4. \n
\n

Les langues du site

\n

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.

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

À 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.

\n

Ajout des clés de traduction

\n

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.

\n

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

\n

./src/en/pages/about.njk

\n
---\npermalink: \"/{{ locale }}/about/index.html\"\ntranslationKey: \"about-page\"\n---
\n

./src/fr/pages/about.njk

\n
---\npermalink: \"/{{ locale }}/a-propos/index.html\"\ntranslationKey: \"about-page\"\n---
\n

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

\n

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

\n
---\ntitle: \"My awesome blogpost\"\ntranslationKey: \"awesome-blogpost\"\n---
\n

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

\n
---\ntitle: \"Mon magnifique article de blog\"\ntranslationKey: \"awesome-blogpost\"\n---
\n

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

\n

Coder notre sélecteur de langue

\n

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

\n
    \n
  1. Boucler sur toutes les langues déclarées de notre site
    2. \n
  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. \n
  3. Dans cette boucle, parcourir tous les contenues du site. Eleventy nous fourni une méthode très pratique avec collections.all.
    4. \n
  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. \n
  5. Utiliser les valeurs de translatedUrl pour créer les liens de notre sélecteur de langue.
    6. \n
\n
{# Boucler sur les langues du site #}\n{% for lgg in site.languages %}\n  {% if loop.first %}<ul class=\"c-lggnav\">{% endif %}\n\n  {# Définir translatedUrl à la page d'accueil de cette langue par défaut #}\n  {% set translatedUrl = \"/\" + lgg.code + \"/\" %}\n\n  {# Définir la classe de la langue active #}\n  {% set activeClass = \"is-active\" if lgg.code == locale else \"\" %}\n\n  {# Parcourir tous les contenus du site #}\n  {% for item in collections.all %}\n\n    {# Pour chaque contenu, vérifier si\n    - la valeur de sa translationKey correspond à celle du contenu en cours\n    - sa locale correspond au code de langue parcourue #}\n    {% if item.data.translationKey == translationKey and item.data.locale == lgg.code %}\n      {% set translatedUrl = item.url %}\n    {% endif %}\n\n  {% endfor %}\n\n  <li class=\"c-lggnav__item\">\n    <a class=\"c-lggnav__link  {{ activeClass }}\" href=\"{{ translatedUrl }}\">{{ lgg.label }}</a>\n  </li>\n\n  {% if loop.last %}</ul>{% endif %}\n{% endfor %}
\n

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.

", "authors": [ { "name": "jerome" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/09/08/requeter-api-graphql-eleventy/", "url": "https://jamstatic.fr/2019/09/08/requeter-api-graphql-eleventy/", "title": "Consommer l'API GraphQL d'un CMS headless avec Eleventy", "summary": "Eleventy permet de récupérer les données d'une API GraphQL pour générer des pages statiques, en lieu et place des fichiers Markdown.", "date_published": "2019-09-08T21:00:48+00:00", "date_modified": "2019-09-08T21:00:48+00:00","content_text": "Les différents types de CMS headless\nSi 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.\nDans 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.\nLes CMS headless basés sur Git\nLes 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 :\n\ncode et contenu partagent le même workflow\nle contenu est versionné par Git avec un historique clair\nle contenu stocké sous forme de fichiers texte (markdown, YAML, JSON, etc.) est extrêmement portable\n\nLes APIs de CMS headless\nLes 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 :\n\nle contenu est destiné à être publié sur différentes plateformes\nvos modèles de données sont hautement relationnels\n\nStructure du projet\nEleventy(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.\nQui 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 ?\nDatoCMS 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.\nSi cet article est écrit pour DatoCMS, cette méthodologie est appliquable à tout CMS headless offrant une API GraphQL.\nVoici l'arborescence de fichiers classique avec laquelle nous allons travailler dans Eleventy :\n+-- src\n +-- _data\n +-- blogposts.js\n +-- _includes\n +-- layouts\n +-- base.njk\n +-- blogposts\n +-- entry.njk\n +-- list.njk\n+-- .eleventy.js\n+-- .env\n+-- .env.example\n+-- package-lock.json\n+-- package.json\nConfiguration de DatoCMS\nAprè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.\nNous 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é.\nUne fois encore, la plupart des CMS headless avec une API GraphQL offrent cette fonctionnalité d'une manière ou d'une autre.\nConfiguration d'Eleventy\nNous 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 :\nDATOCMS_TOKEN=\"fak3t0k3n3c52750d04b3d92383b1d\"\nEnsuite, il nous faut ajouter la ligne suivant au début de notre fichier de configuration .eleventy.js :\nrequire(\"dotenv\").config();\nÉ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.\nUtilisation des fichiers de données JavaScript\nAu 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.\nEleventy sera alors en mesure d'utiliser ce fichier JSON pour générer les pages de détail et d'index de notre blog.\nÇ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.\nAfin de miniser les dépendances, j'ai privilégié l'utilisation de node-fetch à celle d'Appolo et consorts.\nPar 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.\n\/\/ paquets requis\nconst fetch = require(\"node-fetch\");\n\n\/\/ token de DatoCMS\nconst token = process.env.DATOCMS_TOKEN;\n\n\/\/ récupération des articles de blog\n\/\/ voir https:\/\/www.datocms.com\/docs\/content-delivery-api\/first-request#vanilla-js-example\nasync function getAllBlogposts() {\n \/\/ nombre maximal d'enregistrements retournés par requête\n const recordsPerQuery = 100;\n\n \/\/ nombre d'enregistrements à ignorer (démarre à 0)\n let recordsToSkip = 0;\n\n \/\/ Devons nous faire une nouvelle requête ?\n let makeNewQuery = true;\n\n \/\/ Tableau pour stocker les articles de blog\n let blogposts = [];\n\n \/\/ Effectuer des requpêtes jusqu'à ce que makeNewQuery passe à faux\n while (makeNewQuery) {\n try {\n \/\/ Initialisation du téléchargement\n const dato = await fetch(\"https:\/\/graphql.datocms.com\/\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application\/json\",\n Accept: \"application\/json\",\n Authorization: `Bearer ${token}`\n },\n body: JSON.stringify({\n query: `{\n allBlogposts(\n first: ${recordsPerQuery},\n skip: ${recordsToSkip},\n orderBy: _createdAt_DESC,\n filter: {\n _status: {eq: published}\n }\n )\n {\n id\n title\n slug\n intro\n body(markdown: true)\n _createdAt\n image {\n url\n alt\n }\n relatedBlogs {\n id\n }\n }\n }`\n })\n });\n\n \/\/ Enregistrment de la réponse JSON lorsque la promesse est résolue\n const response = await dato.json();\n\n \/\/ Gestion des erreurs DatoCMS\n if (response.errors) {\n let errors = response.errors;\n errors.map((error) => {\n console.log(error.message);\n });\n throw new Error(\"Aborting: DatoCMS errors\");\n }\n\n \/\/ mise à jour du tableau des articles avec les données retournées par la réponse en JSON\n blogposts = blogposts.concat(response.data.allBlogposts);\n\n \/\/ itération des valeurs pour la prochaine requête\n recordsToSkip += recordsPerQuery;\n\n \/\/ Vérification du nombre d'enregistrements retourné\n \/\/ S'il y en a moins de 100, on arrête de faire des requêtes\n if (response.data.allBlogposts.length < recordsPerQuery) {\n makeNewQuery = false;\n }\n } catch (error) {\n throw new Error(error);\n }\n }\n\n \/\/ mise en forme de l'objet blogposts\n const blogpostsFormatted = blogposts.map((item) => {\n return {\n id: item.id,\n date: item._createdAt,\n title: item.title,\n slug: item.slug,\n image: item.image.url,\n imageAlt: item.image.alt,\n summary: item.intro,\n body: item.body,\n relatedBlogs: item.relatedBlogs\n };\n });\n\n \/\/ retour de l'objet formatté\n return blogpostsFormatted;\n}\n\n\/\/ export pour 11ty\nmodule.exports = getAllBlogposts;\nPlutô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.\nLes images et les vignettes\nLes 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.\nLa 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.\nChamps relationnels\nL'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 :\n\nJe 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.\nPour les champs relationnels, je récupère seulement l'identifiants des élements relatifs.\nJ'utilise des boucles imbriquées dans les templates pour récupérer les données à l'aide des identifiants.\n\nComme 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.\nGénérer une liste paginée des articles de blog avec 11ty\nGrâ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.\nVoici le code complet du fichier src\/blogposts\/list.njk :\n---\npagination:\n data: blogposts\n size: 12\npermalink: blog{% if pagination.pageNumber > 0 %}\/page{{ pagination.pageNumber + 1}}{% endif %}\/index.html\n---\n\n{% extends \"layouts\/base.njk\" %}\n{% set htmlTitle = item.title %}\n\n{% block content %}\n <h1>Blogposts<\/h1>\n\n {# boucler sur les éléments paginés #}\n {% for item in pagination.items %}\n {% if loop.first %}<ul>{% endif %}\n <li>\n <p><img src=\"{{ item.image }}?fit=crop&amp;w=200&amp;h=200\" alt=\"{{ item.imageAlt }}\"><\/p>\n <h2><a href=\"\/blog\/{{ item.slug }}\">{{ item.title }}<\/a><\/h2>\n <p><time datetime=\"{{ item.date | date('Y-M-DD') }}\">{{ item.date|date(\"MMMM Do, Y\") }}<\/time><\/p>\n <p>{{ item.summary }}<\/p>\n <\/li>\n {% if loop.last %}<\/ul>{% endif %}\n {% endfor %}\n\n {# pagination #}\n {% if pagination.hrefs | length > 0 %}\n <ul>\n {% if pagination.previousPageHref %}\n <li><a href=\"{{ pagination.previousPageHref }}\">Previous page<\/a><\/li>\n {% endif %}\n {% if pagination.nextPageHref %}\n <li><a href=\"{{ pagination.nextPageHref }}\">Next page<\/a><\/li>\n {% endif %}\n <\/ul>\n {% endif %}\n\n{% endblock %}\nGénérer les pages individuelles pour les articles dans 11ty\nNous 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:\n---\npagination:\n data: blogposts\n size: 1\n alias: blogpost\npermalink: blog\/{{ blogpost.slug }}\/index.html\n---\n{% extends \"layouts\/base.njk\" %}\n{% set htmlTitle = blogpost.title %}\n\n{% block content %}\n {# blogpost #}\n <img src=\"{{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576\"\n srcset=\"{{ blogpost.image }}?fit=crop&amp;w=600&amp;h=338 600w,\n {{ blogpost.image }}?fit=crop&amp;w=800&amp;h=450 800w,\n {{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576 1024w\"\n sizes=\"100vw\"\n class=\"u-fluidimg\"\n alt=\"{{ blogpost.imageAlt }}\">\n\n <h1>{{ blogpost.title }}<\/h1>\n <p><time datetime=\"{{ blogpost.date | date('Y-M-DD') }}\">{{ blogpost.date|date(\"MMMM Do, Y\") }}<\/time><\/p>\n <p>{{ blogpost.intro }}<\/p>\n {{ blogpost.body | safe }}\n\n {# Articles relatifs #}\n {% if blogpost.relatedBlogs|length %}\n <h2>Vous pourriez aussi aimer<\/h2>\n <ul>\n {% for item in blogpost.relatedBlogs %}\n {% for post in blogposts %}\n {% if post.id == item.id %}\n <li>\n <a href=\"\/blog\/{{ post.slug }}\">{{ post.title }}<\/a>\n <\/li>\n {% endif %}\n {% endfor %}\n {% endfor %}\n <\/ul>\n {% endif %}\n{% endblock %}\nDéclencher automatiquement les builds\nLa 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.\nDatoCMS 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.\nNous 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.", "content_html": "

Les différents types de CMS headless

\n

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.

\n

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.

\n

Les CMS headless basés sur Git

\n

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 :

\n\n

Les APIs de CMS headless

\n

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 :

\n\n

Structure du projet

\n

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.

\n

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 ?

\n

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.

\n

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

\n

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

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

Configuration de DatoCMS

\n

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.

\n

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é.

\n

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

\n

Configuration d'Eleventy

\n

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 :

\n
DATOCMS_TOKEN=\"fak3t0k3n3c52750d04b3d92383b1d\"
\n

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

\n
require(\"dotenv\").config();
\n

É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.

\n

Utilisation des fichiers de données JavaScript

\n

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.

\n

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.

\n

Ç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.

\n

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

\n

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.

\n
// paquets requis\nconst fetch = require(\"node-fetch\");\n\n// token de DatoCMS\nconst token = process.env.DATOCMS_TOKEN;\n\n// récupération des articles de blog\n// voir https://www.datocms.com/docs/content-delivery-api/first-request#vanilla-js-example\nasync function getAllBlogposts() {\n  // nombre maximal d'enregistrements retournés par requête\n  const recordsPerQuery = 100;\n\n  // nombre d'enregistrements à ignorer (démarre à 0)\n  let recordsToSkip = 0;\n\n  // Devons nous faire une nouvelle requête ?\n  let makeNewQuery = true;\n\n  // Tableau pour stocker les articles de blog\n  let blogposts = [];\n\n  // Effectuer des requpêtes jusqu'à ce que makeNewQuery passe à faux\n  while (makeNewQuery) {\n    try {\n      // Initialisation du téléchargement\n      const dato = await fetch(\"https://graphql.datocms.com/\", {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Accept: \"application/json\",\n          Authorization: `Bearer ${token}`\n        },\n        body: JSON.stringify({\n          query: `{\n            allBlogposts(\n              first: ${recordsPerQuery},\n              skip: ${recordsToSkip},\n              orderBy: _createdAt_DESC,\n              filter: {\n                _status: {eq: published}\n              }\n            )\n            {\n              id\n              title\n              slug\n              intro\n              body(markdown: true)\n              _createdAt\n              image {\n                url\n                alt\n              }\n              relatedBlogs {\n                id\n              }\n            }\n          }`\n        })\n      });\n\n      // Enregistrment de la réponse JSON lorsque la promesse est résolue\n      const response = await dato.json();\n\n      // Gestion des erreurs DatoCMS\n      if (response.errors) {\n        let errors = response.errors;\n        errors.map((error) => {\n          console.log(error.message);\n        });\n        throw new Error(\"Aborting: DatoCMS errors\");\n      }\n\n      // mise à jour du tableau des articles avec les données retournées par la réponse en JSON\n      blogposts = blogposts.concat(response.data.allBlogposts);\n\n      // itération des valeurs pour la prochaine requête\n      recordsToSkip += recordsPerQuery;\n\n      // Vérification du nombre d'enregistrements retourné\n      // S'il y en a moins de 100, on arrête de faire des requêtes\n      if (response.data.allBlogposts.length < recordsPerQuery) {\n        makeNewQuery = false;\n      }\n    } catch (error) {\n      throw new Error(error);\n    }\n  }\n\n  // mise en forme de l'objet blogposts\n  const blogpostsFormatted = blogposts.map((item) => {\n    return {\n      id: item.id,\n      date: item._createdAt,\n      title: item.title,\n      slug: item.slug,\n      image: item.image.url,\n      imageAlt: item.image.alt,\n      summary: item.intro,\n      body: item.body,\n      relatedBlogs: item.relatedBlogs\n    };\n  });\n\n  // retour de l'objet formatté\n  return blogpostsFormatted;\n}\n\n// export pour 11ty\nmodule.exports = getAllBlogposts;
\n

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.

\n

Les images et les vignettes

\n

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.

\n

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.

\n

Champs relationnels

\n

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 :

\n\n

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.

\n

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

\n

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.

\n

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

\n
---\npagination:\n  data: blogposts\n  size: 12\npermalink: blog{% if pagination.pageNumber > 0 %}/page{{ pagination.pageNumber + 1}}{% endif %}/index.html\n---\n\n{% extends \"layouts/base.njk\" %}\n{% set htmlTitle = item.title %}\n\n{% block content %}\n  <h1>Blogposts</h1>\n\n  {# boucler sur les éléments paginés #}\n  {% for item in pagination.items %}\n    {% if loop.first %}<ul>{% endif %}\n      <li>\n        <p><img src=\"{{ item.image }}?fit=crop&amp;w=200&amp;h=200\" alt=\"{{ item.imageAlt }}\"></p>\n        <h2><a href=\"/blog/{{ item.slug }}\">{{ item.title }}</a></h2>\n        <p><time datetime=\"{{ item.date | date('Y-M-DD') }}\">{{ item.date|date(\"MMMM Do, Y\") }}</time></p>\n        <p>{{ item.summary }}</p>\n      </li>\n    {% if loop.last %}</ul>{% endif %}\n  {% endfor %}\n\n  {# pagination #}\n  {% if pagination.hrefs | length > 0 %}\n  <ul>\n    {% if pagination.previousPageHref %}\n      <li><a href=\"{{ pagination.previousPageHref }}\">Previous page</a></li>\n    {% endif %}\n    {% if pagination.nextPageHref %}\n      <li><a href=\"{{ pagination.nextPageHref }}\">Next page</a></li>\n    {% endif %}\n  </ul>\n  {% endif %}\n\n{% endblock %}
\n

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

\n

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:

\n
---\npagination:\n  data: blogposts\n  size: 1\n  alias: blogpost\npermalink: blog/{{ blogpost.slug }}/index.html\n---\n{% extends \"layouts/base.njk\" %}\n{% set htmlTitle = blogpost.title %}\n\n{% block content %}\n  {# blogpost #}\n  <img src=\"{{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576\"\n       srcset=\"{{ blogpost.image }}?fit=crop&amp;w=600&amp;h=338 600w,\n               {{ blogpost.image }}?fit=crop&amp;w=800&amp;h=450 800w,\n               {{ blogpost.image }}?fit=crop&amp;w=1024&amp;h=576 1024w\"\n       sizes=\"100vw\"\n       class=\"u-fluidimg\"\n       alt=\"{{ blogpost.imageAlt }}\">\n\n  <h1>{{ blogpost.title }}</h1>\n  <p><time datetime=\"{{ blogpost.date | date('Y-M-DD') }}\">{{ blogpost.date|date(\"MMMM Do, Y\") }}</time></p>\n  <p>{{ blogpost.intro }}</p>\n  {{ blogpost.body | safe }}\n\n  {# Articles relatifs #}\n  {% if blogpost.relatedBlogs|length %}\n    <h2>Vous pourriez aussi aimer</h2>\n    <ul>\n    {% for item in blogpost.relatedBlogs %}\n      {% for post in blogposts %}\n        {% if post.id == item.id %}\n          <li>\n            <a href=\"/blog/{{ post.slug }}\">{{ post.title }}</a>\n          </li>\n        {% endif %}\n      {% endfor %}\n    {% endfor %}\n    </ul>\n  {% endif %}\n{% endblock %}
\n

Déclencher automatiquement les builds

\n

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.

\n

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.

\n

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.

", "authors": [ { "name": "jerome" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/09/07/site-multilingue-avec-eleventy/", "url": "https://jamstatic.fr/2019/09/07/site-multilingue-avec-eleventy/", "title": "Un site multilingue avec Eleventy", "summary": "Comment gérer plusieurs langues sur son site Eleventy à l'aide de fichiers de données et de collections.", "date_published": "2019-09-07T12:27:07+00:00", "date_modified": "2019-09-07T12:27:07+00:00","content_text": "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.\nAfin d'illustrer notre propos, nous allons développer un blog multilingue tout ce qu'il y a de plus classique.\nVoici 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.\n+-- src\n +-- _data\n +-- site.js\n +-- footer.js\n +-- header.js\n +-- _includes\n +-- layouts\n +-- base.njk\n +-- partials\n +-- header.njk\n +-- footer.njk\n +-- en\n +-- pages\n +-- index.html\n +-- blog.html\n +-- contact.html\n +-- posts\n +-- yyyy-mm-dd-some-blogpost.md\n +-- posts.json\n +-- en.json\n +-- fr\n +-- pages\n +-- index.html\n +-- blog.html\n +-- contact.html\n +-- posts\n +-- yyyy-mm-dd-some-blogpost.md\n +-- posts.json\n +-- fr.json\n+-- .eleventy.js\nDéfinition des locales\nLa première consiste à créer nos locales à l'aide des fichiers de données pour les répertoires.\nPour 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.\nPar exemple, notre fichier fr.json contient :\n{\n \"locale\": \"fr\"\n}\n{{ 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.\nFiltre de localisation de date\nNunjucks 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.\nPour ce faire, nous allons insérer le code suivant dans notre fichier de configueration eleventy.js :\n\/\/ date filter (localized)\neleventyConfig.addNunjucksFilter(\"date\", function (date, format, locale) {\n locale = locale ? locale : \"en\";\n moment.locale(locale);\n return moment(date).format(format);\n});\nÀ 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 :\n<p><time datetime=\"{{ post.date | date('Y-MM-DD') }}\">{{ post.item|date(\"DD MMMM Y\", locale) }}<\/time><\/p>\nMaintenant que nos dates sont automatiquement localisées, passons aux collections.\nLocalisation des collections\nNous 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.\nmodule.exports = function (eleventyConfig) {\n eleventyConfig.addCollection(\"posts_en\", function (collection) {\n return collection.getFilteredByGlob(\".\/src\/en\/posts\/*.md\");\n });\n};\n\nmodule.exports = function (eleventyConfig) {\n eleventyConfig.addCollection(\"posts_fr\", function (collection) {\n return collection.getFilteredByGlob(\".\/src\/fr\/posts\/*.md\");\n });\n};\nComme 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.\nPlutô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:\n{\n permalink: \"\/{{ locale }}\/blog\/{{ page.fileslug }}\/index.html\";\n}\nNous 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.\n{% for post in collections.posts_en | reverse %}\n {% if loop.first %}<ul>{% endif %}\n <li>\n\n <article>\n <p><time datetime=\"{{ post.date | date('Y-MM-DD') }}\">{{ post.date | date(\"DD MMMM[,] Y\", locale) }}<\/time><\/p>\n <h3><a href=\"{{ post.url }}\">{{ post.data.title }}<\/a><\/h3>\n <\/article>\n\n <\/li>\n\n {% if loop.last %}<\/ul>{% endif %}\n{% endfor %}\nNotez 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.\n{% set posts = collections[\"posts_\" + locale] %}\n{% for post in posts %}\n {# loop content #}\n{% endfor %}\nLocalisation des layouts et des fichiers partiels\nAlors 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.\nFort 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.\nLayouts\nCommençons par un exemple dans un fichier de layout.\nLe fichier .\/src\/_data\/site.js va rendre accessibles des variables via l'objet site.\nmodule.exports = {\n buildTime: new Date(),\n baseUrl: \"https:\/\/www.mysite.com\",\n name: \"mySite\",\n twitter: \"@handle\",\n en: {\n metaTitle: \"Title in english\",\n metaDescription: \"Description in english\",\n },\n fr: {\n metaTitle: \"Titre en français\",\n metaDescription: \"Description en français\",\n },\n};\nNous 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.\n---\npermalink: \/{{ locale }}\/index.html\n---\n\n{% extends \"layouts\/base.njk\" %}\n\n{% set metaTitle = site[locale].metaTitle %}\n{% set metaDescription = site[locale].metaDescription %}\n{% set metaImage = site[locale].metaImage %}\n\n{% block content %}\n {# page content #}\n{% endblock %}\nPuisque 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.\n<!DOCTYPE html>\n<html lang=\"{{ locale }}\">\n<head>\n <meta charset=\"utf-8\">\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">\n <title>{{ metaTitle }}<\/title>\n <link rel=\"stylesheet\" href=\"\/css\/main.min.css\">\n\n <!-- open graph -->\n <meta property=\"og:type\" content=\"article\">\n <meta property=\"og:title\" content=\"{{ metaTitle }}\">\n <meta property=\"og:image\" content=\"{{ metaImage }}\">\n <meta property=\"og:site_name\" content=\"{{ site.name }}\">\n <meta property=\"og:description\" content=\"{{ metaDescription }}\">\n\n <!-- twitter -->\n <meta name=\"twitter:card\" content=\"summary\">\n <meta name=\"twitter:site\" content=\"{{ site.twitter }}\">\n <meta name=\"twitter:title\" content=\"{{ metaTitle }}\">\n <meta name=\"twitter:description\" content=\"{{ metaDescription }}\">\n <meta name=\"twitter:image\" content=\"{{ metaImage }}\">\n<\/head>\n<body>\n {% include \"partials\/siteheader.njk\" %}\n {% block content %}{% endblock %}\n {% include \"partials\/sitefooter.njk\" %}\n<\/body>\n<\/html>\nFichiers partiels\nLa traduction de fichiers partiels comme .\/src\/_includes\/partials\/footer.njk est basée sur le même principe.\nPremièrement, nous créons un fichier .\/data\/footer.js et nous utilisons nos locales comme clés.\nmodule.exports = {\n mapUrl: \"https:\/\/goo.gl\/maps\/3YTkhCgfEgj1PRAd7\",\n fr: {\n addressTitle: \"Adresse\",\n addressStreet: \"Rue du marché\",\n addressNumber: \"42\",\n addressPostcode: \"1000\",\n addressCity: \"Bruxelles\",\n directionsLabel: \"Itinéraire\",\n },\n en: {\n addressTitle: \"Address\",\n addressStreet: \"Market street\",\n addressNumber: \"42\",\n addressPostcode: \"1000\",\n addressCity: \"Brussels\",\n directionsLabel: \"Directions\",\n },\n};\nEnsuite 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.\n<footer>\n <h2>{{ footer[locale].addressTitle }}<\/h2>\n <p>\n {{ footer[locale].addressStreet }}, {{ footer[locale].addressNumber }}<br>\n {{ footer[locale].addressPostcode }}, {{ footer[locale].addressCity }}\n <\/p>\n <p><a href=\"{{ footer.mapUrl }}\">{{ footer[locale].directionsLabel }}<\/a><\/p>\n<\/footer>\nEt voilà, nous avons maintenant un pied de page traduit en plusieurs langues.\nFlexible par nature\nLes 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.", "content_html": "\n

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

\n

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.

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

Définition des locales

\n

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

\n

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.

\n

Par exemple, notre fichier fr.json contient :

\n
{\n  \"locale\": \"fr\"\n}
\n

{{ 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.

\n

Filtre de localisation de date

\n

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.

\n

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

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

À 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 :

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

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

\n

Localisation des collections

\n

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.

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

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.

\n

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:

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

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.

\n
{% for post in collections.posts_en | reverse %}\n  {% if loop.first %}<ul>{% endif %}\n    <li>\n\n      <article>\n        <p><time datetime=\"{{ post.date | date('Y-MM-DD') }}\">{{ post.date | date(\"DD MMMM[,] Y\", locale) }}</time></p>\n        <h3><a href=\"{{ post.url }}\">{{ post.data.title }}</a></h3>\n      </article>\n\n    </li>\n\n  {% if loop.last %}</ul>{% endif %}\n{% endfor %}
\n

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.

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

Localisation des layouts et des fichiers partiels

\n

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.

\n

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.

\n

Layouts

\n

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

\n

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

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

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.

\n
---\npermalink: /{{ locale }}/index.html\n---\n\n{% extends \"layouts/base.njk\" %}\n\n{% set metaTitle = site[locale].metaTitle %}\n{% set metaDescription = site[locale].metaDescription %}\n{% set metaImage = site[locale].metaImage %}\n\n{% block content %}\n  {# page content #}\n{% endblock %}
\n

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.

\n
<!DOCTYPE html>\n<html lang=\"{{ locale }}\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">\n  <title>{{ metaTitle }}</title>\n  <link rel=\"stylesheet\" href=\"/css/main.min.css\">\n\n  <!-- open graph -->\n  <meta property=\"og:type\" content=\"article\">\n  <meta property=\"og:title\" content=\"{{ metaTitle }}\">\n  <meta property=\"og:image\" content=\"{{ metaImage }}\">\n  <meta property=\"og:site_name\" content=\"{{ site.name }}\">\n  <meta property=\"og:description\" content=\"{{ metaDescription }}\">\n\n  <!-- twitter -->\n  <meta name=\"twitter:card\" content=\"summary\">\n  <meta name=\"twitter:site\" content=\"{{ site.twitter }}\">\n  <meta name=\"twitter:title\" content=\"{{ metaTitle }}\">\n  <meta name=\"twitter:description\" content=\"{{ metaDescription }}\">\n  <meta name=\"twitter:image\" content=\"{{ metaImage }}\">\n</head>\n<body>\n  {% include \"partials/siteheader.njk\" %}\n  {% block content %}{% endblock %}\n  {% include \"partials/sitefooter.njk\" %}\n</body>\n</html>
\n

Fichiers partiels

\n

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

\n

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

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

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.

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

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

\n

Flexible par nature

\n

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.

", "authors": [ { "name": "jerome" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/09/07/de-jekyll-a-eleventy/", "url": "https://jamstatic.fr/2019/09/07/de-jekyll-a-eleventy/", "title": "De Jekyll à Eleventy", "summary": "Retour d'expérience du passage de Jekyll à Eleventy.", "date_published": "2019-09-07T08:59:06+00:00", "date_modified": "2019-09-07T10:24:06+00:00","content_text": "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.\nJekyll 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.\nChoisir un générateur de site\nLes 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.\nMon 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.\nHugo\nÉ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.\nCependant, 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.\nEleventy\nCe 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).\nDe plus Eleventy supporte plusieurs langagues de templating.\nConfiguration\nJ'ai opté pour le moteur de templating Nunjucks de Mozilla. Outre cela, je n'avais besoin que de fichiers Markdown et HTML.\nNunjucks 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.\nconst moment = require(\"moment\");\n\n\/\/ limit filter\neleventyConfig.addNunjucksFilter(\"limit\", function (array, limit) {\n return array.slice(0, limit);\n});\n\n\/\/ date filter\neleventyConfig.addNunjucksFilter(\"date\", function (date, format) {\n return moment(date).format(format);\n});\nJ'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:\nsrc\/assets\/**\/*\nL'é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.\n\/\/ packages\nconst cp = require(\"child_process\");\n\n\/\/ Eleventy\nfunction build() {\n return cp.spawn(\"npx\", [\"eleventy\", \"--quiet\"], { stdio: \"inherit\" });\n}\nStructure de données\nCollections\nMon 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.\nEleventy 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.\nPar 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.\n{\n \"layout\": \"layouts\/blogpost.njk\",\n \"permalink\": \"blog\/{{ page.fileSlug }}\/index.html\"\n}\nLes 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.\n{\n \"permalink\": false\n}\nPour 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:\nconst moment = require(\"moment\");\n\nmodule.exports = function (eleventyConfig) {\n \/\/ blogpost collection\n eleventyConfig.addCollection(\"blogposts\", function (collection) {\n return collection.getFilteredByGlob(\".\/src\/blogposts\/*.md\");\n });\n\n \/\/ projects collection\n eleventyConfig.addCollection(\"projects\", function (collection) {\n return collection.getFilteredByGlob(\".\/src\/projects\/*.md\");\n });\n\n \/\/ limit filter\n eleventyConfig.addNunjucksFilter(\"limit\", function (array, limit) {\n return array.slice(0, limit);\n });\n\n \/\/ date filter\n eleventyConfig.addNunjucksFilter(\"date\", function (date, format) {\n return moment(date).format(format);\n });\n\n \/\/ Base config\n return {\n dir: {\n input: \"src\",\n output: \"dist\",\n },\n };\n};\nLes fichiers de données\nEleventy 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).\nJ'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.\nmodule.exports = {\n title: \"Webstoemp\",\n description:\n \"Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.\",\n url: \"https:\/\/www.webstoemp.com\",\n baseUrl: \"\/\",\n author: \"Jerôme Coupé\",\n authorTwitter: \"@jeromecoupe\",\n buildTime: new Date(),\n};\nLa valeur de site.buildTime peut maintenant être utilisée dans le pied de page du site :\n<div class=\"c-sitefooter__copyright\">\n <p class=\"u-margin-all-none\">&copy; Webstoemp {{ site.buildTime | date(\"Y\") }}<\/p>\n<\/div>\nLayouts Nunjucks\nJ'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.\nBlogposts\nBoucler sur la collection blogposts pour afficher les titres et les dates de publication n'est pas très compliqué:\n{% for post in collections.blogposts | reverse %}\n {% if loop.first %}<ul class=\"c-list-ui\">{% endif %}\n <li>\n <article class=\"c-blogteaser\">\n <p class=\"c-blogteaser__date\"><time datetime=\"{{ post.date | date('Y-M-DD') }}\">{{ post.date|date(\"MMMM Do, Y\") }}<\/time><\/p>\n <h2 class=\"c-blogteaser__title\"><a href=\"{{ post.url }}\">{{ post.data.title }}<\/a><\/h2>\n <\/article>\n <\/li>\n {% if loop.last %}<\/ul>{% endif %}\n{% else %}\n <p>No blogpost found<\/p>\n{% endfor %}\nJ'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 :\n{% extends \"layouts\/base.njk\" %}\n{% set activeSection = \"blog\" %}\n\n{% set metaTitle = title %}\n{% set metaDescription = excerpt %}\n{% set metaImage = site.url ~ \"\/img\/blogposts\/_600x600\/\" ~ image %}\n\n{% block content %}\n\n <article class=\"c-blogpost\">\n <div class=\"c-blogpost__media\">\n <div class=\"l-container\">\n\n <picture>\n <source media=\"(min-width: 500px)\"\n srcset=\"\/img\/blogposts\/_1024x576\/{{ image }} 1024w,\n \/img\/blogposts\/{{ image }} 1500w\"\n sizes=\"(min-width: 1140px) 1140px,\n 100vw\">\n <img src=\"\/img\/blogposts\/_600x600\/{{ image }}\"\n class=\"o-fluidimage\"\n alt=\"{{ imageAlt }}\">\n <\/picture>\n\n <\/div>\n <\/div>\n\n <div class=\"c-blogpost__body l-container l-container--narrow\">\n\n <header>\n <p class=\"c-suptitle c-suptitle--dark\"><time datetime=\"{{ page.date | date('Y-M-DD') }}\">{{ page.date | date(\"MMMM Do, YYYY\") }}<\/time><\/p>\n <h1 class=\"c-h1\">{{ title }}<\/h1>\n <div class=\"c-blogpost__intro\">\n <p>{{ excerpt }}<\/p>\n <\/div>\n <\/header>\n\n <div class=\"c-wysiwyg\">\n {{ content | safe }}\n <\/div>\n\n <\/div>\n <\/article>\n\n{% endblock %}\nProjects\nLa 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 :\n{% for project in collections.projects | reverse %}\n {{ project.templateContent | safe }}\n{% endfor %}\nSatisfait de mon choix\nAu 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.", "content_html": "\n

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.

\n

Choisir un générateur de site

\n

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.

\n

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.

\n

Hugo

\n

É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.

\n

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.

\n

Eleventy

\n

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).

\n

De plus Eleventy supporte plusieurs langagues de templating.

\n

Configuration

\n

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

\n

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.

\n
const moment = require(\"moment\");\n\n// limit filter\neleventyConfig.addNunjucksFilter(\"limit\", function (array, limit) {\n  return array.slice(0, limit);\n});\n\n// date filter\neleventyConfig.addNunjucksFilter(\"date\", function (date, format) {\n  return moment(date).format(format);\n});
\n

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:

\n
src/assets/**/*
\n

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.

\n
// packages\nconst cp = require(\"child_process\");\n\n// Eleventy\nfunction build() {\n  return cp.spawn(\"npx\", [\"eleventy\", \"--quiet\"], { stdio: \"inherit\" });\n}
\n

Structure de données

\n

Collections

\n

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.

\n

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.

\n

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.

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

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.

\n
{\n  \"permalink\": false\n}
\n

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:

\n
const moment = require(\"moment\");\n\nmodule.exports = function (eleventyConfig) {\n  // blogpost collection\n  eleventyConfig.addCollection(\"blogposts\", function (collection) {\n    return collection.getFilteredByGlob(\"./src/blogposts/*.md\");\n  });\n\n  // projects collection\n  eleventyConfig.addCollection(\"projects\", function (collection) {\n    return collection.getFilteredByGlob(\"./src/projects/*.md\");\n  });\n\n  // limit filter\n  eleventyConfig.addNunjucksFilter(\"limit\", function (array, limit) {\n    return array.slice(0, limit);\n  });\n\n  // date filter\n  eleventyConfig.addNunjucksFilter(\"date\", function (date, format) {\n    return moment(date).format(format);\n  });\n\n  // Base config\n  return {\n    dir: {\n      input: \"src\",\n      output: \"dist\",\n    },\n  };\n};
\n

Les fichiers de données

\n

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).

\n

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.

\n
module.exports = {\n  title: \"Webstoemp\",\n  description:\n    \"Webstoemp is the portfolio and blog of Jérôme Coupé, a designer and front-end developer from Brussels, Belgium.\",\n  url: \"https://www.webstoemp.com\",\n  baseUrl: \"/\",\n  author: \"Jerôme Coupé\",\n  authorTwitter: \"@jeromecoupe\",\n  buildTime: new Date(),\n};
\n

La valeur de site.buildTime peut maintenant être utilisée dans le pied de page du site :

\n
<div class=\"c-sitefooter__copyright\">\n  <p class=\"u-margin-all-none\">&copy; Webstoemp {{ site.buildTime | date(\"Y\") }}</p>\n</div>
\n

Layouts Nunjucks

\n

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.

\n

Blogposts

\n

Boucler sur la collection blogposts pour afficher les titres et les dates de publication n'est pas très compliqué:

\n
{% for post in collections.blogposts | reverse %}\n  {% if loop.first %}<ul class=\"c-list-ui\">{% endif %}\n  <li>\n    <article class=\"c-blogteaser\">\n      <p class=\"c-blogteaser__date\"><time datetime=\"{{ post.date | date('Y-M-DD') }}\">{{ post.date|date(\"MMMM Do, Y\") }}</time></p>\n      <h2 class=\"c-blogteaser__title\"><a href=\"{{ post.url }}\">{{ post.data.title }}</a></h2>\n    </article>\n  </li>\n  {% if loop.last %}</ul>{% endif %}\n{% else %}\n  <p>No blogpost found</p>\n{% endfor %}
\n

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 :

\n
{% extends \"layouts/base.njk\" %}\n{% set activeSection = \"blog\" %}\n\n{% set metaTitle = title %}\n{% set metaDescription = excerpt %}\n{% set metaImage = site.url ~ \"/img/blogposts/_600x600/\" ~ image %}\n\n{% block content %}\n\n  <article class=\"c-blogpost\">\n    <div class=\"c-blogpost__media\">\n      <div class=\"l-container\">\n\n        <picture>\n          <source media=\"(min-width: 500px)\"\n                  srcset=\"/img/blogposts/_1024x576/{{ image }} 1024w,\n                          /img/blogposts/{{ image }} 1500w\"\n                  sizes=\"(min-width: 1140px) 1140px,\n                         100vw\">\n          <img src=\"/img/blogposts/_600x600/{{ image }}\"\n               class=\"o-fluidimage\"\n               alt=\"{{ imageAlt }}\">\n        </picture>\n\n      </div>\n    </div>\n\n    <div class=\"c-blogpost__body  l-container l-container--narrow\">\n\n      <header>\n        <p class=\"c-suptitle  c-suptitle--dark\"><time datetime=\"{{ page.date | date('Y-M-DD') }}\">{{ page.date | date(\"MMMM Do, YYYY\") }}</time></p>\n        <h1 class=\"c-h1\">{{ title }}</h1>\n        <div class=\"c-blogpost__intro\">\n          <p>{{ excerpt }}</p>\n        </div>\n      </header>\n\n      <div class=\"c-wysiwyg\">\n        {{ content | safe }}\n      </div>\n\n    </div>\n  </article>\n\n{% endblock %}
\n

Projects

\n

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 :

\n
{% for project in collections.projects | reverse %}\n    {{ project.templateContent | safe }}\n{% endfor %}
\n

Satisfait de mon choix

\n

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.

", "authors": [ { "name": "jerome" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/06/22/cms-headless-en-3-jours/", "url": "https://jamstatic.fr/2019/06/22/cms-headless-en-3-jours/", "title": "Intégrer un CMS en 3 jours", "summary": "Retour d’expérience suite à l’intégration de Netlify CMS à un site Jekyll", "date_published": "2019-06-22T00:00:00+00:00","content_text": "\n\n\n\n\n\nImage d'illustration « netlify cms »\n\nImaginons 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 ? ».\nUne 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.\nCette 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.\nNous devions travailler à une meilleure solution afin de migrer nos contributeurs de contenu et effectuer les changements nécessaires rapidement.\nNous avons alors étudié les options qui s’offraient à nous :\n\nMettre en place un outil de gestion de contenu (CMS) traditionnel tel que WordPress\nTrouver un CMS headless à intégrer dans un générateur de site statique (SSG)\n\nLe 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.\nL’une des solutions les plus intéressantes que nous avons testées vient de la société Netlify, et de son projet Netlify CMS.\nNous avons pensé que Netlify CMS pourrait être avantageux pour les raisons suivantes :\n\nIl 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\nIl est SSG agnostique, et fonctionne donc avec notre site Jekyll existant mais ne nous empêcherait pas de changer d’avis (salut GatsbyJS !)\nIl 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 !\nIl fournit une expérience d’édition simple et fonctionnelle\nIl 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é\n\nSuite à 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.\nDevez-vous passer de GitHub Pages à Netlify ?\nÇ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.\nAlors 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.\nGit 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.\nLe 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.\nMigrer de GitHub Pages à Netlify\nEn 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.\nSi 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 :\nGemfile\nsource \"https:\/\/rubygems.org\"\ngem 'github-pages'\nnetlify.toml\n[build]\npublish = \"_site\/\"\ncommand = \"jekyll build\"\nUne 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.\nAjouter Netlify CMS à un site existant\nNetlify 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 :\nadmin\n├ index.html\n└ config.yml\nLa documentation de Netlify CMS explique ça très bien :\n\nLe 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 :\n\nadmin\/index.html\n<!doctype html>\n<html>\n<head>\n <meta charset=\"utf-8\" \/>\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" \/>\n <title>Content Manager<\/title>\n <script src=\"https:\/\/identity.netlify.com\/v1\/netlify-identity-widget.js\"><\/script>\n<\/head>\n<body>\n <!-- Include the script that builds the page and powers Netlify CMS -->\n <script src=\"https:\/\/unpkg.com\/netlify-cms@^2.0.0\/dist\/netlify-cms.js\"><\/script>\n<\/body>\n<\/html>\n\nLe 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.\n\nPour commencer, voici à quoi peut ressembler le fichier de configuration :\nadmin\/config.yml\nbackend:\n name: git-gateway\n branch: master\n identity_url: \"https:\/\/yoursite.com\/.netlify\/identity\"\n gateway_url: \"https:\/\/yoursite.com\/.netlify\/git\"\n squash_merges: true\n\npublish_mode: editorial_workflow\nmedia_folder: \"assets\/img\/uploads\"\n\nsite_url: https:\/\/yoursite.com\nlogo_url: https:\/\/yoursite.com\/assets\/img\/logo.svg\n\ncollections:\nLa 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é !\nRemarque : depuis mai 2019, le flux de travail éditorial n’est pris en charge que lorsque vous utilisez GitHub.\nMaintenant 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 :\n<script>\n if (window.netlifyIdentity) {\n window.netlifyIdentity.on(\"init\", user => {\n if (!user) {\n window.netlifyIdentity.on(\"login\", () => {\n document.location.href = \"\/admin\/\";\n });\n }\n });\n }\n<\/script>\nUne 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\/.\nQu’est-ce que les Collections ?\nBien 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.\nIl 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.\nSachant 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.\nParamétrage d’un fichier de collection pour les données de configuration\nUn 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 :\nadmin\/config.yml\ncollections:\n - label: \"Options transverses\"\n name: options\n editor:\n preview: false\n files:\n - label: \"Menu de navigation\"\n name: nav\n file: \"_data\/nav.yml\"\n fields:\n - label: \"Entrées de menu\"\n label_singular: \"Entrée de menu\"\n name: topLevelItems\n widget: list\n fields:\n - {label: \"Texte affiché\", name: displayText, widget: string}\n - {label: URL, name: url, widget: string}\n - label: \"Type d'objet\"\n name: itemType\n widget: select\n options: [\"Link\", \"Button\"]\nCela 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.\n\n\n\n\n\n\nGestion du menu de navigation depuis Netlify CMS\n\nVoici un exemple de ce à quoi peut resembler un fichier de données :\n_data\/nav.yml\ntopLevelItems:\n - displayText: 'Une page'\n itemType: Link\n url: '\/une-page\/'\n - displayText: 'Lien externe'\n itemType: Link\n url: 'https:\/\/google.com'\nComment utiliser un fichier de collection dans Jekyll ?\nVoyons comment exploiter ces données dans un template Jekyll. Voici un template Liquid qui utilise nos données de navigation :\n<ul>\n {% for item in site.data.nav.topLevelItems %}\n <li>\n {% if item.itemType == 'Link' %}\n <a href=\"{{ item.url }}\">{{ item.displayText }}<\/a>\n {% else %}\n ...\n {% endif %}\n <\/li>\n {% endfor %}\n<\/ul>\nDans 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.\nParamétrer un dossier de collection de pages\nUne 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.\nDans 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.\nRegardons la structure d’un dossier de collection provenant d’un fichier de configuration réel pour voir comment ça marche :\nadmin\/config.yml\ncollections:\n - label: \"Pages\"\n label_singular: \"Page\"\n name: pages\n folder: \"_pages\"\n create: true\n slug: \"{{slug}}\"\n preview_path: \"{{permalink}}\"\n editor:\n preview: false\n fields:\n - {label: \"Titre\", name: title, widget: string}\n - {label: \"Lien permanent\", name: permalink, widget: string}\n - label: \"Template\"\n name: \"layout\"\n widget: \"select\"\n default: \"blocks\"\n options:\n - { label: \"Défaut\", value: \"blocks\" }\n - { label: \"Page d'accueil\", value: \"home\" }\n - {label: \"Meta description\", name: metaDescription, widget: text, required: false}\n - label: \"Partage sur les réseaux sociaux\"\n name: social\n widget: object\n required: false\n fields:\n - {label: \"Image OpenGraph\", name: ogImage, widget: image, required: false}\n - {label: \"Image Twitter\", name: twitterImage, widget: image, required: false}\nCeci 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.\n\n\n\n\n\n\nListe des pages dans Netlify CMS\n\nVeuillez 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:).\nVoici un exemple de ce à quoi peut ressembler le fichier de contenu d’une page :\n_pages\/home.md\n---\nTitle: Accueil\npermalink: \/\nlayout: home\nmetaDescription: Dites nous de quoi il s'agit !\nsocial: {}\n---\nComment utiliser un dossier de collection dans Jekyll ?\nSi 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 !\nNous 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 !\nAvant de commencer, nous avons besoin de compléter le fichier de configuration de Jekyll :\n_config.yml\ncollections:\n pages:\n output: true\nCeci indique à Jekyll qu’il doit générer une nouvelle page pour chaque fichier Markdown présent dans le dossier pages.\nMais 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.\nRegardons un exemple de template :\n_layouts\/home.html\n---\nlayout: default\n---\n\n<h1>{{ page.title }}<\/h1>\n\n<section class=\"home\">\n {{ content }}\n<\/section>\nToutes 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.\nRéaliser un page builder dans Jekyll\nC’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.\nPour commencer, nous devons définir nos composants dans le fichier de configuration de Netlify CMS :\n_admin\/config.yml\ncollections:\n - label: \"Pages\"\n ...\n - label: \"Blocs de contenu\"\n label_singular: \"Bloc de contenu\"\n name: blocks\n widget: list\n types:\n - label: \"Mise en avant\"\n name: hero\n widget: object\n fields:\n - {label: \"En-tête\", name: heading, widget: string}\n - {label: \"Contenu\", name: content, widget: markdown, buttons: [\"bold\", \"italic\", \"link\"], required: false}\n - label: \"Bloc de texte riche\"\n name: textBlock\n widget: object\n fields:\n - {label: \"En-tête\", name: heading, widget: string, required: false}\n - {label: \"Contenu\", name: content, widget: markdown}\n ...\nIci 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.\n\n\n\n\n\n\nEdition de contenu depuis Netlify CMS\n\nCréons maintenant un nouveau template pour le rendu de nos widgets :\n_layouts\/blocks.html\n---\nlayout: default\n---\n\n{% for block in page.blocks %}\n {% include blocks\/{{ block.type }}.html block=block %}\n{% endfor %}\nIci 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 :\n_includes\/blocks\/hero.html\n<header class=\"page-hero\">\n <h1>{{ block.heading }}<\/h1>\n {% if block.content and block.content != '' %}\n <div class=\"max-width--330\">\n {{ block.content | markdownify }}\n <\/div>\n {% endif %}\n<\/header>\nParce 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.\nNotre retour d'expérience avec Netlify + Netlify CMS\nGrâ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).\nLes 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 !\nCela 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 :\nPour\n\nHéberger son site avec Netlify est un jeu d’enfant et nous n’avons rencontré aucun problème avec le site lui-même\nNetlify CMS à été très facile à installer sur un projet Jekyll existant et il est intuitif pour les nouveaux ingénieurs\nIl 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\nL’interface de Netlify CMS est simple et facile à prendre en main pour les contributeurs de contenu\nLe déploiement et l‘aperçu par branche est extraordinaire\nL‘offre gratuite de Netlify vous donnent la liberté d’évaluer le service avant de vous engager\nIl existe une communauté active et très utile pour Netlify CMS sur Gitter\nNetlify CMS est open-source et les contributions sont bienvenues\n\nContre\n\nNos contributeurs de contenu apprécient le flux de travail éditorial, mais n’aiment pas les nombreuses étapes nécessaires pour enregistrer et publier\nL’enregistrement et la publication sont relativement lents, parfois jusqu’à plusieurs secondes\nNous rencontrons des erreurs occasionnelles — mais frustrantes — lors de l’utilisation de l’administration du CMS\nCertains 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\nL’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\nIl 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\n\nCommunauté et contribution\nLes é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 !\nDécouvrez le code sur GitHub : https:\/\/github.com\/netlify\/netlify-cms", "content_html": "
\n\n\n\n\"Image\n\n
Image d'illustration « netlify cms »
\n
\n

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 ? ».

\n

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.

\n

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.\nNous devions travailler à une meilleure solution afin de migrer nos contributeurs de contenu et effectuer les changements nécessaires rapidement.

\n

Nous avons alors étudié les options qui s’offraient à nous :

\n
    \n
  1. Mettre en place un outil de gestion de contenu (CMS) traditionnel tel que WordPress
    2. \n
  2. Trouver un CMS headless à intégrer dans un générateur de site statique (SSG)
    3. \n
\n

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.

\n

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.

\n

Nous avons pensé que Netlify CMS pourrait être avantageux pour les raisons suivantes :

\n\n

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.

\n

Devez-vous passer de GitHub Pages à Netlify ?

\n

Ç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.

\n

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.

\n

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.

\n

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.

\n

Migrer de GitHub Pages à Netlify

\n

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.

\n

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 :

\n

Gemfile

\n
source \"https://rubygems.org\"\ngem 'github-pages'
\n

netlify.toml

\n
[build]\npublish = \"_site/\"\ncommand = \"jekyll build\"
\n

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.

\n

Ajouter Netlify CMS à un site existant

\n

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 :

\n
admin\n├ index.html\n└ config.yml
\n

La documentation de Netlify CMS explique ça très bien :

\n
\n

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 :

\n
\n

admin/index.html

\n
<!doctype html>\n<html>\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n  <title>Content Manager</title>\n  <script src=\"https://identity.netlify.com/v1/netlify-identity-widget.js\"></script>\n</head>\n<body>\n  <!-- Include the script that builds the page and powers Netlify CMS -->\n  <script src=\"https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js\"></script>\n</body>\n</html>
\n
\n

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.

\n
\n

Pour commencer, voici à quoi peut ressembler le fichier de configuration :

\n

admin/config.yml

\n
backend:\n  name: git-gateway\n  branch: master\n  identity_url: \"https://yoursite.com/.netlify/identity\"\n  gateway_url: \"https://yoursite.com/.netlify/git\"\n  squash_merges: true\n\npublish_mode: editorial_workflow\nmedia_folder: \"assets/img/uploads\"\n\nsite_url: https://yoursite.com\nlogo_url: https://yoursite.com/assets/img/logo.svg\n\ncollections:
\n

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é !

\n

Remarque : depuis mai 2019, le flux de travail éditorial n’est pris en charge que lorsque vous utilisez GitHub.

\n

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 :

\n
<script>\n  if (window.netlifyIdentity) {\n    window.netlifyIdentity.on(\"init\", user => {\n      if (!user) {\n        window.netlifyIdentity.on(\"login\", () => {\n          document.location.href = \"/admin/\";\n        });\n      }\n    });\n  }\n</script>
\n

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/.

\n

Qu’est-ce que les Collections ?

\n

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.

\n

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.

\n

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.

\n

Paramétrage d’un fichier de collection pour les données de configuration

\n

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 :

\n

admin/config.yml

\n
collections:\n  - label: \"Options transverses\"\n    name: options\n    editor:\n      preview: false\n    files:\n      - label: \"Menu de navigation\"\n        name: nav\n        file: \"_data/nav.yml\"\n        fields:\n          - label: \"Entrées de menu\"\n            label_singular: \"Entrée de menu\"\n            name: topLevelItems\n            widget: list\n            fields:\n              - {label: \"Texte affiché\", name: displayText, widget: string}\n              - {label: URL, name: url, widget: string}\n              - label: \"Type d'objet\"\n                name: itemType\n                widget: select\n                options: [\"Link\", \"Button\"]
\n

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.

\n
\n\n\n\n\"Gestion\n\n
Gestion du menu de navigation depuis Netlify CMS
\n
\n

Voici un exemple de ce à quoi peut resembler un fichier de données :

\n

_data/nav.yml

\n
topLevelItems:\n  - displayText: 'Une page'\n    itemType: Link\n    url: '/une-page/'\n  - displayText: 'Lien externe'\n    itemType: Link\n    url: 'https://google.com'
\n

Comment utiliser un fichier de collection dans Jekyll ?

\n

Voyons comment exploiter ces données dans un template Jekyll. Voici un template Liquid qui utilise nos données de navigation :

\n
<ul>\n  {% for item in site.data.nav.topLevelItems %}\n    <li>\n      {% if item.itemType == 'Link' %}\n        <a href=\"{{ item.url }}\">{{ item.displayText }}</a>\n      {% else %}\n        ...\n      {% endif %}\n    </li>\n  {% endfor %}\n</ul>
\n

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.

\n

Paramétrer un dossier de collection de pages

\n

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.\nDans 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.

\n

Regardons la structure d’un dossier de collection provenant d’un fichier de configuration réel pour voir comment ça marche :

\n

admin/config.yml

\n
collections:\n - label: \"Pages\"\n    label_singular: \"Page\"\n    name: pages\n    folder: \"_pages\"\n    create: true\n    slug: \"{{slug}}\"\n    preview_path: \"{{permalink}}\"\n    editor:\n      preview: false\n    fields:\n      - {label: \"Titre\", name: title, widget: string}\n      - {label: \"Lien permanent\", name: permalink, widget: string}\n      - label: \"Template\"\n        name: \"layout\"\n        widget: \"select\"\n        default: \"blocks\"\n        options:\n          - { label: \"Défaut\", value: \"blocks\" }\n          - { label: \"Page d'accueil\", value: \"home\" }\n      - {label: \"Meta description\", name: metaDescription, widget: text, required: false}\n      - label: \"Partage sur les réseaux sociaux\"\n        name: social\n        widget: object\n        required: false\n        fields:\n          - {label: \"Image OpenGraph\", name: ogImage, widget: image, required: false}\n          - {label: \"Image Twitter\", name: twitterImage, widget: image, required: false}
\n

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.

\n
\n\n\n\n\"Liste\n\n
Liste des pages dans Netlify CMS
\n
\n

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:).

\n

Voici un exemple de ce à quoi peut ressembler le fichier de contenu d’une page :

\n

_pages/home.md

\n
---\nTitle: Accueil\npermalink: /\nlayout: home\nmetaDescription: Dites nous de quoi il s'agit !\nsocial: {}\n---
\n

Comment utiliser un dossier de collection dans Jekyll ?

\n

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 !

\n

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 !

\n

Avant de commencer, nous avons besoin de compléter le fichier de configuration de Jekyll :

\n

_config.yml

\n
collections:\n  pages:\n    output: true
\n

Ceci indique à Jekyll qu’il doit générer une nouvelle page pour chaque fichier Markdown présent dans le dossier pages.

\n

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.

\n

Regardons un exemple de template :

\n

_layouts/home.html

\n
---\nlayout: default\n---\n\n<h1>{{ page.title }}</h1>\n\n<section class=\"home\">\n  {{ content }}\n</section>
\n

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.

\n

Réaliser un page builder dans Jekyll

\n

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.

\n

Pour commencer, nous devons définir nos composants dans le fichier de configuration de Netlify CMS :

\n

_admin/config.yml

\n
collections:\n  - label: \"Pages\"\n      ...\n      - label: \"Blocs de contenu\"\n        label_singular: \"Bloc de contenu\"\n        name: blocks\n        widget: list\n        types:\n          - label: \"Mise en avant\"\n            name: hero\n            widget: object\n            fields:\n              - {label: \"En-tête\", name: heading, widget: string}\n              - {label: \"Contenu\", name: content, widget: markdown, buttons: [\"bold\", \"italic\", \"link\"], required: false}\n          - label: \"Bloc de texte riche\"\n            name: textBlock\n            widget: object\n            fields:\n              - {label: \"En-tête\", name: heading, widget: string, required: false}\n              - {label: \"Contenu\", name: content, widget: markdown}\n          ...
\n

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.

\n
\n\n\n\n\"Edition\n\n
Edition de contenu depuis Netlify CMS
\n
\n

Créons maintenant un nouveau template pour le rendu de nos widgets :

\n

_layouts/blocks.html

\n
---\nlayout: default\n---\n\n{% for block in page.blocks %}\n  {% include blocks/{{ block.type }}.html block=block %}\n{% endfor %}
\n

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 :

\n

_includes/blocks/hero.html

\n
<header class=\"page-hero\">\n  <h1>{{ block.heading }}</h1>\n  {% if block.content and block.content != '' %}\n    <div class=\"max-width--330\">\n      {{ block.content | markdownify }}\n    </div>\n  {% endif %}\n</header>
\n

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.

\n

Notre retour d'expérience avec Netlify + Netlify CMS

\n

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).\nLes 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 !

\n

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 :

\n

Pour

\n\n

Contre

\n\n

Communauté et contribution

\n

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 !

\n

Découvrez le code sur GitHub : https://github.com/netlify/netlify-cms

", "authors": [ { "name": "arnaud" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/03/01/gatsby-pour-les-applis-web/", "url": "https://jamstatic.fr/2019/03/01/gatsby-pour-les-applis-web/", "title": "Gatsby pour les applis Web", "summary": "Comment Gatsby permet d'allier les atouts du statique avec les possibilités du dynamique pour créer des applis Web riches en fonctionnalités.", "date_published": "2019-03-01T10:00:00+00:00","content_text": "Gatsby est génial pour la génération des sites statiques. Vous le saviez probablement déjà ! Mais c'est en fait tout aussi bien pour les applis Web. Vous ne le saviez peut-être pas. Gatsby est fait pour construire des expériences qui profitent à la fois des bénéfices des sites dits statiques et des applis web. Vous n'avez pas à sacrifier les avantages des unes pour obtenir les bénéfices des autres.\nDans 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.\nNous 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.\nPour commencer, nous pouvons nous demander ce qu'est, au juste, une appli Web.\n\nNote :\nSi 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.\n\nQu'est-ce qu'une appli Web ?\nJ'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 :\n\nrequêtage de données dynamiques;\nauthentification des utilisateurs, et le fait d'avoir des routes authentifiées côté client;\ndes interactions côté client portées par JavaScript.\n\nBien 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.\nJe 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.\nGmail\n\n\n\n\n\nGmail peut-être vu, avec le recul, comme une “preuve de concept” qui a démontré deux choses très importantes :\n\nle JavaScript côté client peut offrir une expérience proche de celles des apps, et\nune application JavaScript (qui s'exécute dans votre navigateur) soutient favorablement la comparaison avec une application native, que ce soit sur desktop ou mobile.\n\nIl 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.\nTwitter (Progressive Web Application)\n\n\n\n\n\nTwitter 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 :\n\nça illustre une partie de la richesse d'une expérience Web moderne, et\nça repose sur des pratiques avancées et des optimisations poussées de performances pour proposer une expérience rapide et plaisante.\n\nEn particulier, les fonctionnalités suivantes sont des composantes clés pour un nouveau genre d'applications :\n\nle cache agressif des données et une navigation rapide grâce aux Service Workers,\nla mise en place du pattern PRPL (Push, Render, Pre-cache, Lazy-Loading),\nl'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.\n\nCes 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.\nCes deux applis Web serviront de d'exemples à garder à l'esprit quand nous allons aborder l'utilisation de Gatsby pour les applis Web.\nGatsby est taillé pour les applis Web\n\n\n\n\n\nEt 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 ?\nAucune 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 :\n\ninjecte la donnée dans les pages (depuis GraphQL ou même sans utiliser GraphQL);\nutilise la fonction d'API de rendu côté serveur ReactDOMServer.renderToString pour transformer les composants React en fichiers HTML;\ninjecte le runtime et des additions (comme un routeur !) pour permettre de construire des features d’applis Web.\n\n\nGatsby offre une expérience similaire à create-react-app une fois que le runtime est fonctionnel\n\nPour 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.\n\/\/ src\/pages\/messages.js\n\nimport React from \"react\";\n\nimport Layout from \"..\/components\/layout\";\n\nclass Messages extends React.Component {\n constructor(props) {\n super(props);\n\n this.state = {\n messages: [],\n };\n }\n\n \/\/ note: this is a simplified example without error handling, authentication, etc.\n async componentDidMount() {\n const messages = await fetch(\n `\/api\/some-url-to-get-messages`\n ).then((response) => response.json());\n\n this.setState({\n messages,\n });\n }\n\n render() {\n const { messages } = this.state;\n return (\n <Layout>\n {messages.length === 0 ? (\n <p>Loading messages&hellip;<\/p>\n ) : (\n <ul>\n {messages.map((message) => (\n <li key={message.id}>{message.text}<\/li>\n ))}\n <\/ul>\n )}\n <\/Layout>\n );\n }\n}\n\nexport default Messages;\nTout 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.\nConsidé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 !\n\nCependant, 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 !\nL'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.\nGatsby 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.\nPourquoi utiliser Gatsby pour une appli Web ?\nDes optimisations de performance, par défaut\nSi l'on regarde les avantages que procure Gatsby, à minima :\n\nle rendu statique de composants React et des données associées en HTML statique;\nl'optimisation des données, des images, etc. pour obtenir des sites ultra-rapides;\nla présence de patterns liés à la performance et des bonnes pratiques comme le PRPL, la séparation de code par route, etc.\n\nChacun 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.\nCes 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.\nLes plugins et l'écosystème Gatsby\nUn 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 !\nPrenons le temps de regarder plus en détail ces fonctionnalités proposées par un de nos composants, gatsby-image.\ngatsby-image\ngatsby-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 :\n\nl'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;\nla 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;\nle chargement asynchrone des images avec une technique de flou dégressif — ou même de SVG tracé.\n\ngatsby-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.\nLe 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 !\nMaintenant, 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.\nLa Coquille Applicative\nEn 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.\nSi nous regardons de plus près cette approche, elle se décompose comme suit:\n\non rend le plus de contenu possible instantanément (la coquille applicative);\non 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).\n\nComparons 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.\nPour 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.\n\nNous 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.\nAfin 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.\nEt voici… Gatsby Mail ! (Qui ne sert qu'à des fins de démonstration !)\n\n\n\n\n\nGatsby Mail reprend certains des concepts et des thèmes que j'ai abordés. Plus particulièrement :\n\nGmail, Twitter et les autres sont des exemples parlants d'applis Web complexes qui proposent des expériences riches.\nGatsby fournit des composants, des plugins, etc… qui permettent de développer ces expériences, servez-vous en !\nGatsby est un excellent choix lorsqu'il s'agit de construire de telles applis Web.\n\nDe plus, Gatsby Mail fait la démonstration de fonctionnalités spécifiques aux applis Web, comme :\n\ndu rendu statique couplé à des requêtes dynamiques grâce au runtime côté client;\nde l'authentification et des routes gérées côté client;\ndes routes non-authentifiées, comme une page d'accueil (qui utilise l'API Context de React);\nl'utilisation de GraphQL au moment du build et au runtime, en s'appuyant sur une API GraphQL distante et sur apollo-boost;\nle chargement d'une coquille applicative grâce à gatsby-plugin-offline (voyez par vous-même la démo en “3G rapide” ci-dessous !).\n\net 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.\n\nVous 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 ;)\nOn a hâte de voir ce que vous allez construire.", "content_html": "

Gatsby est génial pour la génération des sites statiques. Vous le saviez probablement déjà ! Mais c'est en fait tout aussi bien pour les applis Web. Vous ne le saviez peut-être pas. Gatsby est fait pour construire des expériences qui profitent à la fois des bénéfices des sites dits statiques et des applis web. Vous n'avez pas à sacrifier les avantages des unes pour obtenir les bénéfices des autres.

\n

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.

\n

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.

\n

Pour commencer, nous pouvons nous demander ce qu'est, au juste, une appli Web.

\n
\n

Note :\nSi 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.

\n
\n

Qu'est-ce qu'une appli Web ?

\n

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 :

\n\n

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.

\n

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.

\n

Gmail

\n\n\n\n\"capture\n\n

Gmail peut-être vu, avec le recul, comme une “preuve de concept” qui a démontré deux choses très importantes :

\n\n

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.

\n

Twitter (Progressive Web Application)

\n\n\n\n\"Capture\n\n

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 :

\n\n

En particulier, les fonctionnalités suivantes sont des composantes clés pour un nouveau genre d'applications :

\n\n

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.

\n

Ces deux applis Web serviront de d'exemples à garder à l'esprit quand nous allons aborder l'utilisation de Gatsby pour les applis Web.

\n

Gatsby est taillé pour les applis Web

\n\n\n\n\"what\n\n

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 ?

\n

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 :

\n
    \n
  1. injecte la donnée dans les pages (depuis GraphQL ou même sans utiliser GraphQL);
    2. \n
  2. utilise la fonction d'API de rendu côté serveur ReactDOMServer.renderToString pour transformer les composants React en fichiers HTML;
    3. \n
  3. injecte le runtime et des additions (comme un routeur !) pour permettre de construire des features d’applis Web.
    4. \n
\n\n

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.

\n
// src/pages/messages.js\n\nimport React from \"react\";\n\nimport Layout from \"../components/layout\";\n\nclass Messages extends React.Component {\n  constructor(props) {\n    super(props);\n\n    this.state = {\n      messages: [],\n    };\n  }\n\n  // note: this is a simplified example without error handling, authentication, etc.\n  async componentDidMount() {\n    const messages = await fetch(\n      `/api/some-url-to-get-messages`\n    ).then((response) => response.json());\n\n    this.setState({\n      messages,\n    });\n  }\n\n  render() {\n    const { messages } = this.state;\n    return (\n      <Layout>\n        {messages.length === 0 ? (\n          <p>Loading messages&hellip;</p>\n        ) : (\n          <ul>\n            {messages.map((message) => (\n              <li key={message.id}>{message.text}</li>\n            ))}\n          </ul>\n        )}\n      </Layout>\n    );\n  }\n}\n\nexport default Messages;
\n

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.

\n

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 !

\n\"illustration\n

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 !

\n

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.

\n

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.

\n

Pourquoi utiliser Gatsby pour une appli Web ?

\n

Des optimisations de performance, par défaut

\n

Si l'on regarde les avantages que procure Gatsby, à minima :

\n\n

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.

\n

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.

\n

Les plugins et l'écosystème Gatsby

\n

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 !

\n

Prenons le temps de regarder plus en détail ces fonctionnalités proposées par un de nos composants, gatsby-image.

\n

gatsby-image

\n

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 :

\n\n

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.

\n

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 !

\n

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.

\n

La Coquille Applicative

\n

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.

\n

Si nous regardons de plus près cette approche, elle se décompose comme suit:

\n\n

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.

\n

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.

\n\"comparaison\n

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.

\n

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.

\n

Et voici… Gatsby Mail ! (Qui ne sert qu'à des fins de démonstration !)

\n\n\n\n\"gatsby\n\n

Gatsby Mail reprend certains des concepts et des thèmes que j'ai abordés. Plus particulièrement :

\n
    \n
  1. Gmail, Twitter et les autres sont des exemples parlants d'applis Web complexes qui proposent des expériences riches.
    2. \n
  2. Gatsby fournit des composants, des plugins, etc… qui permettent de développer ces expériences, servez-vous en !
    3. \n
  3. Gatsby est un excellent choix lorsqu'il s'agit de construire de telles applis Web.
    4. \n
\n

De plus, Gatsby Mail fait la démonstration de fonctionnalités spécifiques aux applis Web, comme :

\n\n

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.

\n\"animation\n

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 ;)

\n

On a hâte de voir ce que vous allez construire.

", "authors": [ { "name": "phacks" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/02/07/c-est-quoi-la-jamstack/", "url": "https://jamstatic.fr/2019/02/07/c-est-quoi-la-jamstack/", "title": "C'est quoi la Jamstack au juste ?", "summary": "Un petit pense-bête pour expliquer les concepts de la Jamstack et encourager davantage de personnes à adopter cette approche.", "date_published": "2019-02-07T19:12:14+00:00", "date_modified": "2019-02-28T08:17:42+00:00","content_text": "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.\nLa 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é.\nVous vous demandez peut-être ; oui OK, mais comment ? pourquoi ? c'est quoi au juste ?\nC'est la raison d'être de cette page https:\/\/jamstack.wtf.\nLe 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.\nLe contenu ci-dessous est tiré du site ci-dessus 👆\nAsseyez-vous, mettez-vous à l'aise et appréciez ✌️\n\n\nC'est quoi la Jamstack ?\nSignification\nBénéfices\nBonnes pratiques\nChaîne de publication\nHistorique\n\n\nBien démarrer\nDéveloppement\nDéploiement\nParties dynamiques\nCMS\nRessources\n\n\nÀ propos\n\n\nC'est quoi la Jamstack ?\nSignification\n\n\nJAM c'est pour JavaScript, APIs & Markup.\n\nJavaScript\nLes fonctionnalités dynamiques sont gérées par JavaScript. Vous êtes libres d'utiliser la bibliothèque ou le framework que vous voulez.\nAPIs\nLes 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.\nMarkup\nLes 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.\nBénéfices\nLes principaux bénéfices apportés par la Jamstack sont :\nUne performance accrue\nServir du code généré et des assets à partir d'un CDN\nUne meilleure sécurité\nPlus besoin de se soucier des vulnérabilités du serveur ou de la base de données\nUn coût bien moindre\nL'hébergement de fichiers statiques est moins cher voire gratuit\nUne meilleure expérience de développement\nLes 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é.\nRedimensionnement à la volée\nSi votre site devient viral ou est soumis à un pic d'activité, le CDN compensera sans problèmes.\nBonnes pratiques\nLes astuces suivantes vous aideront à tirer le meilleur parti de la stack.\nRéseau de distribution de contenu (CDN)\nPuisque 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.\nEn savoir plus\nDéploiement atomique\nChaque déploiement est une photographie complète du site. Vous disposez ainsi d'une version consistante du site à l'échelle mondiale.\nEn savoir plus\nInvalidation du cache\nUne 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.\nEn savoir plus\nTout est versionné\nVotre 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é.\nEn savoir plus\nGénérations automatiques\nVotre 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.\nEn savoir plus\nChaîne de publication\nVoici à quoi ressemblerait la chaîne de publication Jamstack idéale.\n\n\nChaine de publication\n\nHistorique\n2015\nLes générateurs statiques sont de plus en plus en vogue, grâce à des générateurs populaires comme Jekyll.\n2016\nQuelques développeurs pensent que les sites statiques n'ont pas à être forcément statiques, le terme \"Jamstack\" fait son apparition.\n2017\nLa 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.\n2018\nDes 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.\nSource : Snipcart\n\nBien démarrer\nC'est à vous de décider comment générer vos fichiers HTML. Les trois approches les plus communes sont :\nDéveloppement\nÀ la main\nUne méthode simple et efficace d'écrire du HTML, c'est idéal pour les pages super simples.\nGénérateurs de site statique\nLa plupart des sites Jamstack sont propulsés par un générateur de site statique.\nVous êtes libres de choisir votre GSS.\n\nGatsby\nNext.js\nHugo\n\nVoir davantage de générateurs\nFramework frontend\nLa 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.\n\nReact\nVue.js\nPreact\n\nDéploiement\nVous devez héberger le résultat de la compilation de votre site. Il existe de fantastiques services qui font cela gratuitement et simplement.\n\nNetlify\nVercel\nGithub Pages\n\nVoir plus de services de déploiement\nParties dynamiques\nLes 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.\nFonctions personnalisées\nVous 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\nCommentaires\nBeaucoup de sites Jamstack intègrent des sections pour les commentaires, principalement sur des blogs.\nFormulaires\nUn excellent moyen d'interagir avec votre audience.\nE-Commerce\nMettre en place une boutique en ligne sur un site Jamstack n'a jamais été aussi simple.\nRecherche\nReposez-vous sur des services tiers pour intégrer des fonctionnalités de recherche.\nVoir plus de services pour les sites statiques\nCMS\nLes 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.\n\nContentful\nForestry\nGhost\nHeadless WordPress\nNetlify CMS\nStrapi\n\nVoir plus de services de gestion de contenu\nRessources\nVoici une sélection de ressources sur la Jamstack qui comporte des matériaux d'apprentissage ainsi que des listes de services.\nServices\n\nUne liste de services pour les sites web statiques\nUne liste de gestionnaires de contenu pour les sites Jamstack\nUne liste de générateurs de site statiques pour les sites Jamstack\nUn annuaire de sélection d'outils et de services\n\nArticles\n\nDébuter avec la Jamstack? Tout ce que vous devez savoir pour bien démarrer\nQuel est le concept derrière la Jamstack\nDéveloppement web moderne avec la Jamstack\nSmashing Magazine va dix fois plus vite\nGhost avec la Jamstack\nJamstack avec Gatsby, Netlify et Netlify CMS\n\nVidéos\n\nL'essor de la Jamstack, présentation de Mathias Biilmann\nLa nouvelle stack Front-end, présentation de Mathias Biilmann\nUne sélection de vidéos par The New Dynamic\nComment freeCodeCamp sert des millions d'apprenants en utilisant la Jamstack\n\nPodcast\n\nJamstack Radio\n\n\nÀ propos\nCette page a été mise en place par @peduarte et présentée au meetup Jamstack de Londres — (voir les slides).", "content_html": "\n

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é.

\n

Vous vous demandez peut-être ; oui OK, mais comment ? pourquoi ? c'est quoi au juste ?

\n

C'est la raison d'être de cette page https://jamstack.wtf.

\n

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.

\n

Le contenu ci-dessous est tiré du site ci-dessus 👆

\n

Asseyez-vous, mettez-vous à l'aise et appréciez ✌️

\n
\n
\n
\n

C'est quoi la Jamstack ?

\n

Signification

\n
\n\"JAM\n
JAM c'est pour JavaScript, APIs & Markup.
\n
\n

JavaScript
\nLes fonctionnalités dynamiques sont gérées par JavaScript. Vous êtes libres d'utiliser la bibliothèque ou le framework que vous voulez.

\n

APIs
\nLes 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.

\n

Markup
\nLes 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.

\n

Bénéfices

\n

Les principaux bénéfices apportés par la Jamstack sont :

\n

Une performance accrue
\nServir du code généré et des assets à partir d'un CDN

\n

Une meilleure sécurité
\nPlus besoin de se soucier des vulnérabilités du serveur ou de la base de données

\n

Un coût bien moindre
\nL'hébergement de fichiers statiques est moins cher voire gratuit

\n

Une meilleure expérience de développement
\nLes 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é.

\n

Redimensionnement à la volée
\nSi votre site devient viral ou est soumis à un pic d'activité, le CDN compensera sans problèmes.

\n

Bonnes pratiques

\n

Les astuces suivantes vous aideront à tirer le meilleur parti de la stack.

\n

Réseau de distribution de contenu (CDN)
\nPuisque 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.

\n

En savoir plus

\n

Déploiement atomique
\nChaque déploiement est une photographie complète du site. Vous disposez ainsi d'une version consistante du site à l'échelle mondiale.

\n

En savoir plus

\n

Invalidation du cache
\nUne 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.

\n

En savoir plus

\n

Tout est versionné
\nVotre 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é.

\n

En savoir plus

\n

Générations automatiques
\nVotre 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.

\n

En savoir plus

\n

Chaîne de publication

\n

Voici à quoi ressemblerait la chaîne de publication Jamstack idéale.

\n
\n\"Chaine\n
Chaine de publication
\n
\n

Historique

\n

2015
\nLes générateurs statiques sont de plus en plus en vogue, grâce à des générateurs populaires comme Jekyll.

\n

2016
\nQuelques développeurs pensent que les sites statiques n'ont pas à être forcément statiques, le terme \"Jamstack\" fait son apparition.

\n

2017
\nLa 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.

\n

2018
\nDes 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.

\n

Source : Snipcart

\n
\n

Bien démarrer

\n

C'est à vous de décider comment générer vos fichiers HTML. Les trois approches les plus communes sont :

\n

Développement

\n

À la main
\nUne méthode simple et efficace d'écrire du HTML, c'est idéal pour les pages super simples.

\n

Générateurs de site statique
\nLa plupart des sites Jamstack sont propulsés par un générateur de site statique.\nVous êtes libres de choisir votre GSS.

\n\n

Voir davantage de générateurs

\n

Framework frontend
\nLa 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.

\n\n

Déploiement

\n

Vous devez héberger le résultat de la compilation de votre site. Il existe de fantastiques services qui font cela gratuitement et simplement.

\n\n

Voir plus de services de déploiement

\n

Parties dynamiques

\n

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.

\n

Fonctions personnalisées
\nVous 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

\n

Commentaires
\nBeaucoup de sites Jamstack intègrent des sections pour les commentaires, principalement sur des blogs.

\n

Formulaires
\nUn excellent moyen d'interagir avec votre audience.

\n

E-Commerce
\nMettre en place une boutique en ligne sur un site Jamstack n'a jamais été aussi simple.

\n

Recherche
\nReposez-vous sur des services tiers pour intégrer des fonctionnalités de recherche.

\n

Voir plus de services pour les sites statiques

\n

CMS

\n

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.

\n\n

Voir plus de services de gestion de contenu

\n

Ressources

\n

Voici une sélection de ressources sur la Jamstack qui comporte des matériaux d'apprentissage ainsi que des listes de services.

\n

Services

\n\n

Articles

\n\n

Vidéos

\n\n

Podcast

\n\n
\n

À propos

\n

Cette page a été mise en place par @peduarte et présentée au meetup Jamstack de Londres — (voir les slides).

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/02/06/de-wordpress-a-hugo-un-nouvel-etat-d-esprit/", "url": "https://jamstatic.fr/2019/02/06/de-wordpress-a-hugo-un-nouvel-etat-d-esprit/", "title": "De WordPress à Hugo : adopter un nouvel état d'esprit", "summary": "Comparons le fonctionnement de WordPress et de Hugo pour vous aider à vous familiariser avec ce nouvel environnement et vous imprégner de sa philosophie.", "date_published": "2019-02-06T16:12:14+00:00", "date_modified": "2019-05-03T14:12:14+00:00","content_text": "Dans cet article, nous n'allons pas migrer un site de WordPress vers Hugo, nous allons voir comment passer des habitudes que vous avez prises avec WordPress à celles d'Hugo.\nNous 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.\nNous allons partir de the_post(), the_loop et de la hiérarchie de modèle, pour mieux comprendre comment Hugo fonctionne !\nDe WordPress à Hugo\nVu 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.\nMoi aussi je faisais principalement du développement avec WordPress, avant de devenir complètement accro à Hugo.\nEt 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.\nJe 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.\nMais 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.\nDonc si vous débutez avec Hugo, et que vous connaissez WordPress, ce qui va suivre ne pourra que vous être bénéfique.\nTout est page\nCette affirmation catégorique est essentielle pour mieux appréhender le fonctionnement d'Hugo, surtout en ce qui concerne la logique dans les gabarits.\nPour 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.\nOn peut le voir ainsi : tout ce qui possède une URL, c'est une page !\nSi 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.\nType\nSi 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).\nDans 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 :\n\nVous ajoutez le type désiré dans le front matter\nOu plus généralement, vous laissez le premier niveau d'arborescence de contenu définir le type du fichier.\n\nDonc pour créer une page de type recette, vous pouvez soit écrire le front matter suivant :\ntitle: De délicieux cupcakes\ntype: recette\n---\nOu vous reposer sur la structure de votre arborescence et laisser faire la magie :\ncontent\n ├── post\n └── recette\n └── de-delicieux-cupcakes.md\nKind\nDans 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.\nD'où les fonctions booléennes is_single(), is_archive()!\nDans 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.\nVoici différents exemples de valeurs pour kind :\n\nLa page d'accueil de votre site web est la seule qui ait le kind homepage\nLa page qui affiche vos recettes est une page avec le kind section\nLa page qui affiche vos recettes catégorisées dans chocolat est une page avec le kind taxonomy\nLa page qui regroupe toutes les catégories de vos recette (dont celles au chocolat) est une page avec le kind taxonomyTerm\nEnfin la page qui affiche une recette est la page la plus commune est de kind page.\n\nModèles et hiérarchie\nMaintenant que nous avons vu Type et Kind, plongeons nous dans la logique des gabarits de page d'Hugo.\nTout 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.\nEn plus des conventions sur les noms de fichier, Hugo se base aussi sur l'arborescence des dossiers pour savoir quel modèle appliquer.\nComme évoqué précédemment, WordPress se base sur le fichier archive.php pour la mise en page de la liste d'articles de blog. Hugo se base lui sur un fichier list.html pour remplir cette fonction.\nDe 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.\nLa meilleure approche pour comprendre la logique de l'organisation des modèles avec Hugo est encore de lire la documentation officielle à ce sujet.\nLes modèles de page personnalisés\nC'est un des trucs plus anciens de WordPress.\nSi 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 :\n<?php \/* Template Name: Custom 🤮 *\/ ?>\nAvec 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.\nEnsuite nommez votre fichier d'après la valeur définie pour layout, placez-le dans le dossier layouts\/_default\/ et c'est bon !\n---\ntitle: À propos\nlayout: about\n---\nÀ propos de moi !\nlayouts\n └── _default\n └── about.html\n\nLes fichiers includes\nUne 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.\nDans 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.\nLe 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.\nOn inclut un fichier partiel ainsi :\n{{ partial \"post-head\" . }}\nLe point ci-dessus .............☝️ correspond à la page courante.\nLe 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.\nComprendre le contexte dans Hugo, c'est la clé. Si ce n'est pas encore clair pour vous, 👉 lisez Hugo, le point sur le contexte\nLa boucle et les données\nLes variables de Page\nDans 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.\nHugo 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.\nDans Hugo, les équivalents aux expressions WordPress citées un peu plus haut sont .Permalink, .Title , .Content, .Date.\nVous 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 :\n{{\/* layouts\/partials\/post-head.html *\/}}\n<div class=\"post-head\">\n <h1><a href=\"{{ .Permalink }}\">{{ .Title }}<\/a><h1>\n <time>{{ .Date }}<\/time>\n<\/div>\nBoucler avec range\nPouvoir parcourir des articles pour construire des pages archives ou un widget Derniers articles est essentiel pour un moteur de template.\nSelon 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.\nDonc 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.\nAvec Hugo, dans les gabarits de listes, les pages concernées sont stockées dans une collection et sont accessibles via l'objet .Pages.\nCela fait que pour le modèle de liste de la section recettes, .Pages retournera la collection des pages correspondantes : recettes.\nPour 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.\nUne 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 ..\nComparaison des boucles\nVoici notre boucle WordPress tant aimée :\n\/\/ theme\/archive.php\n<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>\n <!-- post -->\n <h2>\n <a href=\"<?php the_permalink(); ?>\"><?php the_title() ?><\/a>\n <\/h2>\n <h6><?php the_date(); ?><\/h6>\n <p>\n <?php the_excerpt(); ?>\n <\/p>\n <hr>\n<?php endwhile; ?>\n<?php else: ?>\n<!-- aucun post trouvé -->\n<?php endif; ?>\nLa même chose en beaucoup plus lisible et succinct avec Hugo, grâce à la transmission du contexte dans les fonctions :\n\/\/layouts\/_default\/list.html\n{{ with .Pages }}\n {{ range . }}\n <h2>\n <a href=\"{{ .Permalink }}\">{{ .Title }}<\/a>\n <\/h2>\n <h6>{{ .Date.Format \"January, 02 2006\" }}<\/h6>\n <p>\n {{ .Summary }}\n <\/p>\n <hr>\n {{ end }}\n{{ else }}\n<!-- aucun élément trouvé -->\n{{ end }}\nQu'en-est-il des autres pages ?\nPour 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.\nAvec 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.\nVoici 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 :\n<?php\n$recents = new WP_Query(\n [\n 'post_type'=>'recipe',\n 'posts_per_page'=>5,\n 'orderby' => 'meta_value_num',\n 'meta_key' => 'rating',\n ]\n);\nif ( $recents->have_posts() ) : while ( $recents->have_posts() ) : $recents->the_post(); ?>\n <h2>\n <a href=\"<?php $recents->the_permalink(); ?>\"><?php $recents->the_title() ?><\/a>\n <\/h2>\n<!-- post -->\n<?php endwhile; ?>\n<?php else: ?>\n<!-- aucune entrée trouvée -->\n<?php endif; ?>\n?>\nEt voici son élégante variante avec Hugo :\n{{ $recents := (where .Site.RegularPages \"Type\" \"recipe\").ByParam \"rating\" }}\n{{ range first 5 $recents }}\n <h2>\n <a href=\"{{ .Permalink }}\">{{ .Title }}<\/a>\n <\/h2>\n{{ end }}\nPour apprendre comment filtrer et ordonner les collections de pages dans Hugo,\nreportez-vous à la documentation de range, where et comment ordonner le contenu.\nLes shortcodes\nDans 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.\nHugo 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.\n\nSi le paramètre est nommé 👉 .Get \"title\".\nSinon on utilise sa position 👉 .Get 0.\n\nLes shortcodes par l'exemple\nVoici 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.\n<?php\nfunction caption_shortcode( $atts, $content = null ) {\n $a = shortcode_atts( array(\n 'class' => 'caption',\n ), $atts );\n\n return '<span class=\"' . esc_attr($a['class']) . '\">' . $content . '<\/span>';\n}\nadd_shortcode( 'caption', 'caption_shortcode' );\nLe shortcode s'utilise ensuite ainsi :\n[caption class=\"headline\"]My Caption[\/caption]\nVoyons maintenant la réponse en une ligne d'Hugo :\n{{\/* layouts\/shortcodes\/caption.html *\/}}\n<span class=\"{{ default \"caption\" (.Get 0) }}\">{{ .Inner }}<\/span>\nOn écrira dans son fichier Markdown :\n{{%\/* caption \"headline\" *\/%}}My Caption{{%\/* \/caption *\/%}}\nNous avons opté pour l'utilisation de la position… car il n'y a qu'un seul paramètre 🤷\nTirer parti des shortcodes d'Hugo (Julio Pescador)\nParamètres\nIl 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.\nTout 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 :\n\nYAML\nTOML\nJSON\n\nSi 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.\nCes 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.\nFormats de sortie\nHein, c'est quoi ça ?\nAh oui c'est vrai, WordPress ne vous a pas présenté.\nImaginons 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.\nTout 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.\nPour résumer :\n# config.yaml\noutputs:\n homepage:\n - HTML\n - JSON\n page:\n - HTML\n - AMP\nlayouts\n ├── _default\n │ └── about.html\n ├── index.html\n ├── index.json\n └── recipes\n └── single.amp.html\nEt 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 !\nJe 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 !\nBâtir une API JSON avec les formats de sortie personnalisés d'Hugo\nTraitement des assets\nWordPress ne propose rien en ce sens, c'est à vous d'utiliser votre propre gestionnaire de tâches et ses paquets de traitement des assets.\nHugo propose lui sa propre suite d'outils de traitement des assets !\n-- Heeein?\n-- Oui! Ça s'appelle les tuyaux d'Hugo et sans aucune dépendance node vous pouvez :\n\nMinifier 🗜️\nPaquetter vos fichiers 📦\nCompiler vos fichiers Sass\/Scss 👓\nAjouter une empreinte et un contrôle d'intégrité 🔑\n\nAvec quelques dépendances vous pouvez :\n\nExécuter PostCSS sur vos feuilles de style\n\nLe tout avec la même élégance à laquelle vous devez commencer à vous habituer :\n{{ $style := resources.Get \"main.scss\" | toCSS | minify | fingerprint }}\n<link href=\"{{ $style.Permalink }}\" rel=\"stylesheet\">\nHugo s'assurera également que ces assets sont compilés et publiés uniquement si vous appelez leur .Permalink dans vos templates.\nTraitement des images\nLe traitement d'image par défaut de WordPress se fait uniquement lors de l'étape initiale de téléversement.\nWordPress 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.\nHugo 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.\n{{ $img := resources.Get \"header.jpg\" | .Resize \"600x\" }}\n<img src=\"{{ $img.Permalink }}\" alt=\"\">\nJe sais! Moi aussi je ne me lasse pas de ces instructions sur deux lignes !\nVous pouvez lancer des traitements d'images, soit à l'aide des tuyaux d'Hugo ou des ressources de page.\n\nLa révolution des tuyaux d'Hugo\nTraitement des images responsive avec Hugo | Laura Kalbag\nCache-bust et concatenation de fichiers JS\/SCSS avec Hugo | Ben Bozzay\nLes ressources de page d'Hugo\n\nThèmes et Plugins VS Composants de Thème\nWordPress 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.\nPour les thèmes, WordPress ne vous donne que deux niveaux de personnalisation.\nVous 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.\nSi 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.\nDans Hugo, on ne parle pas de plugins et des thèmes mais plutôt de composants.\nVous pouvez en ajouter autant que vous voulez.\nFichiers 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.\nVoyez les composants comme des thèmes enfant illimités !\nCertains 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.\nLe thème par l'exemple\nPrenons pour exemple un projet fictif de clinique dentaire, où personne ne veut avoir à trop mettre les mains dans le code. Vous aurez besoin :\n\nUn thème principal adapté pour le secteur de la santé 👩‍⚕️\nUne extension du thème principal adaptée pour le domaine dentaire 🦷\nUne extension saisonnière du thème principal 🎄\nUne solution pour gérer des menus de navigation riches\nUn ensemble de shortcodes en relation avec le médical à l'intention de l'équipe de rédaction\nUn fichier JSON pour chaque page.\n\nAvec WordPress il vous faudrait :\n\n\nThèmes\n\nUn thème santé\nUn thème dentaire enfant du thème santé\n\n\n\nPlugins\n\nUn plugin thème santé saisonnier\nUn plugin Mega Menu\nUn plugin Shordcodes médicaux\nUn plugin API REST\n\n\n\nNotez 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. 🤷‍♂️\nDans 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.\ntheme:\n - health-theme\n - health-theme-dental-extension\n - health-theme-season-extension\n - mega-menu-component\n - medical-shortcodes-component\n - json-api-component\n\noutput:\n page:\n - HTML\n - JSON\nL'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.\nC'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).\nTrucs et astuces pour développer un thème pour Hugo | Jeff McMorris\nOn en parle de l'interface du CMS ou pas ?\nOui !\nComme 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 !\nCroyez-moi, elles sont toutes bien plus rapides et mieux conçues que ce bon vieux tableau de bord.\nAutres fonctionnalités notables\nAvant 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.\nMultilinguisme\nAu revoir WPML! 🥳\nHugo gère nativement le multilingue, y compris l'i18n et la traduction de chaînes de caractères.\nReportez-vous à l'article complet de Régis Philibert sur la gestion multilingue dans Hugo.\nMenus\nLes 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.\nLa solution proposée par Hugo pour les menus vous laisse assigner n'importe quelle page à un menu ou à une url externe.\nConcrètement, si vous avez deux menus sur votre site, vous assigner une page donnée à un menu de la sorte :\n# \/content\/a-propos.md\ntitle: À propos\nmenu:\n main:\n name: Qui suis-je?\n weight: 2\n footer:\n weight: 1\nSi vous avez besoin d'ajouter une url externe au menu main, ça se fait au niveau de la configuration de votre site :\n# \/config.yaml\nmenus:\n main:\n - name: Blog\n url: https:\/\/blog.tumblr.com\n weight: 3\n footer:\n - name: Blog\n url: https:\/\/blog.tumblr.com\nDans 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.\nEn plus de cela, les deux menus incluent un lien externe Blog qui pointe vers votre ancien blog tumblr.\nContrairement à WordPress, il n'y a pas de notion d'emplacement de menu.\nVous 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.\nEncore 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 🏃‍♀️).\nChamps personnalisés\nAvec 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.\nHugo, 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\".\nCela permet de stocker tous les paramètres non réservés de votre contexte de page dans l'objet .Params.\nDonc dans votre gabarit, plutôt que :\n<?php if ($subfield = get_field('subfield')){ echo $subfield; } ?>\nvous écrivez :\n{{ with .Params.subtitle }}{{ . }}{{ end }}\n.................................................... ☝️ Vous allez l'aimer ce point !\nLes options génériques du site\nQu'en est-il de ces options génériques non rattachées à une page en particulier ?\nEt 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 !\nHugo 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.\nSi 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.\nDonc 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.\n# data\/socials.yaml\n- title: Facebook\n icon: fb\n url: https:\/\/facebook.com\/hugo_rocks\n- title: Twitter\n icon: tw\n url: https:\/\/twitter.com\/hugoRocks\n# data\/options.yaml\nsocials: true\ntagline: Hugo rocks!\nEt dans votre fichier partiel…\n{{\/* layouts\/partials\/socials.html *\/}}\n{{ if .Site.Data.options.social }}\n<ul class=\"socials\">\n {{ range .Site.Data.socials }}\n <li>\n <a href=\"{{ .url }}\"><i class=\"icon icon-{{ .icon }}\"><\/i> {{ .title }}<\/a>\n <\/li>\n {{ end }}\n<\/ul>\n{{ end }}\nUtilisation des fichiers de données dans Hugo par l'exemple | Peter Y. Chuang\nCommentaires\nJe 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.\nComme 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.\nHeureusement il existe un support natif de Disqus prêt à l'emploi.\nEt 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.\n\nRemplacer Disqus avec les commentaires Github | Don Williamson\nHugo + Staticman : réponses imbriquées et notifications par email | Dan C Williams\n\nFormulaires\nLà aussi, il faut passer par un service tiers, le plus souvent gratuit, par exemple :\n\nFormkeep.io\nNetlify's forms\nTypeForm\n\nContenu relatif\nGé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.\nHugo 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\nRecherche\nComme 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 :\n\nLunr.js 🆓\nAlgolia et leur incroyable widget InstantSearch.js (🆓 pour les sites de petite et moyenne tailles)\n\n\nRecherche sur Bleve avec Hugo\nRecherche côté client pour Hugo avec Fuse.js (Eddie Webb)\n\nConclusion\nCet 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.\nNous 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 ! 🏃", "content_html": "

Dans cet article, nous n'allons pas migrer un site de WordPress vers Hugo, nous allons voir comment passer des habitudes que vous avez prises avec WordPress à celles d'Hugo.

\n

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.

\n

Nous allons partir de the_post(), the_loop et de la hiérarchie de modèle, pour mieux comprendre comment Hugo fonctionne !

\n

De WordPress à Hugo

\n

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.\nMoi aussi je faisais principalement du développement avec WordPress, avant de devenir complètement accro à Hugo.

\n

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.

\n

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.

\n

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.

\n

Donc si vous débutez avec Hugo, et que vous connaissez WordPress, ce qui va suivre ne pourra que vous être bénéfique.

\n

Tout est page

\n

Cette affirmation catégorique est essentielle pour mieux appréhender le fonctionnement d'Hugo, surtout en ce qui concerne la logique dans les gabarits.

\n

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.

\n

On peut le voir ainsi : tout ce qui possède une URL, c'est une page !

\n

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.

\n

Type

\n

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).

\n

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 :

\n
    \n
  1. Vous ajoutez le type désiré dans le front matter
    2. \n
  2. Ou plus généralement, vous laissez le premier niveau d'arborescence de contenu définir le type du fichier.
    3. \n
\n

Donc pour créer une page de type recette, vous pouvez soit écrire le front matter suivant :

\n
title: De délicieux cupcakes\ntype: recette\n---
\n

Ou vous reposer sur la structure de votre arborescence et laisser faire la magie :

\n
content\n  ├── post\n  └── recette\n      └── de-delicieux-cupcakes.md
\n

Kind

\n

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.

\n

D'où les fonctions booléennes is_single(), is_archive()!

\n

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.

\n

Voici différents exemples de valeurs pour kind :

\n\n

Modèles et hiérarchie

\n

Maintenant que nous avons vu Type et Kind, plongeons nous dans la logique des gabarits de page d'Hugo.

\n

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.

\n

En plus des conventions sur les noms de fichier, Hugo se base aussi sur l'arborescence des dossiers pour savoir quel modèle appliquer.

\n\n

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.

\n\n

Les modèles de page personnalisés

\n

C'est un des trucs plus anciens de WordPress.

\n

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 :

\n
<?php /* Template Name: Custom 🤮 */ ?>
\n

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.

\n

Ensuite nommez votre fichier d'après la valeur définie pour layout, placez-le dans le dossier layouts/_default/ et c'est bon !

\n
---\ntitle: À propos\nlayout: about\n---\nÀ propos de moi !
\n
layouts\n  └── _default\n      └── about.html\n
\n

Les fichiers includes

\n

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.

\n

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.

\n

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.

\n

On inclut un fichier partiel ainsi :

\n
{{ partial \"post-head\" . }}
\n

Le point ci-dessus .............☝️ correspond à la page courante.

\n

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.

\n\n

La boucle et les données

\n

Les variables de Page

\n

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.

\n

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.

\n

Dans Hugo, les équivalents aux expressions WordPress citées un peu plus haut sont .Permalink, .Title , .Content, .Date.

\n

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 :

\n
{{/* layouts/partials/post-head.html */}}\n<div class=\"post-head\">\n  <h1><a href=\"{{ .Permalink }}\">{{ .Title }}</a><h1>\n  <time>{{ .Date }}</time>\n</div>
\n

Boucler avec range

\n

Pouvoir parcourir des articles pour construire des pages archives ou un widget Derniers articles est essentiel pour un moteur de template.

\n

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.

\n

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.

\n

Avec Hugo, dans les gabarits de listes, les pages concernées sont stockées dans une collection et sont accessibles via l'objet .Pages.

\n

Cela fait que pour le modèle de liste de la section recettes, .Pages retournera la collection des pages correspondantes : recettes.

\n

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.

\n

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 ..

\n

Comparaison des boucles

\n

Voici notre boucle WordPress tant aimée :

\n
// theme/archive.php\n<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>\n  <!-- post -->\n  <h2>\n    <a href=\"<?php the_permalink(); ?>\"><?php the_title() ?></a>\n  </h2>\n  <h6><?php the_date(); ?></h6>\n  <p>\n    <?php the_excerpt(); ?>\n  </p>\n  <hr>\n<?php endwhile; ?>\n<?php else: ?>\n<!-- aucun post trouvé -->\n<?php endif; ?>
\n

La même chose en beaucoup plus lisible et succinct avec Hugo, grâce à la transmission du contexte dans les fonctions :

\n
//layouts/_default/list.html\n{{ with .Pages }}\n  {{ range . }}\n    <h2>\n      <a href=\"{{ .Permalink }}\">{{ .Title }}</a>\n    </h2>\n    <h6>{{ .Date.Format \"January, 02 2006\" }}</h6>\n    <p>\n      {{ .Summary }}\n    </p>\n    <hr>\n  {{ end }}\n{{ else }}\n<!-- aucun élément trouvé -->\n{{ end }}
\n

Qu'en-est-il des autres pages ?

\n

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.

\n

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.

\n

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 :

\n
<?php\n$recents = new WP_Query(\n  [\n    'post_type'=>'recipe',\n    'posts_per_page'=>5,\n    'orderby'   => 'meta_value_num',\n    'meta_key'  => 'rating',\n  ]\n);\nif ( $recents->have_posts() ) : while ( $recents->have_posts() ) : $recents->the_post(); ?>\n  <h2>\n    <a href=\"<?php $recents->the_permalink(); ?>\"><?php $recents->the_title() ?></a>\n  </h2>\n<!-- post -->\n<?php endwhile; ?>\n<?php else: ?>\n<!-- aucune entrée trouvée -->\n<?php endif; ?>\n?>
\n

Et voici son élégante variante avec Hugo :

\n
{{ $recents := (where .Site.RegularPages \"Type\" \"recipe\").ByParam \"rating\" }}\n{{ range first 5 $recents }}\n  <h2>\n    <a href=\"{{ .Permalink }}\">{{ .Title }}</a>\n  </h2>\n{{ end }}
\n\n

Les shortcodes

\n

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.

\n

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.

\n\n

Les shortcodes par l'exemple

\n

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.

\n
<?php\nfunction caption_shortcode( $atts, $content = null ) {\n  $a = shortcode_atts( array(\n    'class' => 'caption',\n  ), $atts );\n\n  return '<span class=\"' . esc_attr($a['class']) . '\">' . $content . '</span>';\n}\nadd_shortcode( 'caption', 'caption_shortcode' );
\n

Le shortcode s'utilise ensuite ainsi :

\n
[caption class=\"headline\"]My Caption[/caption]
\n

Voyons maintenant la réponse en une ligne d'Hugo :

\n
{{/* layouts/shortcodes/caption.html */}}\n<span class=\"{{ default \"caption\" (.Get 0) }}\">{{ .Inner }}</span>
\n

On écrira dans son fichier Markdown :

\n
{{%/* caption \"headline\" */%}}My Caption{{%/* /caption */%}}
\n

Nous avons opté pour l'utilisation de la position… car il n'y a qu'un seul paramètre 🤷

\n\n

Paramètres

\n

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.

\n

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 :

\n\n

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.

\n

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.

\n

Formats de sortie

\n

Hein, c'est quoi ça ?

\n

Ah oui c'est vrai, WordPress ne vous a pas présenté.

\n

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.

\n

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.

\n

Pour résumer :

\n
# config.yaml\noutputs:\n  homepage:\n    - HTML\n    - JSON\n  page:\n    - HTML\n    - AMP
\n
layouts\n  ├── _default\n  │   └── about.html\n  ├── index.html\n  ├── index.json\n  └── recipes\n      └── single.amp.html
\n

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 !

\n

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 !

\n\n

Traitement des assets

\n

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.

\n

Hugo propose lui sa propre suite d'outils de traitement des assets !

\n

-- Heeein?\n-- Oui! Ça s'appelle les tuyaux d'Hugo et sans aucune dépendance node vous pouvez :

\n\n

Avec quelques dépendances vous pouvez :

\n\n

Le tout avec la même élégance à laquelle vous devez commencer à vous habituer :

\n
{{ $style := resources.Get \"main.scss\" | toCSS | minify | fingerprint }}\n<link href=\"{{ $style.Permalink }}\" rel=\"stylesheet\">
\n

Hugo s'assurera également que ces assets sont compilés et publiés uniquement si vous appelez leur .Permalink dans vos templates.

\n

Traitement des images

\n

Le traitement d'image par défaut de WordPress se fait uniquement lors de l'étape initiale de téléversement.

\n

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.

\n

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.

\n
{{ $img := resources.Get \"header.jpg\" | .Resize \"600x\" }}\n<img src=\"{{ $img.Permalink }}\" alt=\"\">
\n

Je sais! Moi aussi je ne me lasse pas de ces instructions sur deux lignes !

\n

Vous pouvez lancer des traitements d'images, soit à l'aide des tuyaux d'Hugo ou des ressources de page.

\n\n

Thèmes et Plugins VS Composants de Thème

\n

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.

\n

Pour les thèmes, WordPress ne vous donne que deux niveaux de personnalisation.\nVous 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.

\n

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.

\n

Dans Hugo, on ne parle pas de plugins et des thèmes mais plutôt de composants.\nVous pouvez en ajouter autant que vous voulez.

\n

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.

\n

Voyez les composants comme des thèmes enfant illimités !

\n

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.

\n

Le thème par l'exemple

\n

Prenons pour exemple un projet fictif de clinique dentaire, où personne ne veut avoir à trop mettre les mains dans le code. Vous aurez besoin :

\n\n

Avec WordPress il vous faudrait :

\n\n

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. 🤷‍♂️

\n

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.

\n
theme:\n  - health-theme\n  - health-theme-dental-extension\n  - health-theme-season-extension\n  - mega-menu-component\n  - medical-shortcodes-component\n  - json-api-component\n\noutput:\n  page:\n    - HTML\n    - JSON
\n

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.

\n

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).

\n\n

On en parle de l'interface du CMS ou pas ?

\n

Oui !

\n

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 !

\n

Croyez-moi, elles sont toutes bien plus rapides et mieux conçues que ce bon vieux tableau de bord.

\n

Autres fonctionnalités notables

\n

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.

\n

Multilinguisme

\n

Au revoir WPML! 🥳

\n

Hugo gère nativement le multilingue, y compris l'i18n et la traduction de chaînes de caractères.

\n

Reportez-vous à l'article complet de Régis Philibert sur la gestion multilingue dans Hugo.

\n

Menus

\n

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.

\n

La solution proposée par Hugo pour les menus vous laisse assigner n'importe quelle page à un menu ou à une url externe.

\n

Concrètement, si vous avez deux menus sur votre site, vous assigner une page donnée à un menu de la sorte :

\n
# /content/a-propos.md\ntitle: À propos\nmenu:\n  main:\n    name: Qui suis-je?\n    weight: 2\n  footer:\n    weight: 1
\n

Si vous avez besoin d'ajouter une url externe au menu main, ça se fait au niveau de la configuration de votre site :

\n
# /config.yaml\nmenus:\n  main:\n    - name: Blog\n      url: https://blog.tumblr.com\n      weight: 3\n  footer:\n    - name: Blog\n      url: https://blog.tumblr.com
\n

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.\nEn plus de cela, les deux menus incluent un lien externe Blog qui pointe vers votre ancien blog tumblr.

\n

Contrairement à WordPress, il n'y a pas de notion d'emplacement de menu.\nVous 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.

\n

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 🏃‍♀️).

\n

Champs personnalisés

\n

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.

\n

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\".\nCela permet de stocker tous les paramètres non réservés de votre contexte de page dans l'objet .Params.

\n

Donc dans votre gabarit, plutôt que :

\n
<?php if ($subfield = get_field('subfield')){ echo $subfield; } ?>
\n

vous écrivez :

\n
{{ with .Params.subtitle }}{{ . }}{{ end }}
\n

.................................................... ☝️ Vous allez l'aimer ce point !

\n

Les options génériques du site

\n

Qu'en est-il de ces options génériques non rattachées à une page en particulier ?

\n

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 !

\n

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.

\n

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.

\n

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.

\n
# data/socials.yaml\n- title: Facebook\n  icon: fb\n  url: https://facebook.com/hugo_rocks\n- title: Twitter\n  icon: tw\n  url: https://twitter.com/hugoRocks
\n
# data/options.yaml\nsocials: true\ntagline: Hugo rocks!
\n

Et dans votre fichier partiel…

\n
{{/* layouts/partials/socials.html */}}\n{{ if .Site.Data.options.social }}\n<ul class=\"socials\">\n  {{ range .Site.Data.socials }}\n    <li>\n      <a href=\"{{ .url }}\"><i class=\"icon icon-{{ .icon }}\"></i> {{ .title }}</a>\n    </li>\n  {{ end }}\n</ul>\n{{ end }}
\n\n

Commentaires

\n

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.

\n

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.

\n

Heureusement il existe un support natif de Disqus prêt à l'emploi.

\n

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.

\n\n

Formulaires

\n

Là aussi, il faut passer par un service tiers, le plus souvent gratuit, par exemple :

\n\n

Contenu relatif

\n

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.

\n

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

\n

Recherche

\n

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 :

\n\n\n

Conclusion

\n

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.

\n

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 ! 🏃

", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/02/05/implementer-les-categories-dans-eleventy/", "url": "https://jamstatic.fr/2019/02/05/implementer-les-categories-dans-eleventy/", "title": "Implémenter les catégories dans Eleventy", "summary": "Comment créer une collection afin de pouvoir travailler avec des catégories dans le générateur Eleventy.", "date_published": "2019-02-05T08:15:06+00:00", "date_modified": "2019-02-06T08:10:26+00:00","content_text": "Je veux disposer de catégories dans Eleventy afin de pouvoir dispatcher\nmes articles dans divers domaines génériques 1. L'idée c'est que tous les\narticles sur les livres aillent dans la catégorie \"Culture\", les articles\ntechniques dans la catégorie \"Tech\", etc.\n\nUn article n'a pas besoin de préciser une catégorie.\nUn article ne peut appartenir qu'à une seule catégorie\nPar convention, les noms de catégories commencent par une majuscule.\n\nLes tags, eux, peuvent figurer dans n'importe quelle catégorie. Un livre\nétrange et un article technique fantaisiste appartiennent à des\ncatégories différentes, mais peuvent très bien être tous les deux étiquettés \"bizarre\".\nComment ça marche à l'usage ?\nRegardons comment nous allons utiliser les catégories :\n\nComment préciser la catégorie d'un article,\nComment accéder à la catégorie d'un article dans un modèle\nComment manipuler tous les articles d'une même catégorie\n\nPréciser la catégorie\nOn utilise la propriété category ainsi pour préciser la catégorie à laquelle\nappartient l'article :\n---\ndate: 10\/30\/2018\ntitle: Loomings\ncategory: Tech\ntags:\n - tools\n - git\n - eleventy\n---\n\nAppeler la catégorie dans un modèle\nDans un modèle, on fait référence à la propriété catégorie comme d'habitude :\n<a href=\"\/categories\/{{category}}\">{{ category }}<\/a>\nManipuler les articles d'une même catégorie\nOn peut manipuler les articles d'une même catégories en créant une collection categories 2.\nPour lister tous les articles rangés dans la catégorie Tech, on pourrait procéder de la sorte :\n<ul>\n {%- for article in collections.categories[\"Tech\"] -%}\n <li>{{ article.data.title }}<\/li>\n {%- endfor -%}\n<\/ul>\nTout comme l'objet collections possède une propriété pour chaque tag, l'objet\ncollections.categories possède une propriété pour chaque catégorie.\nChaque propriété fait référence à un tableau d'articles. Ça donne quelque chose comme ça :\ncollections: {\n all: [ items ],\n categories: {\n Culture: [ items ],\n Life: [ items ],\n Thinking: [ items ]\n }\n}\nImplémentation\nNous voulons :\n\nune liste de catégories\nun objet qui contient une propriété pour chaque catégorie, chaque propriété est une liste d'articles pour cette catégorie\n\nCréer une liste de catégories\nPour générer une liste de catégories nous itérons sur tous les fichiers générés.\nCette fonction crée une collection categoryList qui contient les noms de toutes les catégories.\ngetCatList = function (collection) {\n let catSet = new Set();\n\n collection\n .getAllSorted()\n .forEach(\n (item) =>\n typeof item.data.category === \"string\" && catSet.add(item.data.category)\n );\n\n return [...catSet];\n};\n\neleventyConfig.addCollection(\"categoryList\", getCatList);\nCréer une liste d'articles pour chaque catégorie\nPour 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 :\ncategories {\n Culture: [article_1, article_4],\n Tech: [article_3],\n Life: [article_1, article_3]\n}\nNous 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 3 :\nmakeCategories = function (collection) {\n let categories = {};\n\n \/\/ Every rendered page\n\n collection.getAllSorted().forEach((item) => {\n let category = item.data.category;\n\n \/\/ Ignore the ones without a category\n\n if (typeof category !== \"string\") return;\n\n if (Array.isArray(categories[category]))\n \/\/ category array exists? Just push\n categories[category].push(item);\n \/\/ Otherwise create it and\n \/\/ make `item` the first, uh, item.\n else categories[category] = [item];\n });\n\n return categories;\n};\nPuisque nous souhaitons appeler notre collection de catégories catgories, nous la créons comme cela :\naddCollection(\"categories\", makeCategories);\nNous 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.\n\n\n\n\nÇa c'est ce que je dis maintenant. Ma première motivation était de comprendre comment marchent les collections.] ↩\n\n\nVous l'appelez comme vous voulez. Il se trouve que j'aime bien \"categories\". ↩\n\n\nCe if (Array.isArray(categories[category])) est vraiment stupide. N'existe-t-il pas un moyen d'ajouter un élément dans un tableau et de le créer au passage s'il n'existe pas ? ↩\n\n\n", "content_html": "

Je veux disposer de catégories dans Eleventy afin de pouvoir dispatcher\nmes articles dans divers domaines génériques 1. L'idée c'est que tous les\narticles sur les livres aillent dans la catégorie \"Culture\", les articles\ntechniques dans la catégorie \"Tech\", etc.

\n\n

Les tags, eux, peuvent figurer dans n'importe quelle catégorie. Un livre\nétrange et un article technique fantaisiste appartiennent à des\ncatégories différentes, mais peuvent très bien être tous les deux étiquettés \"bizarre\".

\n

Comment ça marche à l'usage ?

\n

Regardons comment nous allons utiliser les catégories :

\n\n

Préciser la catégorie

\n

On utilise la propriété category ainsi pour préciser la catégorie à laquelle\nappartient l'article :

\n
---\ndate: 10/30/2018\ntitle: Loomings\ncategory: Tech\ntags:\n  - tools\n  - git\n  - eleventy\n---\n
\n

Appeler la catégorie dans un modèle

\n

Dans un modèle, on fait référence à la propriété catégorie comme d'habitude :

\n
<a href=\"/categories/{{category}}\">{{ category }}</a>
\n

Manipuler les articles d'une même catégorie

\n

On peut manipuler les articles d'une même catégories en créant une collection categories 2.\nPour lister tous les articles rangés dans la catégorie Tech, on pourrait procéder de la sorte :

\n
<ul>\n  {%- for article in collections.categories[\"Tech\"] -%}\n  <li>{{ article.data.title }}</li>\n  {%- endfor -%}\n</ul>
\n

Tout comme l'objet collections possède une propriété pour chaque tag, l'objet\ncollections.categories possède une propriété pour chaque catégorie.\nChaque propriété fait référence à un tableau d'articles. Ça donne quelque chose comme ça :

\n
collections: {\n  all: [ items ],\n  categories: {\n    Culture: [ items ],\n    Life: [ items ],\n    Thinking: [ items ]\n  }\n}
\n

Implémentation

\n

Nous voulons :

\n\n

Créer une liste de catégories

\n

Pour générer une liste de catégories nous itérons sur tous les fichiers générés.\nCette fonction crée une collection categoryList qui contient les noms de toutes les catégories.

\n
getCatList = function (collection) {\n  let catSet = new Set();\n\n  collection\n    .getAllSorted()\n    .forEach(\n      (item) =>\n        typeof item.data.category === \"string\" && catSet.add(item.data.category)\n    );\n\n  return [...catSet];\n};\n\neleventyConfig.addCollection(\"categoryList\", getCatList);
\n

Créer une liste d'articles pour chaque catégorie

\n

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 :

\n
categories {\n  Culture: [article_1, article_4],\n  Tech: [article_3],\n  Life: [article_1, article_3]\n}
\n

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 3 :

\n
makeCategories = function (collection) {\n  let categories = {};\n\n  // Every rendered page\n\n  collection.getAllSorted().forEach((item) => {\n    let category = item.data.category;\n\n    // Ignore the ones without a category\n\n    if (typeof category !== \"string\") return;\n\n    if (Array.isArray(categories[category]))\n      //  category array exists? Just push\n      categories[category].push(item);\n    //  Otherwise create it and\n    //  make `item` the first, uh, item.\n    else categories[category] = [item];\n  });\n\n  return categories;\n};
\n

Puisque nous souhaitons appeler notre collection de catégories catgories, nous la créons comme cela :

\n
addCollection(\"categories\", makeCategories);
\n

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.

\n
\n
\n
    \n
  1. \n

    Ça c'est ce que je dis maintenant. Ma première motivation était de comprendre comment marchent les collections.] ↩

    \n
    2. \n
  2. \n

    Vous l'appelez comme vous voulez. Il se trouve que j'aime bien \"categories\". ↩

    \n
    3. \n
  3. \n

    Ce if (Array.isArray(categories[category])) est vraiment stupide. N'existe-t-il pas un moyen d'ajouter un élément dans un tableau et de le créer au passage s'il n'existe pas ? ↩

    \n
    4. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/01/29/les-collections-dans-eleventy/", "url": "https://jamstatic.fr/2019/01/29/les-collections-dans-eleventy/", "title": "Les collections dans Eleventy", "summary": "Les deux manières de créer des collections de documents avec le générateur de site statique Eleventy.", "date_published": "2019-01-29T07:54:22+00:00","content_text": "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.\nDans Eleventy les collections permettent de grouper des articles selon divers\ncritères. Une collection pourrait désigner une série d'articles. Un autre\ncollection pourrait regrouper les articles à propos de livres. Une troisième\ncollection pourrait rassembler tous les contenus d'un même répertoire.\nEleventy vous permet de créer des collections de deux manières :\n\nimplicitement, à l'aide de tags dans le front matter\nexplicitement, avec la fonction addCollection()\n\nLes collections à base de tags\nToutes les pages qui partagent un même tag appartiennent à la même collection.\nUn modèle avec le front matter suivant va générer des pages dans les collections\nbooks et reviews.\n---\ntitle: Finding Oz\ncategory: Culture\ntags:\n - books\n - reviews\n---\n. . .\nDans un modèle, on accède aux collections par leur nom, en tant que propriété de\nl'object global collections.\n<p>\n Le titre de cette page est :\n {{ collections.books[0].data.title }}\n<\/p>\nOn utilise généralement les collections dans des boucles afin d'itérer sur\nchaque élément de la collection.\n{% for post in collections.books %}\n {{ post.data.title }}\n {{ post.url }}\n {{ post.data.category }}\n {{ post.data.tags }}\n {{ post.date }}\n{% endfor %}\nL'objet collections lui, ressemble à ça :\n{\n \"all\": [...],\n \"nav\": [...],\n \"books\": [\n {\n \"inputPath\": \".\/src\/articles\/finding-oz.md\",\n \"outputPath\": \"_site\/articles\/finding-oz\/index.html\",\n \"fileSlug\": \"finding-oz\",\n \"data\": {...},\n \"date\": \"2009-08-07T13:52:12.000Z\",\n \"url\": \"\/articles\/finding-oz\/\",\n \"templateContent\": \"<p>As with most books ... much about The Wizard of Oz<\/li>\\n<\/ul>\\n\",\n \"template\": {...}\n },\n ...\n ],\n \"programming\": [...],\n}\nChaque propriété est un tableau d'objets d'éléments de\ncollection\n(également appelés objets\nmodèle dans la\ndocumentation).\nLa collection spéciale all représente un tableau de tous les objets page\ngénérés par Eleventy.\n\n\n\nPropriété\nDescription\n\n\n\n\ninputPath\nChemin vers ce fichier incluant le répertoire source. .\/src\/articles\/finding-oz.md\n\n\noutputPath\nChemin du fichier généré. articles\/finding-oz\/index.html\n\n\nfileSlug\nVersion courte en fonction du nom et de l'emplacement du fichier. En fonction des règles. finding-oz\n\n\ndata\nDonnées du front matter de la page rendue. Les variables globales disponibles pour chaque page.\n\n\ndate\nLa date du fichier au format UTC. Voir les règles. 2019-01-27T13:52:12.000Z\n\n\nurl\nChemin vers le contenu. N'inclus pas le protocole et le nom d'hôte. \/articles\/finding-oz\/\n\n\ntemplateContent\nLe contenu généré de la page, n'inclut pas les balises enveloppantes de mise en page.<p>Comme la plupart des livres ... à propos du Magicien d'Oz<\/li>\\n<\/ul>\\n\n\n\ntemplate\nToutes sortes de données analysées par le modèle. Des choses comme la configuration d'Eleventy, la configuration du moteur de rendu pour le markdown, et beaucoup de choses sur lesquelles nous ne devrions probablement pas nous baser.\n\n\n\nImplémentation : Comment un tag devient une collection\ngetTaggedCollectionsData() est la fonction qui transforme des tags en collections.\nasync getTaggedCollectionsData() {\nlet collections = {};\ncollections.all = this.createTemplateMapCopy(\nthis.collection.getAllSorted()\n);\ndebug(`Collection: collections.all size: ${collections.all.length}`);\n\nlet tags = this.getAllTags();\nfor (let tag of tags) {\ncollections[tag] = this.createTemplateMapCopy(\nthis.collection.getFilteredByTag(tag)\n);\ndebug(`Collection: collections.${tag} size: ${collections[tag].length}`);\n}\nreturn collections;\n}\ngetTaggedCollectionsData() est appelée dans TemplateMap.cache() qui est\nl'endroit ou Eleventy génère les collections.\nLes collections sur mesure\nOutre les collections créées à partir de tags, vous pouvez utiliser la fonction\naddCollection() dans votre fichier de configuration .eleventy.js pour créer\nvos propres collections.\nPar exemple, voici comment créer une collection nommée articles constituée de pages\ngénérées à partir de modèles présents dans le dossier src\/articles\/ :\neleventyConfig.addCollection(\"articles\", (collection) =>\n collection\n .getAllSorted()\n .filter(\n (item) =>\n item.url &&\n !item.inputPath.includes(\"index.njk\") &&\n item.inputPath.startsWith(\".\/src\/articles\/\")\n )\n);\nLa fonction addCollection() prend deux paramètres1 :\n\nle nom de la collection (une chaîne de caractères)\nune fonction qui prend une collection en paramètre.\n\nVous pourriez penser que le paramètre collection est un tableau d'objets de\nmodèle comme l'objet collections basé sur les tags. Ce paramètre est en fait\nune instance d'une TemplateCollection, qui dérive de\nSortable, et ressemble à ceci :\n{\n \"items\": [\n { ... },\n . . .\n { ... }\n ],\n \"sortFunctionStringMap\": { ... },\n \"sortAscending\": true,\n \"sortNumeric\": false\n}\nLa propriété items est un tableau de tous les objets de modèle. C'est la même\nchose que collections.all. Vous ne voulez pas accéder aux éléments directement\nen écrivant : collection.item[n].\nUtilisez plutôt les méthodes suivantes pour accéder aux éléments.\n\n\n\nMéthode\nDescription\n\n\n\n\ngetAll()\nRécupérer tous les éléments dans un ordre spécifique.\n\n\ngetAllSorted()\nRécupérer tous les éléments dans l'ordre.\n\n\ngetFilteredByTag(tagName)\nRécupérer tous les éléments qui possèdent un tag spécifique.\n\n\ngetFilteredByGlob(glob)\nRécupérer tous les éléments dont l' inputPath correspond à un ou plusieurs patterns globaux.\n\n\n\nLes éléments sont presque les mêmes que ceux des\ncollections basées sur des tags, à la différence près que dans les collections\nbasées sur des tags, les éléments ont une propriété templateContent. Dans les\ncollections créées avec la fonction addCollection(), les éléments ont une\npropriété _pages. Je ne saurais dire pourquoi.\nVous pouvez utiliser addCollection() pour créer des collections de pages.\nDepuis Eleventy 0.5.3, vous pouvez l'utiliser pour créer des collections ou des\nobjets de votre choix.\nPar exemple, voici comment vous créeriez une collection constituée d'un tableau\nde toutes les catégories :\nmodule.exports = function (collection) {\n let catSet = new Set();\n\n collection\n .getAllSorted()\n .forEach(\n (item) =>\n typeof item.data.category === \"string\" && catSet.add(item.data.category)\n );\n\n return [...catSet];\n};\nImplémentation : Comment sont construites les collections sur mesure\ngetUserConfigCollectionsData() est la fonction qui appelle ce qui est retourné par la fonction addCollection().\nasync getUserConfigCollectionsData() {\nlet collections = {};\nlet configCollections =\nthis.configCollections || eleventyConfig.getCollections();\nfor (let name in configCollections) {\nlet ret = configCollections[name](this.collection);\n\/\/ work with arrays and strings returned from UserConfig.addCollection\nif (\nArray.isArray(ret) &&\nret.length &&\nret[0].inputPath &&\nret[0].outputPath\n) {\ncollections[name] = this.createTemplateMapCopy(ret);\n} else {\ncollections[name] = ret;\n}\ndebug(\n`Collection: collections.${name} size: ${collections[name].length}`\n);\n}\nreturn collections;\n}\ngetUserConfigCollectionsData() est appelé dans TemplateMap.cache() qui est\nl'endroit où Eleventy construit les collections.\n\n\n\n\naddCollection() ne fait rien d'autre qu'associer la fonction\nqui construit la collection au nom de la collection.\nLa fonction qui construit la collection est elle-même appelée plus tard dans\ngetUserConfigCollectionsData(). ↩\n\n\n", "content_html": "\n

Dans Eleventy les collections permettent de grouper des articles selon divers\ncritères. Une collection pourrait désigner une série d'articles. Un autre\ncollection pourrait regrouper les articles à propos de livres. Une troisième\ncollection pourrait rassembler tous les contenus d'un même répertoire.

\n

Eleventy vous permet de créer des collections de deux manières :

\n\n

Les collections à base de tags

\n

Toutes les pages qui partagent un même tag appartiennent à la même collection.\nUn modèle avec le front matter suivant va générer des pages dans les collections\nbooks et reviews.

\n
---\ntitle: Finding Oz\ncategory: Culture\ntags:\n  - books\n  - reviews\n---\n. . .
\n

Dans un modèle, on accède aux collections par leur nom, en tant que propriété de\nl'object global collections.

\n
<p>\n  Le titre de cette page est :\n  {{ collections.books[0].data.title }}\n</p>
\n

On utilise généralement les collections dans des boucles afin d'itérer sur\nchaque élément de la collection.

\n
{% for post in collections.books %}\n  {{ post.data.title }}\n  {{ post.url }}\n  {{ post.data.category }}\n  {{ post.data.tags }}\n  {{ post.date }}\n{% endfor %}
\n

L'objet collections lui, ressemble à ça :

\n
{\n  \"all\": [...],\n  \"nav\": [...],\n  \"books\": [\n    {\n      \"inputPath\": \"./src/articles/finding-oz.md\",\n      \"outputPath\": \"_site/articles/finding-oz/index.html\",\n      \"fileSlug\": \"finding-oz\",\n      \"data\": {...},\n      \"date\": \"2009-08-07T13:52:12.000Z\",\n      \"url\": \"/articles/finding-oz/\",\n      \"templateContent\": \"<p>As with most books ... much about The Wizard of Oz</li>\\n</ul>\\n\",\n      \"template\": {...}\n    },\n    ...\n  ],\n  \"programming\": [...],\n}
\n

Chaque propriété est un tableau d'objets d'éléments de\ncollection\n(également appelés objets\nmodèle dans la\ndocumentation).

\n

La collection spéciale all représente un tableau de tous les objets page\ngénérés par Eleventy.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropriétéDescription
inputPathChemin vers ce fichier incluant le répertoire source.
./src/articles/finding-oz.md
outputPathChemin du fichier généré.
articles/finding-oz/index.html
fileSlugVersion courte en fonction du nom et de l'emplacement du fichier. En fonction des règles.
finding-oz
dataDonnées du front matter de la page rendue. Les variables globales disponibles pour chaque page.
dateLa date du fichier au format UTC. Voir les règles.
2019-01-27T13:52:12.000Z
urlChemin vers le contenu. N'inclus pas le protocole et le nom d'hôte.
/articles/finding-oz/
templateContentLe contenu généré de la page, n'inclut pas les balises enveloppantes de mise en page.
<p>Comme la plupart des livres ... à propos du Magicien d'Oz</li>\\n</ul>\\n
templateToutes sortes de données analysées par le modèle. Des choses comme la configuration d'Eleventy, la configuration du moteur de rendu pour le markdown, et beaucoup de choses sur lesquelles nous ne devrions probablement pas nous baser.
\n

Implémentation : Comment un tag devient une collection

\n

getTaggedCollectionsData() est la fonction qui transforme des tags en collections.

\n
async getTaggedCollectionsData() {\nlet collections = {};\ncollections.all = this.createTemplateMapCopy(\nthis.collection.getAllSorted()\n);\ndebug(`Collection: collections.all size: ${collections.all.length}`);\n\nlet tags = this.getAllTags();\nfor (let tag of tags) {\ncollections[tag] = this.createTemplateMapCopy(\nthis.collection.getFilteredByTag(tag)\n);\ndebug(`Collection: collections.${tag} size: ${collections[tag].length}`);\n}\nreturn collections;\n}
\n

getTaggedCollectionsData() est appelée dans TemplateMap.cache() qui est\nl'endroit ou Eleventy génère les collections.

\n

Les collections sur mesure

\n

Outre les collections créées à partir de tags, vous pouvez utiliser la fonction\naddCollection() dans votre fichier de configuration .eleventy.js pour créer\nvos propres collections.

\n

Par exemple, voici comment créer une collection nommée articles constituée de pages\ngénérées à partir de modèles présents dans le dossier src/articles/ :

\n
eleventyConfig.addCollection(\"articles\", (collection) =>\n  collection\n    .getAllSorted()\n    .filter(\n      (item) =>\n        item.url &&\n        !item.inputPath.includes(\"index.njk\") &&\n        item.inputPath.startsWith(\"./src/articles/\")\n    )\n);
\n

La fonction addCollection() prend deux paramètres1 :

\n\n

Vous pourriez penser que le paramètre collection est un tableau d'objets de\nmodèle comme l'objet collections basé sur les tags. Ce paramètre est en fait\nune instance d'une TemplateCollection, qui dérive de\nSortable, et ressemble à ceci :

\n
{\n  \"items\": [\n    { ... },\n    . . .\n    { ... }\n  ],\n  \"sortFunctionStringMap\": { ... },\n  \"sortAscending\": true,\n  \"sortNumeric\": false\n}
\n

La propriété items est un tableau de tous les objets de modèle. C'est la même\nchose que collections.all. Vous ne voulez pas accéder aux éléments directement\nen écrivant : collection.item[n].\nUtilisez plutôt les méthodes suivantes pour accéder aux éléments.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MéthodeDescription
getAll()Récupérer tous les éléments dans un ordre spécifique.
getAllSorted()Récupérer tous les éléments dans l'ordre.
getFilteredByTag(tagName)Récupérer tous les éléments qui possèdent un tag spécifique.
getFilteredByGlob(glob)Récupérer tous les éléments dont l' inputPath correspond à un ou plusieurs patterns globaux.
\n

Les éléments sont presque les mêmes que ceux des\ncollections basées sur des tags, à la différence près que dans les collections\nbasées sur des tags, les éléments ont une propriété templateContent. Dans les\ncollections créées avec la fonction addCollection(), les éléments ont une\npropriété _pages. Je ne saurais dire pourquoi.

\n

Vous pouvez utiliser addCollection() pour créer des collections de pages.\nDepuis Eleventy 0.5.3, vous pouvez l'utiliser pour créer des collections ou des\nobjets de votre choix.

\n

Par exemple, voici comment vous créeriez une collection constituée d'un tableau\nde toutes les catégories :

\n
module.exports = function (collection) {\n  let catSet = new Set();\n\n  collection\n    .getAllSorted()\n    .forEach(\n      (item) =>\n        typeof item.data.category === \"string\" && catSet.add(item.data.category)\n    );\n\n  return [...catSet];\n};
\n

Implémentation : Comment sont construites les collections sur mesure

\n

getUserConfigCollectionsData() est la fonction qui appelle ce qui est retourné par la fonction addCollection().

\n
async getUserConfigCollectionsData() {\nlet collections = {};\nlet configCollections =\nthis.configCollections || eleventyConfig.getCollections();\nfor (let name in configCollections) {\nlet ret = configCollections[name](this.collection);\n// work with arrays and strings returned from UserConfig.addCollection\nif (\nArray.isArray(ret) &&\nret.length &&\nret[0].inputPath &&\nret[0].outputPath\n) {\ncollections[name] = this.createTemplateMapCopy(ret);\n} else {\ncollections[name] = ret;\n}\ndebug(\n`Collection: collections.${name} size: ${collections[name].length}`\n);\n}\nreturn collections;\n}
\n

getUserConfigCollectionsData() est appelé dans TemplateMap.cache() qui est\nl'endroit où Eleventy construit les collections.

\n
\n
\n
    \n
  1. \n

    addCollection() ne fait rien d'autre qu'associer la fonction\nqui construit la collection au nom de la collection.\nLa fonction qui construit la collection est elle-même appelée plus tard dans\ngetUserConfigCollectionsData(). ↩

    \n
    2. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2019/01/28/meetup-jamstack-paris-1/", "url": "https://jamstatic.fr/2019/01/28/meetup-jamstack-paris-1/", "title": "Meetup Jamstack Paris #1", "summary": "Résumé des deux présentations dédiées à Gatsby.", "date_published": "2019-01-28T17:45:24+00:00","content_text": "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.\nDans 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.\nIl 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é.\nEt 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.\nTous le monde est ravi, la prochaine étape sera de s'attaquer à l'authentification utilisateur et d'ajouter un gestion de panier 💳 e-commerce.\n\n\n\n\nPour 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.\nGrand 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.\nL'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.\n\n\n\n\n👏 Un grand bravo aux organisateurs, le prochain meetup aura lieu le 27 février.\nAu programme encore du Gatsby, cette fois avec du Algolia et du WordPress dedans.\nOn 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.", "content_html": "\n

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.

\n

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é.

\n

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.

\n

Tous le monde est ravi, la prochaine étape sera de s'attaquer à l'authentification utilisateur et d'ajouter un gestion de panier 💳 e-commerce.

\n

\n\n

\n
\n

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.

\n

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.

\n

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.

\n

\n\n

\n
\n

👏 Un grand bravo aux organisateurs, le prochain meetup aura lieu le 27 février.\nAu programme encore du Gatsby, cette fois avec du Algolia et du WordPress dedans.

\n

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.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/12/12/passer-de-jekyll-a-eleventy/", "url": "https://jamstatic.fr/2018/12/12/passer-de-jekyll-a-eleventy/", "title": "Passer de Jekyll à Eleventy", "summary": "Longtemps utilisateur du très populaire Jekyll, Paul Lloyd a décidé de passer à la vitesse supérieure avec Eleventy.", "date_published": "2018-12-12T00:00:00+00:00","content_text": "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.\nAutant 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 ?\nNe 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.\nLa 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.\nEn 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.\nPrésentation d'Eleventy\nEleventy 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).\nVu 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 parcours1.\nTout au long de cet article, nous allons prendre comme exemple le site du Guide Markdown de Matt Cone. Si vous voulez tester les modifications, commencez par cloner le dépôt git et placez-vous dans le dossier du projet :\ngit clone https:\/\/github.com\/mattcone\/markdown-guide.git\ncd markdown-guide\nAvant de commencer\nSi 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 :\n\nInstaller Node.js :\n\n\nMac : 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.\nWindows : Téléchargez l'installateur pour Windows depuis le site web de Node.js et suivez les instructions.\n\n\nInitialiser 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.\n\nSi 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.\nInstaller Eleventy\nMaintenant que Node.js est installé et que votre projet est prêt à utiliser npm, nous pouvons installer Eleventy en tant que dépendance :\nnpm install --save-dev @11ty\/eleventy\nSi vous ouvrez votre package.json vous devriez y voir figurer les lignes suivantes :\n…\n\"devDependencies\": {\n \"@11ty\/eleventy\": \"^0.6.0\"\n}\n…\nNous 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 :\nnpx eleventy --input=README.md --formats=md\nCette commande va générer un fichier HTML dans _site\/README\/index.html.\nEleventy utilise par défaut le même répertoire de destination que Jekyll (_site), comme nous le verrons à de nombreuses reprises pendant cette transition.\nLa configuration\nAlors 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.\nCommençons par créer notre fichier de configuration (.eleventy.js), et reportons les paramètres pertinents du _config.yml dans leurs options équivalentes :\nmodule.exports = function(eleventyConfig) {\n return {\n dir: {\n input: \".\/\", \/\/ Équivalent au paramètre source de Jekyll\n output: \".\/_site\" \/\/ Équivalent au paramètre destination de Jekyll\n }\n };\n};\nQuelques choses bonnes à savoir :\n\nAlors 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).\nPar 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.\n\nLes gabarits de mise en forme\nEleventy 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).\nNous 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 :\nmodule.exports = function(eleventyConfig) {\n \/\/ les alias sont relatifs au répertoire _includes\n eleventyConfig.addLayoutAlias('about', 'layouts\/about.html');\n eleventyConfig.addLayoutAlias('book', 'layouts\/book.html');\n eleventyConfig.addLayoutAlias('default', 'layouts\/default.html');\n\n return {\n dir: {\n input: \".\/\",\n output: \".\/_site\"\n }\n };\n }\nDéterminer le langage à utiliser pour les gabarits\nPar 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.\nLes variables\nDe 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.\nLes variables de site\nEn 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 :\ntitle: \"Markdown Guide\"\nurl: https:\/\/www.markdownguide.org\nbaseurl: \"\"\nrepo: http:\/\/github.com\/mattcone\/markdown-guide\ncomments: false\nauthor:\n name: \"Matt Cone\"\nog_locale: \"en_US\"\nLe 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.\n{\n \"title\": \"Markdown Guide\",\n \"url\": \"https:\/\/www.markdownguide.org\",\n \"baseurl\": \"\",\n \"repo\": \"http:\/\/github.com\/mattcone\/markdown-guide\",\n \"comments\": false,\n \"author\": {\n \"name\": \"Matt Cone\"\n },\n \"og_locale\": \"en_US\"\n }\nLes variables de page\nLe tableau ci-dessous établit la correspondance entre les variables de page.\nRetenez 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.* :\n\n\n\nJekyll\nEleventy\n\n\n\n\npage.url\npage.url\n\n\npage.date\npage.date\n\n\npage.path\npage.inputPath\n\n\npage.id\npage.outputPath\n\n\npage.name\npage.fileSlug\n\n\npage.content\ncontent\n\n\npage.title\ntitle\n\n\npage.foobar\nfoobar\n\n\n\nLorsque d'une itération sur des pages, les valeurs front matter sont accessibles via l'objet data et le contenu via templateContent :\n\n\n\nJekyll\nEleventy\n\n\n\n\nitem.url\nitem.url\n\n\nitem.date\nitem.date\n\n\nitem.path\nitem.inputPath\n\n\nitem.id\nitem.outputPath\n\n\nitem.name\nitem.fileSlug\n\n\nitem.content\nitem.templateContent\n\n\nitem.title\nitem.data.title\n\n\nitem.foobar\nitem.data.foobar\n\n\n\nEspé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.\nLes variables de pagination\nAlors 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 :\n\n\n\nJekyll\nEleventy\n\n\n\n\npagination.page\npagination.pageNumber\n\n\npagination.per_page\npagination.size\n\n\npagination.posts\npagination.items\n\n\npagination.previous_page_path\npagination.previousPageHref\n\n\npagination.previous_page_path\npagination.nextPageHref\n\n\n\nLes filtres\nJekyll propose quelques filtres supplémentaires, en plus de ceux fournis par défaut par Liquid.\nIl 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.\nLe 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 :\n\/\/ {{ variable | jsonify }}\n eleventyConfig.addFilter('jsonify', function (variable) {\n return JSON.stringify(variable);\n });\nLe 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 :\n{{ site.members | where: \"graduation_year\",\"2014\" }}\nPour 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 :\n\/\/ {{ array | where: key,value }}\n eleventyConfig.addFilter('where', function (array, key, value) {\n return array.filter(item => {\n const keys = key.split('.');\n const reducedKey = keys.reduce((object, key) => {\n return object[key];\n }, item);\n\n return (reducedKey === value ? item : false);\n });\n });\nIl se passe pas mal de trucs dans ce filtre, que je vais tenter d'expliquer.\nNous 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 !\nLes includes\nComme 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.\nDans le cas contraire, alors qu'avec Jekyll vous écrivez :\n<!-- page.html -->\n{% include include.html value=\"key\" %}\n\n<!-- include.html -->\n{{ include.value }}\ndans Eleventy, vous allez écrire :\n<!-- page.html -->\n{% include \"include.html\", value: \"key\" %}\n\n<!-- include.html -->\n{{ value }}\nL'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.\nParamétrer Liquid\nVous 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\\.\nEn 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.\nHeureusement pour nous, Eleventy nous laisse passer des options à LiquidJS :\neleventyConfig.setLiquidOptions({\n dynamicPartials: false,\n root: [\n '_includes',\n '.'\n ]\n });\nLes collections\nDans 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.\nLes collections dans Jekyll\nDans 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 :\ncollections:\n - basic-syntax\n - extended-syntax\nElles correspondent aux dossiers _basic-syntax et _extended-syntax, nous pouvons itérer sur leurs contenus de la sorte :\n{% for syntax in site.extended-syntax %}\n {{ syntax.title }}\n{% endfor %}\nLes collections dans Eleventy\nIl existe deux manières de configurer des collections dans Eleventy.\nTout d'abord, en utilisant simplement la propriété tag dans le front matter des fichiers de contenu :\n---\ntitle: Barré\nsyntax-id: barre\nsyntax-summary: \"~~La terre est plate~~\"\ntag: extended-syntax\n---\nNous pouvons ensuite itérer sur les contenus étiquetés de la sorte :\n{% for syntax in collections.extended-syntax %}\n {{ syntax.data.title }}\n{% endfor %}\nEleventy 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) :\neleventyConfig.addCollection('basic-syntax', collection => {\n return collection.getFilteredByGlob('_basic-syntax\/*.md');\n});\n\neleventyConfig.addCollection('extended-syntax', collection => {\n return collection.getFilteredByGlob('_extended-syntax\/*.md');\n});\nNous 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 :\neleventyConfig.addCollection('example', collection => {\n return collection.getFilteredByGlob('_examples\/*.md').sort((a, b) => {\n return a.data.display_order - b.data.display_order;\n });\n});\nAvec un peu de chance, cet exemple vous a fait comprendre ce qu'il est possible de faire avec cette approche.\nUtiliser les données de répertoire pour définir les paramètres par défaut\nPar 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\n\/_basic-syntax\/lists.md sera généré sous \/_basic-syntax\/lists\/index.html.\nComme 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 :\n---\ntitle: Lists\nsyntax-id: lists\napi: \"no\"\npermalink: \/basic-syntax\/lists.html\n---\nLà 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.\nPar 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é :\n{\n \"layout\": \"syntax\",\n \"tag\": \"basic-syntax\",\n \"permalink\": \"basic-syntax\/{{ title | slug }}.html\"\n}\nMaintenant, 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 :\nmarkdown-guide\n└── _content\n ├── basic-syntax\n ├── extended-syntax\n ├── getting-started\n └── _content.json\nAjoutons é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 :\n{\n \"permalink\": false\n}\nLes fichiers statiques\nEleventy 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.\nPuis nous activons cette fonctionnalité dans ce qui est retourné, en mettant passthroughFileCopy à true :\nmodule.exports = function(eleventyConfig) {\n …\n\n \/\/ Copy the `assets` directory to the compiled site folder\n eleventyConfig.addPassthroughCopy('assets');\n\n return {\n dir: {\n input: \".\/\",\n output: \".\/_site\"\n },\n passthroughFileCopy: true\n };\n}\nConsidérations finales\nGestion des assets\nContrairement à 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.\nPublication sur GitHub Pages\nUn 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 !\nC'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.\nRappelez-vous cependant que vous pouvez publier un site statique où vous voulez !\nMontez d'un cran\nSi 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.\nEssayer 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.\nJ'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 !\nMais ceux-là vont jusqu'à 11.\n\n\n\n\nL'information présentée ici est valable pour les versions 0.6.0 d'Eleventy et 3.8.5 de Jekyll. ↩\n\n\n", "content_html": "\n

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.

\n

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.

\n

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.

\n

Présentation d'Eleventy

\n

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).

\n

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 parcours1.

\n\n

Avant de commencer

\n

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 :

\n
    \n
  1. Installer Node.js :
    2. \n
\n\n
    \n
  1. 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.
    2. \n
\n

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.

\n

Installer Eleventy

\n

Maintenant que Node.js est installé et que votre projet est prêt à utiliser npm, nous pouvons installer Eleventy en tant que dépendance :

\n
npm install --save-dev @11ty/eleventy
\n

Si vous ouvrez votre package.json vous devriez y voir figurer les lignes suivantes :

\n
…\n\"devDependencies\": {\n  \"@11ty/eleventy\": \"^0.6.0\"\n}\n…
\n

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 :

\n
npx eleventy --input=README.md --formats=md
\n

Cette commande va générer un fichier HTML dans _site/README/index.html.
\nEleventy utilise par défaut le même répertoire de destination que Jekyll (_site), comme nous le verrons à de nombreuses reprises pendant cette transition.

\n

La configuration

\n

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.

\n

Commençons par créer notre fichier de configuration (.eleventy.js), et reportons les paramètres pertinents du _config.yml dans leurs options équivalentes :

\n
module.exports = function(eleventyConfig) {\n  return {\n    dir: {\n      input: \"./\",      // Équivalent au paramètre source de Jekyll\n      output: \"./_site\" // Équivalent au paramètre destination de Jekyll\n    }\n  };\n};
\n

Quelques choses bonnes à savoir :

\n\n

Les gabarits de mise en forme

\n

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).

\n

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 :

\n
module.exports = function(eleventyConfig) {\n    // les alias sont relatifs au répertoire _includes\n    eleventyConfig.addLayoutAlias('about', 'layouts/about.html');\n    eleventyConfig.addLayoutAlias('book', 'layouts/book.html');\n    eleventyConfig.addLayoutAlias('default', 'layouts/default.html');\n\n    return {\n      dir: {\n        input: \"./\",\n        output: \"./_site\"\n      }\n    };\n  }
\n

Déterminer le langage à utiliser pour les gabarits

\n

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.

\n

Les variables

\n

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.

\n

Les variables de site

\n

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 :

\n
title: \"Markdown Guide\"\nurl: https://www.markdownguide.org\nbaseurl: \"\"\nrepo: http://github.com/mattcone/markdown-guide\ncomments: false\nauthor:\n  name: \"Matt Cone\"\nog_locale: \"en_US\"
\n

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.

\n
{\n    \"title\": \"Markdown Guide\",\n    \"url\": \"https://www.markdownguide.org\",\n    \"baseurl\": \"\",\n    \"repo\": \"http://github.com/mattcone/markdown-guide\",\n    \"comments\": false,\n    \"author\": {\n      \"name\": \"Matt Cone\"\n    },\n    \"og_locale\": \"en_US\"\n  }
\n

Les variables de page

\n

Le tableau ci-dessous établit la correspondance entre les variables de page.\nRetenez 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.* :

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
JekyllEleventy
page.urlpage.url
page.datepage.date
page.pathpage.inputPath
page.idpage.outputPath
page.namepage.fileSlug
page.contentcontent
page.titletitle
page.foobarfoobar
\n

Lorsque d'une itération sur des pages, les valeurs front matter sont accessibles via l'objet data et le contenu via templateContent :

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
JekyllEleventy
item.urlitem.url
item.dateitem.date
item.pathitem.inputPath
item.iditem.outputPath
item.nameitem.fileSlug
item.contentitem.templateContent
item.titleitem.data.title
item.foobaritem.data.foobar
\n

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.

\n

Les variables de pagination

\n

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 :

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
JekyllEleventy
pagination.pagepagination.pageNumber
pagination.per_pagepagination.size
pagination.postspagination.items
pagination.previous_page_pathpagination.previousPageHref
pagination.previous_page_pathpagination.nextPageHref
\n

Les filtres

\n

Jekyll propose quelques filtres supplémentaires, en plus de ceux fournis par défaut par Liquid.\nIl 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.

\n

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 :

\n
// {{ variable | jsonify }}\n  eleventyConfig.addFilter('jsonify', function (variable) {\n    return JSON.stringify(variable);\n  });
\n

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 :

\n
{{ site.members | where: \"graduation_year\",\"2014\" }}
\n

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 :

\n
// {{ array | where: key,value }}\n  eleventyConfig.addFilter('where', function (array, key, value) {\n    return array.filter(item => {\n      const keys = key.split('.');\n      const reducedKey = keys.reduce((object, key) => {\n        return object[key];\n      }, item);\n\n      return (reducedKey === value ? item : false);\n    });\n  });
\n

Il se passe pas mal de trucs dans ce filtre, que je vais tenter d'expliquer.
\nNous 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 !

\n

Les includes

\n

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.
\nDans le cas contraire, alors qu'avec Jekyll vous écrivez :

\n
<!-- page.html -->\n{% include include.html value=\"key\" %}\n\n<!-- include.html -->\n{{ include.value }}
\n

dans Eleventy, vous allez écrire :

\n
<!-- page.html -->\n{% include \"include.html\", value: \"key\" %}\n\n<!-- include.html -->\n{{ value }}
\n

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.

\n

Paramétrer Liquid

\n

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\\.

\n

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.

\n

Heureusement pour nous, Eleventy nous laisse passer des options à LiquidJS :

\n
eleventyConfig.setLiquidOptions({\n    dynamicPartials: false,\n    root: [\n      '_includes',\n      '.'\n    ]\n  });
\n

Les collections

\n

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.

\n

Les collections dans Jekyll

\n

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 :

\n
collections:\n    - basic-syntax\n    - extended-syntax
\n

Elles correspondent aux dossiers _basic-syntax et _extended-syntax, nous pouvons itérer sur leurs contenus de la sorte :

\n
{% for syntax in site.extended-syntax %}\n  {{ syntax.title }}\n{% endfor %}
\n

Les collections dans Eleventy

\n

Il existe deux manières de configurer des collections dans Eleventy.\nTout d'abord, en utilisant simplement la propriété tag dans le front matter des fichiers de contenu :

\n
---\ntitle: Barré\nsyntax-id: barre\nsyntax-summary: \"~~La terre est plate~~\"\ntag: extended-syntax\n---
\n

Nous pouvons ensuite itérer sur les contenus étiquetés de la sorte :

\n
{% for syntax in collections.extended-syntax %}\n  {{ syntax.data.title }}\n{% endfor %}
\n

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) :

\n
eleventyConfig.addCollection('basic-syntax', collection => {\n  return collection.getFilteredByGlob('_basic-syntax/*.md');\n});\n\neleventyConfig.addCollection('extended-syntax', collection => {\n  return collection.getFilteredByGlob('_extended-syntax/*.md');\n});
\n

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 :

\n
eleventyConfig.addCollection('example', collection => {\n  return collection.getFilteredByGlob('_examples/*.md').sort((a, b) => {\n    return a.data.display_order - b.data.display_order;\n  });\n});
\n

Avec un peu de chance, cet exemple vous a fait comprendre ce qu'il est possible de faire avec cette approche.

\n

Utiliser les données de répertoire pour définir les paramètres par défaut

\n

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\n/_basic-syntax/lists.md sera généré sous /_basic-syntax/lists/index.html.\nComme 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 :

\n
---\ntitle: Lists\nsyntax-id: lists\napi: \"no\"\npermalink: /basic-syntax/lists.html\n---
\n

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.

\n

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é :

\n
{\n  \"layout\": \"syntax\",\n  \"tag\": \"basic-syntax\",\n  \"permalink\": \"basic-syntax/{{ title | slug }}.html\"\n}
\n

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 :

\n
markdown-guide\n└── _content\n    ├── basic-syntax\n    ├── extended-syntax\n    ├── getting-started\n    └── _content.json
\n

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 :

\n
{\n  \"permalink\": false\n}
\n

Les fichiers statiques

\n

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.\nPuis nous activons cette fonctionnalité dans ce qui est retourné, en mettant passthroughFileCopy à true :

\n
module.exports = function(eleventyConfig) {\n  …\n\n  // Copy the `assets` directory to the compiled site folder\n  eleventyConfig.addPassthroughCopy('assets');\n\n  return {\n    dir: {\n      input: \"./\",\n      output: \"./_site\"\n    },\n    passthroughFileCopy: true\n  };\n}
\n

Considérations finales

\n

Gestion des assets

\n

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.

\n

Publication sur GitHub Pages

\n

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 !

\n

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.\nRappelez-vous cependant que vous pouvez publier un site statique où vous voulez !

\n

Montez d'un cran

\n

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.

\n

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.

\n

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 !

\n

Mais ceux-là vont jusqu'à 11.

\n
\n
\n
    \n
  1. \n

    L'information présentée ici est valable pour les versions 0.6.0 d'Eleventy et 3.8.5 de Jekyll. ↩

    \n
    2. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/12/07/oubliez-docker-le-futur-c-est-la-jamstack/", "url": "https://jamstatic.fr/2018/12/07/oubliez-docker-le-futur-c-est-la-jamstack/", "title": "Oubliez Docker, le futur c'est la Jamstack", "summary": "À 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.", "date_published": "2018-12-07T00:21:13+00:00", "date_modified": "2018-01-26T00:09:11+00:00","content_text": "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.\nÀ l'heure où les entreprises se débattent pour devenir plus agiles et rester\npertinentes, elles peuvent compter sur les dernières évolutions des\ntechnologies. Oubliez Docker, Jamstack marque la prochaine évolution du\ndéveloppement web moderne.\nJamstack c'est pour JavaScript, APis et Markup. C'est la merveilleuse union de\ntechnologies modernes, du logiciel as a service et des langages au coeur des\nfondations du web. Cette stack procure :\n\nune réduction des coûts,\nune mise sur le marché plus rapide,\nune sécurité accrue,\nplus de fiabilité, de disponibilité, et une meilleure adaptation à la montée en charge,\nune réduction de la dépendance à des technologies propriétaires.\n\nLes technologies comme Docker vont continuer à jouer un rôle primordial dans le\nfutur du numérique, mais elles devraient devenir de plus en plus transparentes\npour la majorité des entreprises et seront utilisées sans que vous le sachiez.\nLe fait de devoir gérer et maintenir soi-même sa propre infrastructure\nappartiendra bientôt au passé.\nSi votre coeur de métier n'est pas de fournir des services dans le Cloud, cet\narticle vous explique pourquoi la Jamstack devrait devenir votre première\npréoccupation si vous tenez à fournir un avantage stratégique et une agilité\naccrue à la majorité de vos activités en ligne.\nLa Jamstack ?\nLa Jamstack c'est en partie du JavaScript et du code généré qui peuvent être\nhébergés en statique n'importe où. Elle est parfaitement complémentaire avec les\ntechnologies serverless et peut faire appel à des fonctions serverless exécutées\ndans le Cloud. Les serveurs d'applications traditionnelles sont en passe d'être\ntotalement superflus, en leur lieu et place une bonne partie de la complexité\nest résolue lors de l'étape de génération à l'aide de l'outillage fourni par\nentre autres par JavaScript.\nDes générateurs de site statiques comme Next.js ou Gatsby sont souvent utilisés\npour combler le besoin de faire du rendu côté serveur. Ces outils s'intègrent\nparfaitement avec des services du Cloud pendant l'étape de génération et\nproduisent en sortie une application complète composée de pages pré-rendues. Par\nexemple, ces outils peuvent récupérer des contenus stockés dans un CMS headless\net générer l'ensemble de votre site sous forme de pages statiques en quelques\nsecondes. Un instantané immuable de toutes ces pages peut alors être déployé en\nproduction et distribué partout dans le monde.\nIl est possible de déclencher des modifications à partir de n'importe quel\nservice en aval grâce à des webhooks et de générer une nouvelle version en\nquelques secondes après avoir récupéré le contenu mis à jour.\nBien que les applications Jamstack soient hébergées de manière statique, cela ne\nveut pas dire qu'elles n'en sont pas moins dynamiques ou interactives que des\npages dont le rendu est effectué côté serveur. Ces applications peuvent être\nconçues pour interagir avec des APIs web côté client et peuvent fournir du\ncontenu dynamique et de l'interactivité comme n'importe quelle application\nclassique. On peut toujours authentifier des utilisateurs et enrichir les pages\nprogressivement en fonctionnalités.\nDes fonctions exécutées depuis le Cloud peuvent fournir des capacités de\nservices additionnelles au besoin, et peuvent être elles aussi être écrites en\nJavaScript.\n\n\n\n\n\n\nExemple d'architecture Jamstack.\n\nPourquoi la Jamstack ?\nUn application Jamstack réduit les dépendances nécessaires lors de l'exécution\npour des performances, une fiabilité, une capacité de montée en charge et une\nsécurité maximales. En effet comme elles n'ont pas besoin de serveurs\nd'application dédiés pour servir les pages, cela réduit considérablement la\nsurface d'attaque possible. Le contenu statique est extrêmement facile à mettre\nen cache et à distribuer via un fournisseur d'accès au Cloud. Vous ne dépendez\npas d'un fournisseur en particulier.\nLes entreprises peuvent développer des solutions à l'aide de la Jamstack pour se\nlancer plus rapidement sur le marché et ce à moindre coût. C'est dû au fait\nqu'il y a besoin de beaucoup moins de ressources pour gérer et maintenir\nl'application en production et en développement. Une petite équipe agile\nmulti-disciplinaire aura seulement besoin d'être en capacité de livrer du HTML,\ndu CSS et du JavaScript. Pas besoin d'avoir beaucoup d'autres compétences quand\nil s'agit de publier pour le web.\nDans les applications traditionnelles, les mises à jour de dépendances se font\ngénéralement sur le serveur. Cela augment le risque d'interruption. Avec la\nJamstack comme tout se fait en aval, il y a beaucoup moins de chances que\nquelque chose puisse impacter les utilisateurs finaux — et encore moins si les\ngénérations sont testées automatiquement avant la mise en production.\nLa JAMStack sur repose sur les services dans le Cloud pour l'extension de\nfonctionnalités. Elle suit la tendance du développement JavaScript full-stack\nfacilité par des outils comme React et les offres de \"functions as a service\" du\nCloud. Fini les serveurs d'applications et les systèmes monolithiques avec des\nbases de données SQL. Plus besoin d'une infrastructure disponible en permanence\npour effectuer du rendu côté serveur à l'aide de langages compilés comme Java ou\n.NET.\nUne architecture Jamstack n'est jamais aussi performante que lorsqu'elle utilise\nles services d'un hébergeur spécialisé comme Netlify. Netlify est une\nplate-forme complète de Cloud pour les architectures Jamstack, qui se connecte\ndirectement à votre dépôt de code. Chaque sauvegarde permet d'à la fois\nversionner et déployer votre application et ses fonctions de support dans le\nCloud sur votre environnement de production en quelques secondes.\nNetlify déploie vos applications sur son réseau global de CDN pour une\nperformance optimale et propose également d'autres fonctionnalités à forte\nvaleur ajoutée, que vous auriez dû autrement développé ou configurer vous-mêmes.\nVerrou logiciel\nBeaucoup d'entreprises utilisent des logiciels tiers qu'elles hébergent\nelles-mêmes, ces logiciels demandent d'avoir des équipes importantes chargées de\nleur développement, de leur déploiement et de leur maintenance, avant même que\nvous n'ayez songé à développeur votre application. Parfois les deux sont\nindissociables et cela augmente considérablement les compétences minimales\nrequises dont vous auriez normalement besoin pour développer votre application.\nLes systèmes de gestion de contenu (CMS) en sont un parfait exemple. Quand ces\nfonctionnalités ne sont pas au coeur de votre activité, aujourd'hui cela n'a\nplus aucun sens d'investir du temps et des ressource spécialisées pour leur\nmaintenance, leur disponibilité et leur support. Ce fut pendant longtemps la\nseule option disponible et un sacrifice à consentir pour essayer de tirer parti\nde la valeur ajoutée que ces outils pouvaient vous procurer en retour.\nDepuis les offres de services ont évolué et les solutions adaptatives du Cloud\nentièrement gérées et maintenues pour une fraction du prix ont changé la donne.\nPrismic et Contentful sont des exemples de solutions de CMS découplés qui\noffrent des APIs web hautement interopérables. Plus besoin des compétences d'un\nexpert maison, ces services s'intègrent facilement à une architecture Jamstack,\nquelle que soit la technologie choisie.\nSur le même principe, presque n'importe quelle fonctionnalité peut être lancée\nou générée par des services offerts par le Cloud. Cela inclut des serices\nd'intégration et de déploiement continus qui peuvent être déclenchés à la\ndemande. Dans la plupart des cas, il n'y a plus besoin d'héberger et de gérer\nvos propres serveurs qu'ils soient chez vous ou dans le Cloud.\nCommodités logicielles\nÉtant donnée que les offres Saas (Software as a service) transforment les\nproduits en services dans le Cloud, les entreprises doivent repenser leur\nstratégie pour rester agiles.\nIl est critique pour une entreprise de comprendre l'offre actuelle et de faire\nappels à ces services distants lorsque c'est possible de façon à réduire ses\ncoûts et éviter de fournir un effort inutile en reproduisant ces infrastructures\ndisponibles partout en interne à un coût plus important.\nLes 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.\nIci 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.\nAvec la Jamstack, on tire parti des services du Cloud comme suit :\n\nhébergement de fichiers statiques plutôt que des serveurs d'application,\nintégration et déploiement dans le Cloud plutôt que chez soi en fonction de ses capacités,\npartenaires Saas plutôt que des produits tiers hébergés en interne,\nfonctions déclenchées à la demande dans le Cloud plutôt que sur des serveurs qui tournent en permanence,\ndes développeurs JavaScript full-stack plutôt que des compétences et des langages variés.\n\nEn résumé\nLes technologies comme Docker sont au coeur des infrastructures modernes. Elles\nsimplifient le provisionnement de ressources de manière très consistante et très\nfiable.\nToutefois, à moins que vous soyez un expert qui fournit des services dans le\nCloud, se focaliser sur l'infrastructure ne fait plus sens.\nUne grande partie de la complexité de l'infrastructure de développement d'un\nproduit interne provient de dépendances lourdes comme celles à des systèmes de\ngestion de contenu. Pendant longtemps il a fallu héberger des logiciels tiers,\nles configurer pour qu'ils soient tout le temps disponibles, et posséder des\ncompétences variées pour développer et maintenir l'ensemble. Cela pousse les\nentreprises à s'engouffrer dans de faux problèmes en se focalisant sur\nl'infrastructure et le déploiement, plutôt que de se défaire de ces dépendances\nqui peuvent s'avérer douloureuses à gérer.\nLa Jamstack propose un modèle d'architecture efficace pour remplacer l'approche\ntraditionnelle du développement web et permet à une petit équipe agile d'adopter\nun bon rythme. Plus besoin de se préoccuper de l'infrastructure et des serveurs.\nElle encourage également l'intégration d'autres offres SaaS qui fournissent des\nAPIs interopérables et s'affranchit des systèmes\nLa Jamstack rend les mises à jour, le support et le redimensionnement de ses\napplications trivial. C'est l'assurance d'une agilité accrue et d'un lancement\nsur le marché plus rapide, avec de meilleures performances. Le monde de\nl'entreprise bouge lentement et ceux qui pourront s'adapter en tireront un\navantage compétitif.", "content_html": "\n

À l'heure où les entreprises se débattent pour devenir plus agiles et rester\npertinentes, elles peuvent compter sur les dernières évolutions des\ntechnologies. Oubliez Docker, Jamstack marque la prochaine évolution du\ndéveloppement web moderne.

\n

Jamstack c'est pour JavaScript, APis et Markup. C'est la merveilleuse union de\ntechnologies modernes, du logiciel as a service et des langages au coeur des\nfondations du web. Cette stack procure :

\n\n

Les technologies comme Docker vont continuer à jouer un rôle primordial dans le\nfutur du numérique, mais elles devraient devenir de plus en plus transparentes\npour la majorité des entreprises et seront utilisées sans que vous le sachiez.\nLe fait de devoir gérer et maintenir soi-même sa propre infrastructure\nappartiendra bientôt au passé.

\n

Si votre coeur de métier n'est pas de fournir des services dans le Cloud, cet\narticle vous explique pourquoi la Jamstack devrait devenir votre première\npréoccupation si vous tenez à fournir un avantage stratégique et une agilité\naccrue à la majorité de vos activités en ligne.

\n

La Jamstack ?

\n

La Jamstack c'est en partie du JavaScript et du code généré qui peuvent être\nhébergés en statique n'importe où. Elle est parfaitement complémentaire avec les\ntechnologies serverless et peut faire appel à des fonctions serverless exécutées\ndans le Cloud. Les serveurs d'applications traditionnelles sont en passe d'être\ntotalement superflus, en leur lieu et place une bonne partie de la complexité\nest résolue lors de l'étape de génération à l'aide de l'outillage fourni par\nentre autres par JavaScript.

\n

Des générateurs de site statiques comme Next.js ou Gatsby sont souvent utilisés\npour combler le besoin de faire du rendu côté serveur. Ces outils s'intègrent\nparfaitement avec des services du Cloud pendant l'étape de génération et\nproduisent en sortie une application complète composée de pages pré-rendues. Par\nexemple, ces outils peuvent récupérer des contenus stockés dans un CMS headless\net générer l'ensemble de votre site sous forme de pages statiques en quelques\nsecondes. Un instantané immuable de toutes ces pages peut alors être déployé en\nproduction et distribué partout dans le monde.

\n

Il est possible de déclencher des modifications à partir de n'importe quel\nservice en aval grâce à des webhooks et de générer une nouvelle version en\nquelques secondes après avoir récupéré le contenu mis à jour.

\n

Bien que les applications Jamstack soient hébergées de manière statique, cela ne\nveut pas dire qu'elles n'en sont pas moins dynamiques ou interactives que des\npages dont le rendu est effectué côté serveur. Ces applications peuvent être\nconçues pour interagir avec des APIs web côté client et peuvent fournir du\ncontenu dynamique et de l'interactivité comme n'importe quelle application\nclassique. On peut toujours authentifier des utilisateurs et enrichir les pages\nprogressivement en fonctionnalités.

\n

Des fonctions exécutées depuis le Cloud peuvent fournir des capacités de\nservices additionnelles au besoin, et peuvent être elles aussi être écrites en\nJavaScript.

\n
\n\n\n\n\"Exemple\n\n
Exemple d'architecture Jamstack.
\n
\n

Pourquoi la Jamstack ?

\n

Un application Jamstack réduit les dépendances nécessaires lors de l'exécution\npour des performances, une fiabilité, une capacité de montée en charge et une\nsécurité maximales. En effet comme elles n'ont pas besoin de serveurs\nd'application dédiés pour servir les pages, cela réduit considérablement la\nsurface d'attaque possible. Le contenu statique est extrêmement facile à mettre\nen cache et à distribuer via un fournisseur d'accès au Cloud. Vous ne dépendez\npas d'un fournisseur en particulier.

\n

Les entreprises peuvent développer des solutions à l'aide de la Jamstack pour se\nlancer plus rapidement sur le marché et ce à moindre coût. C'est dû au fait\nqu'il y a besoin de beaucoup moins de ressources pour gérer et maintenir\nl'application en production et en développement. Une petite équipe agile\nmulti-disciplinaire aura seulement besoin d'être en capacité de livrer du HTML,\ndu CSS et du JavaScript. Pas besoin d'avoir beaucoup d'autres compétences quand\nil s'agit de publier pour le web.

\n

Dans les applications traditionnelles, les mises à jour de dépendances se font\ngénéralement sur le serveur. Cela augment le risque d'interruption. Avec la\nJamstack comme tout se fait en aval, il y a beaucoup moins de chances que\nquelque chose puisse impacter les utilisateurs finaux — et encore moins si les\ngénérations sont testées automatiquement avant la mise en production.

\n

La JAMStack sur repose sur les services dans le Cloud pour l'extension de\nfonctionnalités. Elle suit la tendance du développement JavaScript full-stack\nfacilité par des outils comme React et les offres de \"functions as a service\" du\nCloud. Fini les serveurs d'applications et les systèmes monolithiques avec des\nbases de données SQL. Plus besoin d'une infrastructure disponible en permanence\npour effectuer du rendu côté serveur à l'aide de langages compilés comme Java ou\n.NET.

\n

Une architecture Jamstack n'est jamais aussi performante que lorsqu'elle utilise\nles services d'un hébergeur spécialisé comme Netlify. Netlify est une\nplate-forme complète de Cloud pour les architectures Jamstack, qui se connecte\ndirectement à votre dépôt de code. Chaque sauvegarde permet d'à la fois\nversionner et déployer votre application et ses fonctions de support dans le\nCloud sur votre environnement de production en quelques secondes.

\n

Netlify déploie vos applications sur son réseau global de CDN pour une\nperformance optimale et propose également d'autres fonctionnalités à forte\nvaleur ajoutée, que vous auriez dû autrement développé ou configurer vous-mêmes.

\n

Verrou logiciel

\n

Beaucoup d'entreprises utilisent des logiciels tiers qu'elles hébergent\nelles-mêmes, ces logiciels demandent d'avoir des équipes importantes chargées de\nleur développement, de leur déploiement et de leur maintenance, avant même que\nvous n'ayez songé à développeur votre application. Parfois les deux sont\nindissociables et cela augmente considérablement les compétences minimales\nrequises dont vous auriez normalement besoin pour développer votre application.

\n

Les systèmes de gestion de contenu (CMS) en sont un parfait exemple. Quand ces\nfonctionnalités ne sont pas au coeur de votre activité, aujourd'hui cela n'a\nplus aucun sens d'investir du temps et des ressource spécialisées pour leur\nmaintenance, leur disponibilité et leur support. Ce fut pendant longtemps la\nseule option disponible et un sacrifice à consentir pour essayer de tirer parti\nde la valeur ajoutée que ces outils pouvaient vous procurer en retour.

\n

Depuis les offres de services ont évolué et les solutions adaptatives du Cloud\nentièrement gérées et maintenues pour une fraction du prix ont changé la donne.\nPrismic et Contentful sont des exemples de solutions de CMS découplés qui\noffrent des APIs web hautement interopérables. Plus besoin des compétences d'un\nexpert maison, ces services s'intègrent facilement à une architecture Jamstack,\nquelle que soit la technologie choisie.

\n

Sur le même principe, presque n'importe quelle fonctionnalité peut être lancée\nou générée par des services offerts par le Cloud. Cela inclut des serices\nd'intégration et de déploiement continus qui peuvent être déclenchés à la\ndemande. Dans la plupart des cas, il n'y a plus besoin d'héberger et de gérer\nvos propres serveurs qu'ils soient chez vous ou dans le Cloud.

\n

Commodités logicielles

\n

Étant donnée que les offres Saas (Software as a service) transforment les\nproduits en services dans le Cloud, les entreprises doivent repenser leur\nstratégie pour rester agiles.

\n

Il est critique pour une entreprise de comprendre l'offre actuelle et de faire\nappels à ces services distants lorsque c'est possible de façon à réduire ses\ncoûts et éviter de fournir un effort inutile en reproduisant ces infrastructures\ndisponibles partout en interne à un coût plus important.

\n

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.

\n

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.

\n

Avec la Jamstack, on tire parti des services du Cloud comme suit :

\n\n

En résumé

\n

Les technologies comme Docker sont au coeur des infrastructures modernes. Elles\nsimplifient le provisionnement de ressources de manière très consistante et très\nfiable.

\n

Toutefois, à moins que vous soyez un expert qui fournit des services dans le\nCloud, se focaliser sur l'infrastructure ne fait plus sens.

\n

Une grande partie de la complexité de l'infrastructure de développement d'un\nproduit interne provient de dépendances lourdes comme celles à des systèmes de\ngestion de contenu. Pendant longtemps il a fallu héberger des logiciels tiers,\nles configurer pour qu'ils soient tout le temps disponibles, et posséder des\ncompétences variées pour développer et maintenir l'ensemble. Cela pousse les\nentreprises à s'engouffrer dans de faux problèmes en se focalisant sur\nl'infrastructure et le déploiement, plutôt que de se défaire de ces dépendances\nqui peuvent s'avérer douloureuses à gérer.

\n

La Jamstack propose un modèle d'architecture efficace pour remplacer l'approche\ntraditionnelle du développement web et permet à une petit équipe agile d'adopter\nun bon rythme. Plus besoin de se préoccuper de l'infrastructure et des serveurs.\nElle encourage également l'intégration d'autres offres SaaS qui fournissent des\nAPIs interopérables et s'affranchit des systèmes

\n

La Jamstack rend les mises à jour, le support et le redimensionnement de ses\napplications trivial. C'est l'assurance d'une agilité accrue et d'un lancement\nsur le marché plus rapide, avec de meilleures performances. Le monde de\nl'entreprise bouge lentement et ceux qui pourront s'adapter en tireront un\navantage compétitif.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/11/28/optimisation-compilation-jekyll/", "url": "https://jamstatic.fr/2018/11/28/optimisation-compilation-jekyll/", "title": "Optimisation du temps de compilation de Jekyll", "summary": "Comment diviser par quinze le temps de génération de son site.", "date_published": "2018-11-28T00:00:00+00:00","content_text": "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.\nTrois 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.\nPar 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.\nTL;DR\n\nConstatant que ma compilation Jekyll était des plus lentes, j'ai contacté la communauté Jamstack francophone pour des conseils.\nPlusieurs choses ont émergé, chaque conseil permettant d'optimiser le temps de compilation.\nLe plus gros gain provient des évolutions de Jekyll lui-même, sur lequel l'équipe est en train de faire un énorme travail.\n\n\nPour générer mon site (source), j'ai développé un ensemble de commandes Rake1 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.\nToutes 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.\nIl 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 Netlify2.\nIl était temps d'agir.\n\nUn proverbe africain dit :\n\nSeul, on va plus vite. Ensemble, on va plus loin.\n\nJe 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.\n\nQuand 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.\nInclusions : à consommer avec modération\nL'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.\nDans 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].\nD'après Pat Hawks, membre de la Core Team Jekyll :\n\nChaque 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.\nCela 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…\n\nUne 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 :\n\nassurez-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 ;\nsi 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.\n\nCes 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 compilation3 en sacrifiant ce petit confort.\nEt 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.\nFaites confiance aux gemmes compilées en C\nPar 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.\nIl en existe certainement d'autres, mais en voici au moins deux :\n\nla gemme liquid-c, pour optimiser la compilation Liquid ;\nla gemme sassc, si vous avez besoin de Jekyll pour compiler des fichiers Sass plus efficacement.\n\nJe n'ai pas besoin de Jekyll pour mes fichiers Sass mais en utilisant liquid-c, j'ai économisé 9 % du temps de compilation.\nSi vous pouvez l'éviter, n'utilisez pas LSI\nJekyll 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 lentement4.\nAprès une très rapide non-analyse des données analytiques dont je ne dispose pas5, j'ai décidé de me séparer de la proposition d'articles associés et d'économiser 17 % du temps de compilation.\nMarkdown : choisissez la bonne variante\nMarkdown 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.\nPar 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.\nAttention, 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.\nPar 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 --> :\nmarkdown: CommonMark\ncommonmark:\n options: [\"SMART\", \"FOOTNOTES\", \"UNSAFE\", \"HARDBREAKS\"]\n extensions: [\"strikethrough\", \"autolink\", \"table\"]\nVous 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.\nUn petit prix à payer pour gagner encore 9 % de temps de compilation.\nFaites confiance à la Team pour aller dans la bonne direction\nEnfin, 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 % !\nJe 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.\nSi 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.\nQu'en est-il de mon chantier multilingue ?\nAvec 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.\nElle 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.\nAshwin 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.\nJe ne manquerai pas d'en parler quand j'attaquerai à nouveau ce chantier.\n\nProtocole expérimental\nComme 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.\nVoici 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.\nVoici les données brutes, si certains veulent jouer avec :\n\n\n\nRun\nStep\nDone in… (s)\n\n\n\n\nTest 1\n1 - Before\n1337,872\n\n\nTest 1\n2 - Switch to liquid-c\n1509,997\n\n\nTest 1\n3 - Remove LSI\n1264,981\n\n\nTest 1\n4 - Switch to CommonMark\n1282,607\n\n\nTest 1\n5 - Switch to master\n64,949\n\n\nTest 2\n1 - Before\n1510,356\n\n\nTest 2\n2 - Switch to liquid-c\n1457,161\n\n\nTest 2\n3 - Remove LSI\n1239,278\n\n\nTest 2\n4 - Switch to CommonMark\n1058,934\n\n\nTest 2\n5 - Switch to master\n72,335\n\n\nTest 3\n1 - Before\n2148,253\n\n\nTest 3\n2 - Switch to liquid-c\n1465,446\n\n\nTest 3\n3 - Remove LSI\n1253,785\n\n\nTest 3\n4 - Switch to CommonMark\n886,152\n\n\nTest 3\n5 - Switch to master\n92,384\n\n\nTest 4\n1 - Before\n1621,322\n\n\nTest 4\n2 - Switch to liquid-c\n1506,737\n\n\nTest 4\n3 - Remove LSI\n1225,414\n\n\nTest 4\n4 - Switch to CommonMark\n1057,497\n\n\nTest 4\n5 - Switch to master\n87,943\n\n\nTest 5\n1 - Before\n1589,323\n\n\nTest 5\n2 - Switch to liquid-c\n1607,33\n\n\nTest 5\n3 - Remove LSI\n1261,815\n\n\nTest 5\n4 - Switch to CommonMark\n914,124\n\n\nTest 5\n5 - Switch to master\n77,526\n\n\nTest 6\n1 - Before\n1643,596\n\n\nTest 6\n2 - Switch to liquid-c\n1481,98\n\n\nTest 6\n3 - Remove LSI\n1237,843\n\n\nTest 6\n4 - Switch to CommonMark\n1336,47\n\n\nTest 6\n5 - Switch to master\n69,099\n\n\nTest 7\n1 - Before\n1456,432\n\n\nTest 7\n2 - Switch to liquid-c\n1487,558\n\n\nTest 7\n3 - Remove LSI\n1268,737\n\n\nTest 7\n4 - Switch to CommonMark\n1106,233\n\n\nTest 7\n5 - Switch to master\n69,562\n\n\nTest 8\n1 - Before\n2943,453\n\n\nTest 8\n2 - Switch to liquid-c\n1492,383\n\n\nTest 8\n3 - Remove LSI\n1229,34\n\n\nTest 8\n4 - Switch to CommonMark\n1321,156\n\n\nTest 8\n5 - Switch to master\n70,332\n\n\nTest 9\n1 - Before\n1587,532\n\n\nTest 9\n2 - Switch to liquid-c\n1586,698\n\n\nTest 9\n3 - Remove LSI\n1264,424\n\n\nTest 9\n4 - Switch to CommonMark\n950,634\n\n\nTest 9\n5 - Switch to master\n69,907\n\n\nTest 10\n1 - Before\n1643,22\n\n\nTest 10\n2 - Switch to liquid-c\n1581,063\n\n\nTest 10\n3 - Remove LSI\n1229,119\n\n\nTest 10\n4 - Switch to CommonMark\n1332,547\n\n\nTest 10\n5 - Switch to master\n69,022\n\n\n\n\n\n\n\nRake est un orchestrateur similaire à make, mais en Ruby (en savoir plus). ↩\n\n\n15 minutes, comme confirmé par Chris McCraw dans son article \"How Our Build Bots Build Sites\". ↩\n\n\nVous allez devoir me croire sur parole, parce que mon protocole d'expérimentation ne contenait pas de test avec et sans inclusions. Il s'agit donc d'une estimation personnelle. ↩\n\n\nIl semblerait que la gemme gsl permette d'améliorer cela, mais je ne l'ai pas testé. Vos retours m'intéressent. ↩\n\n\nParce que je n'ai pas besoin de ça pour connaître les personnes qui me lisent, car elles interagissent souvent avec moi dans les commentaires ou sur Twitter. ↩\n\n\n", "content_html": "\n

TL;DR

\n\n
\n

Pour générer mon site (source), j'ai développé un ensemble de commandes Rake1 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.

\n

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.

\n

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 Netlify2.

\n

Il était temps d'agir.

\n
\n

Un proverbe africain dit :

\n
\n

Seul, on va plus vite. Ensemble, on va plus loin.

\n
\n

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.

\n
\n

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.

\n

Inclusions : à consommer avec modération

\n

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.

\n

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].

\n

D'après Pat Hawks, membre de la Core Team Jekyll :

\n
\n

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.\nCela 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…

\n
\n

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 :

\n
    \n
  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. \n
  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.
    3. \n
\n

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 compilation3 en sacrifiant ce petit confort.

\n

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.

\n

Faites confiance aux gemmes compilées en C

\n

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.

\n

Il en existe certainement d'autres, mais en voici au moins deux :

\n\n

Je n'ai pas besoin de Jekyll pour mes fichiers Sass mais en utilisant liquid-c, j'ai économisé 9 % du temps de compilation.

\n

Si vous pouvez l'éviter, n'utilisez pas LSI

\n

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 lentement4.

\n

Après une très rapide non-analyse des données analytiques dont je ne dispose pas5, j'ai décidé de me séparer de la proposition d'articles associés et d'économiser 17 % du temps de compilation.

\n

Markdown : choisissez la bonne variante

\n

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.

\n

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.

\n

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.

\n

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 --> :

\n
markdown: CommonMark\ncommonmark:\n  options: [\"SMART\", \"FOOTNOTES\", \"UNSAFE\", \"HARDBREAKS\"]\n  extensions: [\"strikethrough\", \"autolink\", \"table\"]
\n

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.

\n

Un petit prix à payer pour gagner encore 9 % de temps de compilation.

\n

Faites confiance à la Team pour aller dans la bonne direction

\n

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 % !

\n

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.

\n

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.

\n

Qu'en est-il de mon chantier multilingue ?

\n

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.

\n

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.

\n

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.

\n

Je ne manquerai pas d'en parler quand j'attaquerai à nouveau ce chantier.

\n
\n

Protocole expérimental

\n

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.

\n

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.

\n

Voici les données brutes, si certains veulent jouer avec :

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
RunStepDone in… (s)
Test 11 - Before1337,872
Test 12 - Switch to liquid-c1509,997
Test 13 - Remove LSI1264,981
Test 14 - Switch to CommonMark1282,607
Test 15 - Switch to master64,949
Test 21 - Before1510,356
Test 22 - Switch to liquid-c1457,161
Test 23 - Remove LSI1239,278
Test 24 - Switch to CommonMark1058,934
Test 25 - Switch to master72,335
Test 31 - Before2148,253
Test 32 - Switch to liquid-c1465,446
Test 33 - Remove LSI1253,785
Test 34 - Switch to CommonMark886,152
Test 35 - Switch to master92,384
Test 41 - Before1621,322
Test 42 - Switch to liquid-c1506,737
Test 43 - Remove LSI1225,414
Test 44 - Switch to CommonMark1057,497
Test 45 - Switch to master87,943
Test 51 - Before1589,323
Test 52 - Switch to liquid-c1607,33
Test 53 - Remove LSI1261,815
Test 54 - Switch to CommonMark914,124
Test 55 - Switch to master77,526
Test 61 - Before1643,596
Test 62 - Switch to liquid-c1481,98
Test 63 - Remove LSI1237,843
Test 64 - Switch to CommonMark1336,47
Test 65 - Switch to master69,099
Test 71 - Before1456,432
Test 72 - Switch to liquid-c1487,558
Test 73 - Remove LSI1268,737
Test 74 - Switch to CommonMark1106,233
Test 75 - Switch to master69,562
Test 81 - Before2943,453
Test 82 - Switch to liquid-c1492,383
Test 83 - Remove LSI1229,34
Test 84 - Switch to CommonMark1321,156
Test 85 - Switch to master70,332
Test 91 - Before1587,532
Test 92 - Switch to liquid-c1586,698
Test 93 - Remove LSI1264,424
Test 94 - Switch to CommonMark950,634
Test 95 - Switch to master69,907
Test 101 - Before1643,22
Test 102 - Switch to liquid-c1581,063
Test 103 - Remove LSI1229,119
Test 104 - Switch to CommonMark1332,547
Test 105 - Switch to master69,022
\n
\n
\n
    \n
  1. \n

    Rake est un orchestrateur similaire à make, mais en Ruby (en savoir plus). ↩

    \n
    2. \n
  2. \n

    15 minutes, comme confirmé par Chris McCraw dans son article \"How Our Build Bots Build Sites\". ↩

    \n
    3. \n
  3. \n

    Vous allez devoir me croire sur parole, parce que mon protocole d'expérimentation ne contenait pas de test avec et sans inclusions. Il s'agit donc d'une estimation personnelle. ↩

    \n
    4. \n
  4. \n

    Il semblerait que la gemme gsl permette d'améliorer cela, mais je ne l'ai pas testé. Vos retours m'intéressent. ↩

    \n
    5. \n
  5. \n

    Parce que je n'ai pas besoin de ça pour connaître les personnes qui me lisent, car elles interagissent souvent avec moi dans les commentaires ou sur Twitter. ↩

    \n
    6. \n
\n
", "authors": [ { "name": "boris" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/09/07/microbloguer-avec-jekyll/", "url": "https://jamstatic.fr/2018/09/07/microbloguer-avec-jekyll/", "title": "Microbloguer avec Jekyll", "summary": "Un microblog est un blog qui publie des articles courts, le plus souvent sans titre. Rejoignez la communauté IndieWeb et configurez votre site pour pour publier vos notes pour ensuite les envoyer sur Twitter.", "date_published": "2018-09-07T14:26:04+00:00","content_text": "Garder la main sur ses contenus est devenu une préoccupation pour beaucoup, on a pu le voir récemment avec l'annonce de Medium qui a décidé d'arrêter le support des noms de domaine personnalisés. Versionner ses contenus dans un format texte est la raison première de l'existence des générateurs comme Jekyll.\nEt si pour être un peu plus indépendant des plate-formes des réseaux sociaux qui se nourrissent de nos données, on commençait par publier sur son site, quitte à republier automatiquement ensuite sur Medium ou Twitter ? Fiona Voss a tenté l'expérience et ça marche très bien ! 🎉\nUn microblog est un blog sur lequel figurent des articles courts, le plus souvent sans titre. Jusqu'à récemment je pensais que Twitter ou Tumblr étaient les seules plate-formes sur lesquelles les gens pouvaient microbloguer. Il s'avère que les membres enthousiastes de la vibrante communauté de l'IndieWeb microbloguent sur leurs sites web. À mon tour, j'ai décidé de faire de même et de configurer mon site pour pouvoir microbloguer.\nJe peux créer deux types de posts, des notes et des articles, ma page d'accueil quant à elle affiche indifféremment les deux types de contenu. Je peux aisément poster sur mon blog Jekyll depuis n'importe où avec mon téléphone, et mes notes sont automatiquement republiées sur Twitter.\nPourquoi procéder ainsi ? Microbloguer sur mon site me donne plus de liberté que l'utilisation de Twitter. Je n'ai pas à respecter la limite du nombre de caractères de Twitter, et je peux baliser mes posts comme j'en ai envie. J'ai la maîtrise sur le design de mon site, je peux choisir ou pas d'afficher des publicités.\nPuisque je poste aussi sur Twitter, je reste connecté aux personnes présentes sur cette plate-forme, mais si un jour je décide de quitter Twitter, je peux supprimer mon compte sans perdre mes notes ou me demander comme les exporter dans un format exploitable. De plus les gens peuvent me suivre sans avoir de compte Twitter, via mon flux RSS ou le site micro.blog.\nVoici comment j'ai configuré mon site pour faire ça:\nConfiguration de Jekyll\nJ'ai commencé par utiliser le thème Lanyon pour Jekyll, puis je suis passée à Minima le thème par défaut, parce que la navigation me plaisait davantage. Minima est un thème basé sur une gem, donc pour personnaliser l'apparence de mon site, j'ai dû recopier les fichiers de gabarits de page stockés dans la gem comme indiqué dans la documentation.\nVoici à quoi ressemble le fichier Markdown d'une note. Ça ressemble à un post Jekyll standard, sauf que la chaîne de caractères pour le titre est vide. Si je supprime cette ligne, Jekyll utiliserait le slug, ici \"343\", comme titre. Ce ne serait pas très joli.\n---\nlayout: post\ndate: \"2018-03-25T00:05:43.780Z\"\ntitle: \"\"\nslug: \"343\"\n---\n\nJe poste sur mon site Jekyll depuis mon téléphone à l'aide de l'application iOS Micro.blog. Maintenant je peux représenter le web indépendant à la RailsConf !\nJ'utilise les catégories afin de pouvoir différencier les articles des notes. Jekyll affecte automatiquement la catégorie en fonction du chemin du fichier, dans mon cas ce sera soit articles\/_posts soit notes\/_posts. On peut créer des pages pour les notes et les articles en se basant sur cet exemple de la documentation de Jekyll.\nMa page d'accueil se contente d'afficher tous les posts, elle se fiche des catégories. Pour éviter d'avoir des niveaux de titre vides et créer des sauts de ligne inutiles pour les notes qui n'ont pas de titre, dans mon gabarit je vérifie d'abord si le titre est vide. Pas super élégant, mais ça fait le job.\n{%- if post.title != \"\" -%}\n <h3>\n <a class=\"post-link\" href=\"{{ post.url | relative_url }}\">\n {{ post.title | escape }}\n <\/a>\n <\/h3>\n{%- endif -%}\nSi le post est un article, j'affiche un extrait (le premier paragraphe par défaut) avec un lien pour lire la suite. Si c'est une note, j'affiche l'intégralité de son contenu.\n{%- if post.categories contains 'articles' -%}\n {{ post.excerpt }}\n {% if post.content contains site.excerpt_separator %}\n <a href=\"{{ post.url | prepend: site.baseurl }}\">Read more<\/a>\n {% endif %}\n{% else %}\n {{ post.content }}\n{%- endif -%}\nLa ligne if post.content contains site.excerpt_separator s'assure que nous n'affichons le lien Lire la suite que s'il y a du contenu supplémentaire. En pratique ce n'est pas nécessaire puisque tous mes articles comportent plus d'un paragraphe; En théorie je pourrais écrire un long post sans titre ou un court post avec un titre et il serait quand même affiché que ce soit un article ou une note, puisque la logique d'affichage ne prend pas en compte la catégorie à laquelle il appartient.\nPOSSE avec Micro.blog\nPOSSE veut dire Publish (on your) Own Site, Syndicate Elsewhere (Publiez sur votre propre site et syndiquez ailleurs), le but est d'avoir le meilleur des deux mondes : garder la main sur vos contenus en publiant d'abord sur votre site, tout en gardant le contact avec les autres sur les réseaux sociaux. C'était la partie la plus facile à configurer pour moi, car je me suis reposée sur le service Micro.blog qui ressemble à Twitter mais en plus petit et en plus sympa.\nAvec Micro.blog vous pouvez créer un compte et syndiquer les posts du flux RSS de votre blog vers celui de votre instance Micro.blog. Les posts courts apparaîtront en entier, comme des tweets. Les posts plus longs afficheront l'extrait ou le titre ainsi qu'un lien vers l'article complet sur votre blog. Les autres utilisateurs de micro.blog peuvent vous suivre et répondre à vos posts dans l'application Micro.blog.Voilà à quoi ressemble mon flux.\nJ'aime beaucoup la communauté Micro.blog. On sent plus d'humanité et moins de promotion que sur Twitter. La plate-forme n'affiche aucune publicité et le flux est strictement chronologique. Comme la communauté est restreinte, c'est plus facile de suivre les gens, et je pense que plus de personnes voient mes notes que sur Twitter. Bien qu'il y ait moins de gens, j'ai plus de discussions sur Micro.blog.\nMicro.blog me permet aussi de rester en contact avec les gens qui sont sur Twitter, puisque mon flux est automatiquement publié là-bas. Ce service là me coûte deux dollars par mois.\nMicro.blog peut aussi héberger votre blog pour 5 dollars par mois. Cela peut être une bonne solution, si vous ne voulez pas avoir à configurer et à maintenir votre site, ou si vous avez déjà un blog mais que vous souhaitez garder votre microblog à part.\nPublication\nMicro.blog propose des applications pour macOS et iOS, qui peuvent poster sur votre blog s'il supporte Micropub. Micropub est la spécification d'une norme pour publier de manière standard sur un site qui peut fonctionner avec une variété d'applications clientes. Si vous bloguez sur un site dynamique, vous auriez à configurer un point d'accès pour recevoir les requêtes de type POST dans un format spécifique. Si vous utilisez WordPress, qui reste un choix populaire dans la communauté IndieWeb, il y a des plugins pour cela.\nComme j'utilise Jekyll, un générateur de site statique, je pensais que Micropub serait compliqué à configurer, mais heureusement il y a un super outil qui fait exactement ce qu'il faut : webpage-micropub-to-github.\nC'est une application qui crée un point d'accès Micropub pour les sites Jekyll hébergés sur GitHub Pages.\nJ'ai dû d'abord ajouter quelques lignes de code dans la balise <head> pour l'authentification :\n<link rel=\"authorization_endpoint\" href=\"https:\/\/indieauth.com\/auth\" \/>\n<link rel=\"token_endpoint\" href=\"https:\/\/tokens.indieauth.com\/token\" \/>\n<link href=\"https:\/\/twitter.com\/fionajvoss\" rel=\"me\" \/>\n<link href=\"https:\/\/github.com\/FionaVoss\" rel=\"me\" \/>\nLes deux premières lignes indiquent à Micropub quel service d'authentification\nutiliser, les deux ligne suivantes lient mes profils sociaux à mon site web de\nmanière à ce que je puisse m'authentifier avec IndieAuth.com.\nL'un ou l'autre des profils aurait suffit, je n'ai pas vraiment besoin des deux liens. J'ai aussi dû ajouter l'URL de mon site à mes biographies Twitter et GitHub.\nwebpage-micropub-to-github est auto-hébergé, donc j'ai du ensuite déployé ma propre instance de cette application. Tout ce que j'ai eu à faire a été de cliquer sur le bouton \"Deployer sur Heroku\" dans README et de configurer quelques variables d'environnement, dont mon pseudonyme GitHub, ma clef d'API et le nom de mon dépôt. J'ai forké le dépôt même si ce n'était pas nécessaire puisque je n'ai fait aucune modification de code dans l'application.\nPetite précision : pour configurer la variable optionnelle MICROPUB_LAYOUT_NAME j'ai du entré la valeur \"posts\", entre guillemets; sans quoi ça faisait planter l'application. Même chose pour MICROPUB_FILENAME_STYLE, que j'ai défini à \"notes\/_posts\/:year-:month-:day-:slug\" pour que mes posts aillent dans la catégorie Notes.\nUne fois déployée, j'ai dû lier l'application dans ma balise <head> pour indiquer à micropub où poster:\n<link\n rel=\"micropub\"\n href=\"https:\/\/jekyll-micropub-to-github.herokuapp.com\/micropub\/main\"\n\/>\nEnfin, j'ai dû ajouter l'URL de mon site web dans mes préférences Micro.blog et suivre le processus d'authentification d'IndieAuth, qui consiste en tout en pour tout à m'authentifier avec mon compte Twitter.\nQuand je poste, Micro.blog envoie une requête à webpage-micropub-to-github. Puis webpage-micropub-to-github formate correctement le post en Markdown pour Jekyll et ajoute le fichier à mon dépôt via l'API de GitHub. Et comme GitHub Pages régénère mon site à chaque nouveau commit sur la branche master, le post apparaît instantanément.\nPasser par Micropub me permet non seulement d'utiliser les applications pour Micro.blog pour poster, mais également tout un tas d'autres. J'ai testé également Quill. Puisque c'est une application web, c'est pratique pour poster depuis un ordinateur public sans avoir à installer quoi que ce soit. Pour poster depuis mon téléphone, je passe par Micro.blog.\nMême si la configuration demande un peu d'effort, poster depuis mon site est aussi simple et rapide que de passer par Twitter, c'est un élément clef qui montre que microbloguer avec Jekyll est tout à fait faisable.", "content_html": "\n

Un microblog est un blog sur lequel figurent des articles courts, le plus souvent sans titre. Jusqu'à récemment je pensais que Twitter ou Tumblr étaient les seules plate-formes sur lesquelles les gens pouvaient microbloguer. Il s'avère que les membres enthousiastes de la vibrante communauté de l'IndieWeb microbloguent sur leurs sites web. À mon tour, j'ai décidé de faire de même et de configurer mon site pour pouvoir microbloguer.

\n

Je peux créer deux types de posts, des notes et des articles, ma page d'accueil quant à elle affiche indifféremment les deux types de contenu. Je peux aisément poster sur mon blog Jekyll depuis n'importe où avec mon téléphone, et mes notes sont automatiquement republiées sur Twitter.

\n

Pourquoi procéder ainsi ? Microbloguer sur mon site me donne plus de liberté que l'utilisation de Twitter. Je n'ai pas à respecter la limite du nombre de caractères de Twitter, et je peux baliser mes posts comme j'en ai envie. J'ai la maîtrise sur le design de mon site, je peux choisir ou pas d'afficher des publicités.

\n

Puisque je poste aussi sur Twitter, je reste connecté aux personnes présentes sur cette plate-forme, mais si un jour je décide de quitter Twitter, je peux supprimer mon compte sans perdre mes notes ou me demander comme les exporter dans un format exploitable. De plus les gens peuvent me suivre sans avoir de compte Twitter, via mon flux RSS ou le site micro.blog.

\n

Voici comment j'ai configuré mon site pour faire ça:

\n

Configuration de Jekyll

\n

J'ai commencé par utiliser le thème Lanyon pour Jekyll, puis je suis passée à Minima le thème par défaut, parce que la navigation me plaisait davantage. Minima est un thème basé sur une gem, donc pour personnaliser l'apparence de mon site, j'ai dû recopier les fichiers de gabarits de page stockés dans la gem comme indiqué dans la documentation.

\n

Voici à quoi ressemble le fichier Markdown d'une note. Ça ressemble à un post Jekyll standard, sauf que la chaîne de caractères pour le titre est vide. Si je supprime cette ligne, Jekyll utiliserait le slug, ici \"343\", comme titre. Ce ne serait pas très joli.

\n
---\nlayout: post\ndate: \"2018-03-25T00:05:43.780Z\"\ntitle: \"\"\nslug: \"343\"\n---\n\nJe poste sur mon site Jekyll depuis mon téléphone à l'aide de l'application iOS Micro.blog. Maintenant je peux représenter le web indépendant à la RailsConf !
\n

J'utilise les catégories afin de pouvoir différencier les articles des notes. Jekyll affecte automatiquement la catégorie en fonction du chemin du fichier, dans mon cas ce sera soit articles/_posts soit notes/_posts. On peut créer des pages pour les notes et les articles en se basant sur cet exemple de la documentation de Jekyll.

\n

Ma page d'accueil se contente d'afficher tous les posts, elle se fiche des catégories. Pour éviter d'avoir des niveaux de titre vides et créer des sauts de ligne inutiles pour les notes qui n'ont pas de titre, dans mon gabarit je vérifie d'abord si le titre est vide. Pas super élégant, mais ça fait le job.

\n
{%- if post.title != \"\" -%}\n  <h3>\n    <a class=\"post-link\" href=\"{{ post.url | relative_url }}\">\n      {{ post.title | escape }}\n    </a>\n  </h3>\n{%- endif -%}
\n

Si le post est un article, j'affiche un extrait (le premier paragraphe par défaut) avec un lien pour lire la suite. Si c'est une note, j'affiche l'intégralité de son contenu.

\n
{%- if post.categories contains 'articles' -%}\n  {{ post.excerpt }}\n  {% if post.content contains site.excerpt_separator %}\n    <a href=\"{{ post.url | prepend: site.baseurl }}\">Read more</a>\n  {% endif %}\n{% else %}\n  {{ post.content }}\n{%- endif -%}
\n

La ligne if post.content contains site.excerpt_separator s'assure que nous n'affichons le lien Lire la suite que s'il y a du contenu supplémentaire. En pratique ce n'est pas nécessaire puisque tous mes articles comportent plus d'un paragraphe; En théorie je pourrais écrire un long post sans titre ou un court post avec un titre et il serait quand même affiché que ce soit un article ou une note, puisque la logique d'affichage ne prend pas en compte la catégorie à laquelle il appartient.

\n

POSSE avec Micro.blog

\n

POSSE veut dire Publish (on your) Own Site, Syndicate Elsewhere (Publiez sur votre propre site et syndiquez ailleurs), le but est d'avoir le meilleur des deux mondes : garder la main sur vos contenus en publiant d'abord sur votre site, tout en gardant le contact avec les autres sur les réseaux sociaux. C'était la partie la plus facile à configurer pour moi, car je me suis reposée sur le service Micro.blog qui ressemble à Twitter mais en plus petit et en plus sympa.

\n

Avec Micro.blog vous pouvez créer un compte et syndiquer les posts du flux RSS de votre blog vers celui de votre instance Micro.blog. Les posts courts apparaîtront en entier, comme des tweets. Les posts plus longs afficheront l'extrait ou le titre ainsi qu'un lien vers l'article complet sur votre blog. Les autres utilisateurs de micro.blog peuvent vous suivre et répondre à vos posts dans l'application Micro.blog.Voilà à quoi ressemble mon flux.

\n

J'aime beaucoup la communauté Micro.blog. On sent plus d'humanité et moins de promotion que sur Twitter. La plate-forme n'affiche aucune publicité et le flux est strictement chronologique. Comme la communauté est restreinte, c'est plus facile de suivre les gens, et je pense que plus de personnes voient mes notes que sur Twitter. Bien qu'il y ait moins de gens, j'ai plus de discussions sur Micro.blog.

\n

Micro.blog me permet aussi de rester en contact avec les gens qui sont sur Twitter, puisque mon flux est automatiquement publié là-bas. Ce service là me coûte deux dollars par mois.

\n

Micro.blog peut aussi héberger votre blog pour 5 dollars par mois. Cela peut être une bonne solution, si vous ne voulez pas avoir à configurer et à maintenir votre site, ou si vous avez déjà un blog mais que vous souhaitez garder votre microblog à part.

\n

Publication

\n

Micro.blog propose des applications pour macOS et iOS, qui peuvent poster sur votre blog s'il supporte Micropub. Micropub est la spécification d'une norme pour publier de manière standard sur un site qui peut fonctionner avec une variété d'applications clientes. Si vous bloguez sur un site dynamique, vous auriez à configurer un point d'accès pour recevoir les requêtes de type POST dans un format spécifique. Si vous utilisez WordPress, qui reste un choix populaire dans la communauté IndieWeb, il y a des plugins pour cela.

\n

Comme j'utilise Jekyll, un générateur de site statique, je pensais que Micropub serait compliqué à configurer, mais heureusement il y a un super outil qui fait exactement ce qu'il faut : webpage-micropub-to-github.\nC'est une application qui crée un point d'accès Micropub pour les sites Jekyll hébergés sur GitHub Pages.

\n

J'ai dû d'abord ajouter quelques lignes de code dans la balise <head> pour l'authentification :

\n
<link rel=\"authorization_endpoint\" href=\"https://indieauth.com/auth\" />\n<link rel=\"token_endpoint\" href=\"https://tokens.indieauth.com/token\" />\n<link href=\"https://twitter.com/fionajvoss\" rel=\"me\" />\n<link href=\"https://github.com/FionaVoss\" rel=\"me\" />
\n

Les deux premières lignes indiquent à Micropub quel service d'authentification\nutiliser, les deux ligne suivantes lient mes profils sociaux à mon site web de\nmanière à ce que je puisse m'authentifier avec IndieAuth.com.

\n

L'un ou l'autre des profils aurait suffit, je n'ai pas vraiment besoin des deux liens. J'ai aussi dû ajouter l'URL de mon site à mes biographies Twitter et GitHub.

\n

webpage-micropub-to-github est auto-hébergé, donc j'ai du ensuite déployé ma propre instance de cette application. Tout ce que j'ai eu à faire a été de cliquer sur le bouton \"Deployer sur Heroku\" dans README et de configurer quelques variables d'environnement, dont mon pseudonyme GitHub, ma clef d'API et le nom de mon dépôt. J'ai forké le dépôt même si ce n'était pas nécessaire puisque je n'ai fait aucune modification de code dans l'application.

\n

Petite précision : pour configurer la variable optionnelle MICROPUB_LAYOUT_NAME j'ai du entré la valeur \"posts\", entre guillemets; sans quoi ça faisait planter l'application. Même chose pour MICROPUB_FILENAME_STYLE, que j'ai défini à \"notes/_posts/:year-:month-:day-:slug\" pour que mes posts aillent dans la catégorie Notes.

\n

Une fois déployée, j'ai dû lier l'application dans ma balise <head> pour indiquer à micropub où poster:

\n
<link\n  rel=\"micropub\"\n  href=\"https://jekyll-micropub-to-github.herokuapp.com/micropub/main\"\n/>
\n

Enfin, j'ai dû ajouter l'URL de mon site web dans mes préférences Micro.blog et suivre le processus d'authentification d'IndieAuth, qui consiste en tout en pour tout à m'authentifier avec mon compte Twitter.

\n

Quand je poste, Micro.blog envoie une requête à webpage-micropub-to-github. Puis webpage-micropub-to-github formate correctement le post en Markdown pour Jekyll et ajoute le fichier à mon dépôt via l'API de GitHub. Et comme GitHub Pages régénère mon site à chaque nouveau commit sur la branche master, le post apparaît instantanément.

\n

Passer par Micropub me permet non seulement d'utiliser les applications pour Micro.blog pour poster, mais également tout un tas d'autres. J'ai testé également Quill. Puisque c'est une application web, c'est pratique pour poster depuis un ordinateur public sans avoir à installer quoi que ce soit. Pour poster depuis mon téléphone, je passe par Micro.blog.

\n

Même si la configuration demande un peu d'effort, poster depuis mon site est aussi simple et rapide que de passer par Twitter, c'est un élément clef qui montre que microbloguer avec Jekyll est tout à fait faisable.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/08/26/recherche-plate-forme-de-deploiement-continu-parfaite/", "url": "https://jamstatic.fr/2018/08/26/recherche-plate-forme-de-deploiement-continu-parfaite/", "title": "À la recherche de la plate-forme de déploiement continu parfaite", "summary": "Travis, Circle, Drone, GitLab, Jenkins : choisissez la solution d'intégration et de déploiement continu qui vous convient le mieux.", "date_published": "2018-08-26T16:26:33+00:00","content_text": "L'automatisation est une des composantes qui permet de bien travailler en versionnant son projet et en configurant une publication automatique. Cette bonne pratique issue du développement permet de s'assurer que tout le monde peut contribuer et que les changements seront bien publiés. DJ Walker a pris le temps de passer en revue différents services pour vous, c'est parti pour la visite guidée.\nNous vous avons déjà parlé des avantages du déploiement automatique, et plus particulièrement de ceux des sites statiques. L'intégration continue et le déploiement continu sont la stratégie qu'on retrouve le plus souvent quand il s'agit de gérer la publication logicielle. Il existe une multitude d'options pour la mise en place de pipelines CI\/CD, avec leurs forces et leurs faiblesses. Quelle est celle qui est faite pour vous ? Dans cet article, nous nous penchons sur cinq services différents avec lesquels vous pouvez développer, tester et déployer votre code.\nLa configuration est clé\nLors de l'évaluation de l'utilité d'un outil de CI\/CD, je veux d'abord connaître la réponse à deux questions :\nQuel niveau de contrôle ai-je sur l'environnement qui va générer une nouvelle version de mon application ? Pouvoir configurer l'environnement dans lequel vous allez lancer vos étapes de build est essentiel. J'ai tendance à préférer lancer les étapes de build dans un conteneur Docker avec une image définie par mes soins. Les conteneurs sont devenus le moyen idéal pour faire tourner du code dans un environnement reproductible et isolé.\nComment se configurent les étapes de build ?\nVous pourriez simplement lancer vos tâches à l'aide d'un gros script shell ou d'un outil robuste comme make. Ces scripts peuvent toutefois devenir rapidement complexes et difficiles à déboguer. Idéalement, l'enchaînement des tâches est configuré à l'aide d'un langage de configuration qui offre des abstractions plus commodes pour éviter d'avoir à écrire de multiples scripts réutilisables. Bien qu'une syntaxe de configuration intuitive et facile à comprendre soit utile, quel que soit l'outil utilisé vous devrez en apprendre les rudiments, attendez-vous donc à lire leur documentation pour comprendre comment les utiliser.\nPeu importe comment fonctionne la configuration, l'important est d'opter pour des outils qui vous permettent de stocker et versionner votre configuration de build dans votre dépôt. Stocker votre configuration présente plusieurs avantages. Lancer le build d'un commit précédent se fera avec la configuration correspondante à cette même période. Vous pouvez travailler votre configuration sur une branche à part, et tirer parti de la portabilité qui découle de l'utilisation de la gestion de version.\nCircleCI\n\n\n\n\n\nCircleCI est un service d'hébergement de CI\/CD qui se connecte à votre dépôt et exécute vos étapes de build à chaque nouveau commit. CircleCI peut exécuter vos tâches dans une image Docker, une machine virtuelle Linux, ou une VM MacOS pour vos projets iOS.\nLa configuration se fait à l'aide d'un fichier .circleci\/config.yml dans votre dépôt. Ce fichier indique l'image Docker à utiliser pour votre environnement de build, ainsi que les commandes à exécuter afin de générer, tester et déployer votre application.\nCircleCI est le service utilisé par Forestry pour lancer ses tests et déployer son code. Il s'intègre sans problème avec GitHub et Bitbucket.\nOn aime\nLe fait que ce soit à la fois hautement configurable et simple à intégrer avec les projets GitHub.\nOn est pas super fan\nOn ne peut pas connecter de projets GitLab à CircleCI pour le moment.\nLire comment déployer un site statique avec CircleCI.\nTravisCI\n\n\n\n\n\nTravisCI est une solution de CI\/CD hébergée qui s'intègre avec vos projets GitHub. Les builds TravisCI se configurent dans un fichier .travis.yml présent dans votre dépôt.\nLes scripts de build s'exécutent dans un environnement Ubuntu qui peut être configuré à l'aide de commandes shell pendant la phase d'installation de votre build. TravisCI fournit également des abstractions pour installer différents langages de programmation dans votre environnement de build.\nOn aime\nTravisCI promet d'être gratuit à vie pour les projets open source. TravisCI travaille de pair avec Github et peut lancer automatiquement les tests d'intégration lorsqu'une pull request est ouverte.\nOn est pas super fan\nAvec TravisCI, vos builds doivent tourner dans un environnement Ubuntu. Vous pouvez installer Docker dans cet environnement pour récupérer des images, mais c'est la solution la plus verbeuse de toutes. De plus, vous ne pouvez utiliser TravisCI que si vos projets sont hébergés sur GitHub.\nGuide de démarrage TravisCI\nDrone\nDrone est un serveur de CI\/CD écrit en Go. Pour le moment vous devez héberger Drone sur votre serveur, mais une option d'hébergement dédiée est dans les tuyaux. Drone possède un système de plugin qui permet ainsi d'ajouter de nouvelles fonctionnalités.\nConfigurer un build pour Drone se fait à l'aide d'un fichier .drone.yml. On notera que la syntaxe de configuration de Drone est dérivée de la configuration de docker-compose. Si vous connaissez déjà docker-compose, vous serez en terrain connu avec le langage de configuration de Drone.\nOn aime\nDrone propose des matrices de builds pour permettre de tester simplement votre code dans de multiples configurations, par exemple différentes versions de vos dépendances.\nOn est pas super fan\nDrone est un arrivant relativement récent, et sa documentation aurait besoin d'un peu d'amour.\nBien démarrer avec Drone CI\nGitLab CI\n\n\n\n\n\nSi vous utilisez GitLab pour héberger votre code, vous avez déjà accès aux outils d'intégration continue de GitLab. Tout ce que vous avez à faire est d'ajouter un pipeline de CI à votre projet avec un fichier .gitlab-ci.yml. J'aime le fait de ne pas à avoir à parcourir une interface graphique pour configurer l'intégration continue d'un projet — si vous avez plein de projets et que vous souhaitez gérer leur intégration continue par lots, cette option vous donne des possibilités d'automatisation.\nOn aime\nGitLab CI est compatible avec toutes les versions de GitLab : vous pouvez l'utiliser sur gitlab.com ou sur votre instance GitLab hébergée. Le composant d'intégration continue de GitLab est écrit en Go, il est donc facile à exécuter sur les systèmes d'exploitation majeurs, y compris Windows et MacOS. Vous pouvez même lancer vos tests d'intégration en local sur votre machine !.\nOn est pas super fan\nForcément pour utiliser GitLab CI, vous devez héberger votre code source avec GitLab, le fait de pouvoir héberger vous-même votre suite logicielle devrait vous rassurer si vous avez peur d'être trop dépendant d'un service tiers.\nGitLab CI : guide de démarrage rapide\nJenkins\n\nJenkins est un serveur d'intégration et de déploiement continu que vous installez et lancer sur votre propre serveur. Le projet Jenkins a débuté en 2004 et aujourd'hui c'est une solution adoptée par les entreprises qui souhaitent posséder leur propre infrastructure de CI.\nJenkins dispose d'une foule de plugins pour l'ajout de fonctionnalités à votre serveur de CI. Les builds sont configurés dans un fichier Jenkinsfile, à partir du moment où vous avez installé le plugin Pipeline recommandé. Comme CircleCI, vous pouvez configurer votre environnement de build à l'aide d'une image Docker, même s'il existe également beaucoup d'autres options.\nJenkins est écrit en Java et est compatible avec les principaux systèmes d'exploitation. Les builds peuvent tourner sous environnement Linux, BSD, MacOS ou Windows.\nOn aime\nJenkins est totalement libre d'utilisation et open source. Jenkins supporte les plugins et dispose d'une bibliothèque très fournie de par sa relative longévité dans le domaine de l'intégration continue.\nLe fait de pouvoir faire tourner ses builds sur n'importe quel système d'exploitation, y compris Windows ou Mac OS, car Jenkins est écrit en Java.\nOn est pas super fan\nPas grand-chose à redire à ce niveau : Jenkins peut faire à peu près tout ce que vous voulez ! Toutefois, il se peut que les petites équipes n'aient peut-être pas envie de devoir se coltiner la maintenance et l'hébergement de leur propre serveur d'intégration continue.\nJenkins : Guide de démarrage\nChoisir l'outil qui vous convient le mieux\nLa variété d'options pour la mise en place de l'intégration et du déploiement continu a rendu l'automatisation plus accessible que jamais aux développeurs. Les projets open source qui possèdent des prérequis assez simples peuvent tirer parti de l'offre gratuite de TravisCI. Les utilisateurs de GitLab devraient se pencher sur l'utilisation de GitLab CI. Drone est une bonne solution pour ceux qui recherchent une solution simple à héberger soi-même, surtout s'ils apprécient la syntaxe de docker-compose. CircleCI est un bon choix pour ceux qui veulent de la souplesse mais qui ne souhaitent pas héberger leur serveur. Jenkins demandera quelques heures et de l'huile de coude, mais c'est un logiciel capable de faire beaucoup de choses.", "content_html": "\n

Nous vous avons déjà parlé des avantages du déploiement automatique, et plus particulièrement de ceux des sites statiques. L'intégration continue et le déploiement continu sont la stratégie qu'on retrouve le plus souvent quand il s'agit de gérer la publication logicielle. Il existe une multitude d'options pour la mise en place de pipelines CI/CD, avec leurs forces et leurs faiblesses. Quelle est celle qui est faite pour vous ? Dans cet article, nous nous penchons sur cinq services différents avec lesquels vous pouvez développer, tester et déployer votre code.

\n

La configuration est clé

\n

Lors de l'évaluation de l'utilité d'un outil de CI/CD, je veux d'abord connaître la réponse à deux questions :

\n

Quel niveau de contrôle ai-je sur l'environnement qui va générer une nouvelle version de mon application ? Pouvoir configurer l'environnement dans lequel vous allez lancer vos étapes de build est essentiel. J'ai tendance à préférer lancer les étapes de build dans un conteneur Docker avec une image définie par mes soins. Les conteneurs sont devenus le moyen idéal pour faire tourner du code dans un environnement reproductible et isolé.

\n

Comment se configurent les étapes de build ?\nVous pourriez simplement lancer vos tâches à l'aide d'un gros script shell ou d'un outil robuste comme make. Ces scripts peuvent toutefois devenir rapidement complexes et difficiles à déboguer. Idéalement, l'enchaînement des tâches est configuré à l'aide d'un langage de configuration qui offre des abstractions plus commodes pour éviter d'avoir à écrire de multiples scripts réutilisables. Bien qu'une syntaxe de configuration intuitive et facile à comprendre soit utile, quel que soit l'outil utilisé vous devrez en apprendre les rudiments, attendez-vous donc à lire leur documentation pour comprendre comment les utiliser.

\n

Peu importe comment fonctionne la configuration, l'important est d'opter pour des outils qui vous permettent de stocker et versionner votre configuration de build dans votre dépôt. Stocker votre configuration présente plusieurs avantages. Lancer le build d'un commit précédent se fera avec la configuration correspondante à cette même période. Vous pouvez travailler votre configuration sur une branche à part, et tirer parti de la portabilité qui découle de l'utilisation de la gestion de version.

\n

CircleCI

\n\n\n\n\"\"\n\n

CircleCI est un service d'hébergement de CI/CD qui se connecte à votre dépôt et exécute vos étapes de build à chaque nouveau commit. CircleCI peut exécuter vos tâches dans une image Docker, une machine virtuelle Linux, ou une VM MacOS pour vos projets iOS.

\n

La configuration se fait à l'aide d'un fichier .circleci/config.yml dans votre dépôt. Ce fichier indique l'image Docker à utiliser pour votre environnement de build, ainsi que les commandes à exécuter afin de générer, tester et déployer votre application.

\n

CircleCI est le service utilisé par Forestry pour lancer ses tests et déployer son code. Il s'intègre sans problème avec GitHub et Bitbucket.

\n

On aime

\n

Le fait que ce soit à la fois hautement configurable et simple à intégrer avec les projets GitHub.

\n

On est pas super fan

\n

On ne peut pas connecter de projets GitLab à CircleCI pour le moment.

\n\n

TravisCI

\n\n\n\n\"\"\n\n

TravisCI est une solution de CI/CD hébergée qui s'intègre avec vos projets GitHub. Les builds TravisCI se configurent dans un fichier .travis.yml présent dans votre dépôt.

\n

Les scripts de build s'exécutent dans un environnement Ubuntu qui peut être configuré à l'aide de commandes shell pendant la phase d'installation de votre build. TravisCI fournit également des abstractions pour installer différents langages de programmation dans votre environnement de build.

\n

On aime

\n

TravisCI promet d'être gratuit à vie pour les projets open source. TravisCI travaille de pair avec Github et peut lancer automatiquement les tests d'intégration lorsqu'une pull request est ouverte.

\n

On est pas super fan

\n

Avec TravisCI, vos builds doivent tourner dans un environnement Ubuntu. Vous pouvez installer Docker dans cet environnement pour récupérer des images, mais c'est la solution la plus verbeuse de toutes. De plus, vous ne pouvez utiliser TravisCI que si vos projets sont hébergés sur GitHub.

\n\n

Drone

\n

Drone est un serveur de CI/CD écrit en Go. Pour le moment vous devez héberger Drone sur votre serveur, mais une option d'hébergement dédiée est dans les tuyaux. Drone possède un système de plugin qui permet ainsi d'ajouter de nouvelles fonctionnalités.

\n

Configurer un build pour Drone se fait à l'aide d'un fichier .drone.yml. On notera que la syntaxe de configuration de Drone est dérivée de la configuration de docker-compose. Si vous connaissez déjà docker-compose, vous serez en terrain connu avec le langage de configuration de Drone.

\n

On aime

\n

Drone propose des matrices de builds pour permettre de tester simplement votre code dans de multiples configurations, par exemple différentes versions de vos dépendances.

\n

On est pas super fan

\n

Drone est un arrivant relativement récent, et sa documentation aurait besoin d'un peu d'amour.

\n\n

GitLab CI

\n\n\n\n\"\"\n\n

Si vous utilisez GitLab pour héberger votre code, vous avez déjà accès aux outils d'intégration continue de GitLab. Tout ce que vous avez à faire est d'ajouter un pipeline de CI à votre projet avec un fichier .gitlab-ci.yml. J'aime le fait de ne pas à avoir à parcourir une interface graphique pour configurer l'intégration continue d'un projet — si vous avez plein de projets et que vous souhaitez gérer leur intégration continue par lots, cette option vous donne des possibilités d'automatisation.

\n

On aime

\n

GitLab CI est compatible avec toutes les versions de GitLab : vous pouvez l'utiliser sur gitlab.com ou sur votre instance GitLab hébergée. Le composant d'intégration continue de GitLab est écrit en Go, il est donc facile à exécuter sur les systèmes d'exploitation majeurs, y compris Windows et MacOS. Vous pouvez même lancer vos tests d'intégration en local sur votre machine !.

\n

On est pas super fan

\n

Forcément pour utiliser GitLab CI, vous devez héberger votre code source avec GitLab, le fait de pouvoir héberger vous-même votre suite logicielle devrait vous rassurer si vous avez peur d'être trop dépendant d'un service tiers.

\n\n

Jenkins

\n\"Jenkins\n

Jenkins est un serveur d'intégration et de déploiement continu que vous installez et lancer sur votre propre serveur. Le projet Jenkins a débuté en 2004 et aujourd'hui c'est une solution adoptée par les entreprises qui souhaitent posséder leur propre infrastructure de CI.

\n

Jenkins dispose d'une foule de plugins pour l'ajout de fonctionnalités à votre serveur de CI. Les builds sont configurés dans un fichier Jenkinsfile, à partir du moment où vous avez installé le plugin Pipeline recommandé. Comme CircleCI, vous pouvez configurer votre environnement de build à l'aide d'une image Docker, même s'il existe également beaucoup d'autres options.

\n

Jenkins est écrit en Java et est compatible avec les principaux systèmes d'exploitation. Les builds peuvent tourner sous environnement Linux, BSD, MacOS ou Windows.

\n

On aime

\n

Jenkins est totalement libre d'utilisation et open source. Jenkins supporte les plugins et dispose d'une bibliothèque très fournie de par sa relative longévité dans le domaine de l'intégration continue.

\n

Le fait de pouvoir faire tourner ses builds sur n'importe quel système d'exploitation, y compris Windows ou Mac OS, car Jenkins est écrit en Java.

\n

On est pas super fan

\n

Pas grand-chose à redire à ce niveau : Jenkins peut faire à peu près tout ce que vous voulez ! Toutefois, il se peut que les petites équipes n'aient peut-être pas envie de devoir se coltiner la maintenance et l'hébergement de leur propre serveur d'intégration continue.

\n\n

Choisir l'outil qui vous convient le mieux

\n

La variété d'options pour la mise en place de l'intégration et du déploiement continu a rendu l'automatisation plus accessible que jamais aux développeurs. Les projets open source qui possèdent des prérequis assez simples peuvent tirer parti de l'offre gratuite de TravisCI. Les utilisateurs de GitLab devraient se pencher sur l'utilisation de GitLab CI. Drone est une bonne solution pour ceux qui recherchent une solution simple à héberger soi-même, surtout s'ils apprécient la syntaxe de docker-compose. CircleCI est un bon choix pour ceux qui veulent de la souplesse mais qui ne souhaitent pas héberger leur serveur. Jenkins demandera quelques heures et de l'huile de coude, mais c'est un logiciel capable de faire beaucoup de choses.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/08/17/contenu-multilingue-avec-hugo/", "url": "https://jamstatic.fr/2018/08/17/contenu-multilingue-avec-hugo/", "title": "Contenu multilingue avec Hugo", "summary": "Comment gérer les traductions dans plusieurs langues avec Hugo.", "date_published": "2018-08-17T09:36:38+00:00","content_text": "Hugo gère parfaitement le multilingue par défaut et permet ainsi de facilement traduire les contenus et les chaînes de caractères pour la localisation. Tout est pensé pour que la gestion de langues supplémentaires soit aussi simple que possible pour les développeurs et les contributeurs, ils peuvent ainsi se focaliser sur l'essentiel.\nVoyons ensemble comment configurer un projet Hugo multilingue et traduire votre contenu.\nConfigurer les langues\nLa première chose à faire sur un projet multilingue est d'indiquer à Hugo les langues à prendre en compte. Dans notre exemple nous en aurons trois :\n\nAnglais 🇬🇧\nFrançais 🇫🇷\nEspagnol 🇪🇸\n\nNous ajoutons donc les paramètres suivants dans notre fichier de configuration :\n# config.yaml\nlanguages:\n en:\n languageName: English\n weight: 1\n fr:\n languageName: Français\n weight: 2\n es:\n languageName: Español\n weight: 3\nCes langues sont dorénavant accessibles via .Site.Languages, triées par le poids indiqué, la valeur la plus petite sera la plus importante.\nIl est possible de personnaliser des paramètres globaux déjà définis dans .Site.Params ou .Param. Aucun souci à se faire donc pour le paramètre à appeler.\n# config.yaml\nparams:\n description: Everything you need to know about the three languages.\n twitter_handle: 3Languages\n\nlanguages:\n en:\n languageName: English\n weight: 1\n fr:\n languageName: Français\n weight: 2\n description: Tous ce que vous avez toujours voulu savoir sur les trois langues.\n twitter_handle: 3Languages_france\n es:\n languageName: Español\n weight: 3\n description: Todo lo que necesitas saber sobre los tres idiomas.\n twitter_handle: 3Languages_espana\n\n<meta name=\"description\" content=\"{{ .Param \"description\" }}\">\n<meta name=\"twitter:site\" content=\"{{ .Param \"twitter_handle\" }}\">\nTraduire nos pages\nHugo propose deux manière de faire pour traduire vos contenus.\nLa première consiste à inclure le code de la langue dans le nom du fichier de votre contenu, par exemple : \/content\/about.fr.md.\nLa deuxième suppose de créer un fichier dans un dossier dédié à une langue, par exemple : \/content\/french\/about.md.\nNous allons voir en détail comment s'assurer de deux choses, quelle que soit la méthode utilisée :\n\nChaque page a une langue de définie.\nChaque page est reliée à ses traductions.\n\nGérer les traductions avec les noms de fichiers 📄\nVoici à quoi ressemble notre page about et ses traductions :\ncontent\n├── about.md\n├── about.es.md\n└── about.fr.md\nHugo assigne ici le français au fichier about.fr.md et la version espagnole au fichier about.es.md. C'est très intuitif.\nQuid du fichier about.md ? Comme aucune langue n'est précisée, il se verra assigné celle par défaut.\nSi vous n'avez pas défini la valeur de DefaultContentLanguage dans votre fichier de configuration, la langue par défaut est l'anglais.\nSi vous souhaitez modifier ce comportement et assigner le français par défaut aux fichiers sans nomenclature de code de langue, il vous faut ajouter cette ligne à votre fichier de configuration :\n# config.yaml\nDefaultContentLanguage: fr\nGérer les traductions par dossier 📁\nIl est également possible d'affecter un dossier à chaque langue pour y déposer vos contenus traduits. Pour ce faire, vous devez spécifier le paramètre contentDir dans la configuration des langues :\nlanguages:\n en:\n languageName: English\n weight: 1\n contentDir: content\/english\n fr:\n languageName: Français\n weight: 2\n contentDir: content\/french\n es:\n languageName: Español\n weight: 3\n contentDir: content\/spanish\nVous pouvez spécifier un chemin relatif à votre projet ou un chemin absolu. L'utilisation d'un chemin absolu signifie que vos dossiers de traduction ne se trouvent pas forcément dans votre projet, mais ailleurs sur votre ordinateur.\nEn reprenant l'exemple précédent, notre arborescence de contenus ressemble maintenant à quelque chose comme :\ncontent\n├── english\n│ └── about.md\n├── french\n│ └── about.md\n└── spanish\n └── about.md\nHugo peut désormais assigner une langue à chacune des pages en fonction du dossier dans lequel elles se trouvent.\nCréer des liens vers les traductions 🔗\nLa création de lien vers les traductions est fondamentale.\nEn règle générale, nous allons vouloir indiquer à nos visiteurs les traductions disponibles de la page en cours, que ce soit via un menu ou des métadonnées pour le SEO.\nNous avons vu qu'Hugo sait assigner une langue à une page, mais qu'en est-il de la possibilité de lier des traductions entre elles ?\nDans les deux cas, Hugo va se baser sur le nom de fichier et sa localisation par rapport au dossier content. En fonction du système utilisé, on peut utiliser les nomenclatures suivantes :\n\n\n\nPar nom de fichier\n\n\n\n\n\n\ncontent\/about.md\ncontent\/about.fr.md\n✅\n\n\ncontent\/about.fr.md\ncontent\/about.es.md\n✅\n\n\ncontent\/about\/index.md\ncontent\/about\/index.fr.md\n✅\n\n\ncontent\/about.md\ncontent\/a-propos.fr.md\n🚫\n\n\ncontent\/company\/about.md\ncontent\/about.fr.md\n🚫\n\n\n\n\n\n\nPar dossier\n\n\n\n\n\n\ncontent\/english\/about.md\ncontent\/french\/about.md\n✅\n\n\ncontent\/english\/about\/index.md\ncontent\/french\/about\/index.md\n✅\n\n\ncontent\/english\/about.md\ncontent\/french\/a-propos.md\n🚫\n\n\ncontent\/english\/company\/about.md\ncontent\/english\/about.md\n🚫\n\n\n\nNotez bien qu'on peut forcer la liaison si elle ne correspond pas à celle par défaut. Il suffit pour cela d'ajouter le paramètre translationKey dans le Front Matter aux pages qui partagent le même contenu.\n# Dans les trois pages : about.md, a-propos.fr.md, acerda.es.md\n---\ntranslationKey: about\n---\nGrâce à cette clé de traduction, en l'absence de nomenclature commune, Hugo se fera un plaisir de relier ces pages entre elles.\nAjouter des liens vers les traductions dans les modèles de page\nMaintenant que nos contenus dans différentes langues sont reliés entre eux, comment en tirer parti dans les gabarits de page ?\nHugo stocke les traductions liées dans deux variables de page :\n\n.Translations pour les autres traductions liées à un contenu,\n.AllTranslations pour toutes les traductions liées y compris celle en cours.\n\nLes traductions sont ici également triées en fonction du paramètre Weight défini dans le fichier configuration.\nPour indiquer aux moteurs de recherche qu'il existe des traductions de contenu, il nous suffit d'ajouter le code suivant dans la balise <head> :\n{{ if .IsTranslated }}\n {{ range .Translations }}\n <link rel=\"alternate\" hreflang=\"{{ .Language.Lang }}\" href=\"{{ .Permalink }}\" title=\"{{ .Language.LanguageName }}\">\n {{ end }}\n{{ end }}\nSi nous préférons lister toutes les langues, y compris celle de la page en cours il nous suffit de boucler plutôt sur .AllTranslations.\nOn peut utiliser la même logique pour ajouter un sélecteur de langue qui ne s'affiche que si une ou plusieurs traductions sont disponibles :\n{{ if .IsTranslated }}\n <nav class=\"LangNav\">\n {{ range .Translations }}\n <a href=\"{{ .Permalink }}\">{{ .Language.LanguageName }}<\/a>\n {{ end}}\n <\/nav>\n{{ end }}\nL'objet .Language est disponible pour toutes les pages. En plus des paramètres principaux de langues, il contient les valeurs personnalisées définir dans la configuration des langues comme la description et le pseudo twitter dans notre exemple.\nLes bundles de page\nHugo vous permet de partager des ressources entre traductions et vous laisse aussi la possibilité de traduire une ressource !\nRevenons à nos pages about et transformons les en bundles (un dossier qui permet de stocker un contenu et ses ressources associées : images, etc.). Afin que ce soit plus clair, nous opterons pour la gestion par dossiers :\ncontent\n├── english\n│ └── about\n│ ├── index.md\n│ └── header.jpg\n├── español\n│ └── about\n│ └── index.md\n└── french\n └── about\n └── index.md\ncontent\n├── english\n│ └── about\n│ ├── index.md\n│ └── header.jpg\n├── spanish\n│ └── about\n│ └── index.md\n└── french\n └── about\n └── index.md\nDans cette configuration, toutes les traductions utilisent la ressource de la langue anglaise header.jpg. Hugo nous évite des duplications inutiles en partageant les ressources avec toutes les traductions d'une même page. On peut donc utiliser cette image quelque que soit la langue utilisée à l'aide de la fonction .Resources, en écrivant par exemple ici .Resources.GetMatch \"header.jpg\". Vous n'êtes pas obligé de stocker la ressource dans le dossier de la langue par défaut, ça marchera aussi si la ressource se trouve dans un autre dossier de langue.\nC'est bien pratique.\nMais que se passe-t-il si nous devons localiser cette image pour notre audience espagnole ? Comment ajouter une image spécifique pour la page espagnole ?\nIl suffit de déposer notre image dans le dossier de la langue espagnole :\ncontent\n├── english\n│ └── about\n│ ├── index.md\n│ └── header.jpg\n├── spanish\n│ └── about\n│ ├── index.md\n│ └── header.jpg ✨\n└── french\n └── about\n └── index.md\nC'est tout, Hugo prendra en compte qu'une ressource dédiée pour la version espagnole de notre page about.\nEt pour la version française ? Quelle image va-t-elle utiliser ? Celle de la version espagnole ou celle de la version anglaise ?\nDans ce cas Hugo va se baser sur la langue qui a le plus de poids et retourner la version correspondante. Comme dans notre configuration des langues, l'anglais a un indice de poids de 1, la version française héritera de la version de la ressource en anglais.\nSachez qu'il est possible de renommer n'importe quel fichier pour lui affecter une langue. Si nous avions choisi ici de nous baser sur la méthode qui repose sur la nomenclature des fichiers, notre bundle pour la page about ressemblerait à ceci :\ncontent\n└── about\n ├── index.md\n ├── index.es.md\n ├── index.fr.md\n ├── header.jpg\n └── header.es.jpg\nComme la fonction .GetMatch teste la valeur .Title d'une ressource, qui correspond par défaut à son nom de fichier (langue incluse), faites bien attention si vous vous basez sur les nomenclatures de fichier de bien englober toutes les ressources quelle que soit leur langue, comme ceci : .Resources.GetMatch \"header*.jpg\"\nConfigurer nos URLs\nQu'en est-il des URLs de nos pages ? Nous pouvons redefinir le slug d'une URL depuis le front matter d'une page, mais qu'en est-il de l'URL de base de chacune de nos langues ?\nPar défaut, Hugo va stocker les pages de la langue par défaut à la racine du dossier de destination public et les autres langues dans leurs répertoires respectifs.\nDonc pour un site en anglais par défaut, les URLs de la page about et de ses traductions seront :\n\nabout\/index.html 🇬🇧\nfr\/about\/index.html 🇫🇷\nes\/about\/index.html 🇪🇸\n\nC'est pas mal, mais je doute que l'équipe chargée du référencement soit vraiment satisfaite. Pour nous assurer que les URLs des pages correspondent à leur titre, il nous faut encore mettre à jour le slug des pages traduites :\n# about.fr.md\ntitle: À Propos\nslug: a-propos\n# acerda.es.md\ntitle: Acerda\nslug: acerda\nCe qui a pour effet d'avoir des URLs traduites :\n\nfr\/a-propos\/index.html 🇫🇷 👌\nes\/acerda\/index.html 🇪🇸 👌\n\nNous pourrions décider de stocker les pages en anglais dans un répertoire dédié simplement en définissant le paramètre defaultContentLanguageInSubdir à true dans notre fichier config.yaml\nLocalisation des chaînes de caractères\nLa convention pour la traduction des chaînes de caractères avec Hugo ressemble un peu à celle des fichiers .po de gettext. Les chaînes de chaque langue sont enregistrées dans un fichier nommé en fonction du code de la langue utilisée et stockées dans un dossier i18n\/.\nCe dossier peut se trouver à la racine de votre projet ou d'un thème.\n\ni18n\/en.yaml ✅\nthemes\/academic\/i18n\/en.yaml ✅\n\nPour nos trois langues, ça ressemble à quelque chose comme :\n# i18n\/en.yaml 🇬🇧\n- id: hello\n translation: \"Hello\"\n- id: how_are_you\n translation: \"How are you doing?\"\n# i18n\/fr.yaml 🇫🇷\n- id: hello\n translation: \"Bonjour\"\n- id: how_are_you\n translation: \"Comment allez-vous ?\"\n# i18n\/es.yaml 🇪🇸\n- id: hello\n translation: \"Hola\"\n- id: how_are_you\n translation: \"¿Como estas?\"\nComme vous pouvez le voir dans l'exemple ci-dessus, tout ce dont nous avons besoin c'est d'une chaîne qui servira de clé unique et d'une chaîne de caractère pour la traduction.\nEnsuite dans nos modèles de page, la fonction i18n d'Hugo se charge du reste.\n\nElle va tester si la clé passée en argument existe et retourner la traduction correspondante si elle existe.\nSi la clé n'existe pas pour la langue courante dans le fichier, elle affichera la traduction de la langue par défaut.\nSi la clé n'existe pas pour la langue par défaut, elle retourne une chaîne vide.\n\n<header>\n {{ i18n \"hello\" }}\n <hr>\n {{ i18n \"how_are_you\" }}\n<\/header>\n<!-- \/es\/index.html 🇪🇸 -->\n<header>\n Hola\n <hr>\n ¿Como estas?\n<\/header>\n<!-- \/fr\/index.html 🇫🇷 -->\n<header>\n Bonjour\n <hr>\n Comment allez-vous ?\n<\/header>\nLa fonction i18n a comme alias T. Si taper i18n est trop fatiguant pour vos petits doigts, vous pouvez donc utiliser la syntaxe abrégée : {{ T \"how_are_you\" }}.\nMettre les chaînes au pluriel\nLes chaînes ne font pas toujours référence à une entité unique. Elles peuvent parfois qualifier une seule chose, parfois plus. Comment donc nous assurer qu'une phrase sera fidèlement traduite au singulier comme au pluriel ?\nHugo possède bien une fonction pluralize, mais elle ne gère que l'anglais.\nHeureusement pour nous, les chaînes de traduction d'Hugo nous permettent de gérer parfaitement les autres langues.\nAfin de mieux illustrer cette fonctionnalité, nous allons utiliser des exemples dans lesquels figurent… des rongeurs 🐭 ! N'ayez pas peur, ce sont simplement des pluriels intéressants dans les trois langues.\nComment ça marche ? Hé bien, il s'avère que la valeur de notre traduction peut également être une liste de pluriels.\n# i18n\/en.yaml 🇬🇧\n- id: mouse\n translation:\n one: Mouse\n other: Mice\nExcellent, notre chaîne a maintenant un singulier (one) et une autre version (other) qui sera donc notre pluriel.\nRenseignons donc nos autres fichiers :\n# i18n\/es.yaml 🇪🇸\n- id: mouse\n translation:\n one: Ratón\n other: Ratones\n# i18n\/fr.yaml 🇫🇷\n- id: mouse\n translation:\n other: Souris\nComme en français le mot souris est invariable au singulier et au pluriel, nous n'avons qu'à renseigner la version générique other.\nLa fonction i18n peut prendre un entier comme deuxième paramètre, afin de préciser à combien d'éléments fait référence notre chaîne et à pouvoir la mettre au pluriel si nécessaire.\n{{ range .Pages }}\n <h3>{{ $.Title }}<\/h3>\n {{ with .Params.mice }}\n {{ i18n \"this_story_has\" }} {{ . }} {{ i18n \"mouse\" . }}.\n {{ end }}\n <hr>\n{{ end }}\nImaginons que nous avons deux histoires, la première avec 24 souris et la seconde avec une seule, voici quel serait le HTML compilé :\n<h3>Cinderella<\/h3>\nThis story has 24 Mice.\n<hr>\n<h3>Fantasia<\/h3>\nThis story has 1 Mouse.\n<hr>\nInclure le nombre d'unités dans la traduction\nVous pouvez même ajouter le nombre exact à la traduction de votre chaîne à l'aide de .Count et fusionner l'ensemble dans une seule chaîne de caractère (notez l'utilisation des guillemets) :\n- id: story_mice\n translation:\n other: \"This story has {{ .Count }} Mice\"\n one: This story has only one Mouse\nDorénavant le nombre de souris sera retourné en sortie de la fonction i18n, nous pouvons mettre à jour notre code pour qu'il utilise plutôt cette chaîne unique :\n- {{ i18n \"this_story_has\" }} {{ . }} {{ i18n \"mouse\" . }}\n+ {{ i18n \"story_mice\" . }}\nLe HTML compilé correspondant sera :\n<h3>Cinderella<\/h3>\nThis story has 24 Mice.\n<hr>\n<h3>Fantasia<\/h3>\nThis story has only one Mouse.\n<hr>\nVous pensez peut-être déjà au cas où il n'y a pas de souris quand le total est 0 ?\nComme expliqué plus bas, cela ne sera pas possible 🙅‍♂️.\nInclusion du contexte dans la traduction\nVous pouvez également passer en second paramètre un contexte à la fonction i18n plutôt qu'un entier.\nLà encore cela peut nous éviter de découper nos phrases en plusieurs chaînes de traduction, quand nous avons besoin de plus que de .Count.\n# i18n\/en.yaml\n- id: intro\n translation: \"This is the story of {{ .Params.lead }}{{ with .Params.location }} which takes place in {{ . }}{{ end }}\"\n# i18n\/en.yaml\n- id: intro\n translation: \"Voici l'histoire de {{ .Params.lead }}{{ with .Params.location }} qui se déroule à {{ . }}{{ end }}\"\nC'est le même principe que le contexte d'un fichier partiel.\n<h3>{{ .Title }}<\/h3>\n<div class=\"intro\">{{ i18n \"intro\" . }}<\/div>\n<h3>The Great Mouse Detective<\/h3>\n<div class=\"intro\">This is the story of Basil which takes place in London<\/div>\nLorsque vous passez un contexte en paramètre d'i18n, vous devez garder certaines choses en tête :\n\ni18n ne pourra évaluer ce paramètre comme un nombre (puisque ce n'en est pas un), donc impossible de mettre cette chaîne au pluriel à l'aide de one et other.\nSi cette chaîne est appelée à différents endroits, assurez-vous de toujours lui passer le même contexte ou bien utilisez with comme nous l'avons fait ci-dessus, si vous ne voulez pas vous retrouver avec une erreur bien moche du type can't evaluate field.\n\nTraduction des chaînes avec le système de fichier d'Hugo\nRappelez-vous que nos fichiers i18n sont inclus dans le système de fichier global d'Hugo. En conséquence, tous les fichiers en.yaml présents dans l'arborescence de notre projet Hugo seront fusionnés.\nSi une des traductions du thème que nous utilisons ne nous plaît pas, nous n'avons qu'à créer un fichier i18n\/en.yaml à la racine de notre projet (ou de notre composant de thème prioritaire) pour y ajouter notre version de cette traduction et uniquement celle-ci.\n# i18n\/en.yaml\n- id: mouse\n translation:\n one: Rodent\n other: Rodents\nC'est tout ! Pour les autres langues, Hugo se basera sur les Souris et les Ratones 🐁 déclarés dans themes\/miceandmen\/i18n\/.\nUn dernier mot sur les singuliers et les pluriels\nL'anglais comme le français, l'espagnol et bien d'autres langues ne connaît que deux formes de pluralisation, c'est soit du singulier soit du pluriel.\nDonc dans Hugo assez logiquement, pour le traitement d'une chaîne en anglais, les seules possibilités de mettre au pluriel seront one ou other.\nLa version à utiliser est déterminée par ce test tout simple :\nsi l'entier passé en paramètre de i18n == 1 👉 one\nsinon 👉 other\nC'est tout pour la plupart des langues européennes !\nMaintenant, d'autres langues comme le Russe ont des pluriels spécifiques pour few et many, l'arabe a une forme pour zero et une pour two 1\nSi nous pouvons deviner sans mal le nombre correspondant au pluriel de zero ou two, connaître le nombre exact d'éléments correspondants à few ou many en Russe ressemble davantage à un casse-tête.\nHeureusement, nous pouvons nous reposer sur Hugo et go-i18n de Nick Snyder pour nous aider à assembler toutes les pièces du puzzle.\nVoici tous les pluriels supportés pour l'ensemble des langues :\nzero one two few many other\nMais, cela ne veut pas dire pour autant que vous pouvez les utiliser en anglais.\nSi la langue courante est l'anglais, que votre total de souris est nul, et que vous précisez que le pluriel pour zero est This story has no mouse, vous vous retrouverez quand même avec la valeur utilisée pour other : This story has 0 Mice.\nLa valeur zero n'est prise en compte que si la langue courante est l'arabe ou si cette langue supporte un pluriel pour zero.\nConclusion 🏁\nTraduire des chaînes de caractères dans Hugo consiste à écrire un ou plusieurs fichiers de données pour chacune des langues supportée par votre projet.\nNous avons vu qu'Hugo offre une solution de localisation très simple et très efficace, que ce soit pour aider les contributeurs à traduire des contenus, ou permettre aux développeurs de supporter plusieurs langues dans les modèles de page.\nSi vous avez été amenés à gérer des projets multilingues plus complexes que ceux présentés ici, si vous pensez pouvoir enrichir cet article ou que vous avez vérifié le nombre exact de souris présentes dans Cendrillon2, faite-le savoir en commentaire.\n\n\n\n\nhttp:\/\/www.unicode.org\/cldr\/charts\/33\/supplemental\/language_plural_rules.html ↩\n\n\nEvidemment, j'ai pris un nombre au pif ! ↩\n\n\n", "content_html": "

Hugo gère parfaitement le multilingue par défaut et permet ainsi de facilement traduire les contenus et les chaînes de caractères pour la localisation. Tout est pensé pour que la gestion de langues supplémentaires soit aussi simple que possible pour les développeurs et les contributeurs, ils peuvent ainsi se focaliser sur l'essentiel.

\n

Voyons ensemble comment configurer un projet Hugo multilingue et traduire votre contenu.

\n

Configurer les langues

\n

La première chose à faire sur un projet multilingue est d'indiquer à Hugo les langues à prendre en compte. Dans notre exemple nous en aurons trois :

\n
    \n
  1. Anglais 🇬🇧
    2. \n
  2. Français 🇫🇷
    3. \n
  3. Espagnol 🇪🇸
    4. \n
\n

Nous ajoutons donc les paramètres suivants dans notre fichier de configuration :

\n
# config.yaml\nlanguages:\n  en:\n    languageName: English\n    weight: 1\n  fr:\n    languageName: Français\n    weight: 2\n  es:\n    languageName: Español\n    weight: 3
\n

Ces langues sont dorénavant accessibles via .Site.Languages, triées par le poids indiqué, la valeur la plus petite sera la plus importante.

\n

Il est possible de personnaliser des paramètres globaux déjà définis dans .Site.Params ou .Param. Aucun souci à se faire donc pour le paramètre à appeler.

\n
# config.yaml\nparams:\n  description: Everything you need to know about the three languages.\n  twitter_handle: 3Languages\n\nlanguages:\n  en:\n    languageName: English\n    weight: 1\n  fr:\n    languageName: Français\n    weight: 2\n    description: Tous ce que vous avez toujours voulu savoir sur les trois langues.\n    twitter_handle: 3Languages_france\n  es:\n    languageName: Español\n    weight: 3\n    description: Todo lo que necesitas saber sobre los tres idiomas.\n    twitter_handle: 3Languages_espana\n
\n
<meta name=\"description\" content=\"{{ .Param \"description\" }}\">\n<meta name=\"twitter:site\" content=\"{{ .Param \"twitter_handle\" }}\">
\n

Traduire nos pages

\n

Hugo propose deux manière de faire pour traduire vos contenus.

\n

La première consiste à inclure le code de la langue dans le nom du fichier de votre contenu, par exemple : /content/about.fr.md.

\n

La deuxième suppose de créer un fichier dans un dossier dédié à une langue, par exemple : /content/french/about.md.

\n

Nous allons voir en détail comment s'assurer de deux choses, quelle que soit la méthode utilisée :

\n
    \n
  1. Chaque page a une langue de définie.
    2. \n
  2. Chaque page est reliée à ses traductions.
    3. \n
\n

Gérer les traductions avec les noms de fichiers 📄

\n

Voici à quoi ressemble notre page about et ses traductions :

\n
content\n├── about.md\n├── about.es.md\n└── about.fr.md
\n

Hugo assigne ici le français au fichier about.fr.md et la version espagnole au fichier about.es.md. C'est très intuitif.

\n

Quid du fichier about.md ? Comme aucune langue n'est précisée, il se verra assigné celle par défaut.

\n

Si vous n'avez pas défini la valeur de DefaultContentLanguage dans votre fichier de configuration, la langue par défaut est l'anglais.

\n

Si vous souhaitez modifier ce comportement et assigner le français par défaut aux fichiers sans nomenclature de code de langue, il vous faut ajouter cette ligne à votre fichier de configuration :

\n
# config.yaml\nDefaultContentLanguage: fr
\n

Gérer les traductions par dossier 📁

\n

Il est également possible d'affecter un dossier à chaque langue pour y déposer vos contenus traduits. Pour ce faire, vous devez spécifier le paramètre contentDir dans la configuration des langues :

\n
languages:\n  en:\n    languageName: English\n    weight: 1\n    contentDir: content/english\n  fr:\n    languageName: Français\n    weight: 2\n    contentDir: content/french\n  es:\n    languageName: Español\n    weight: 3\n    contentDir: content/spanish
\n

Vous pouvez spécifier un chemin relatif à votre projet ou un chemin absolu. L'utilisation d'un chemin absolu signifie que vos dossiers de traduction ne se trouvent pas forcément dans votre projet, mais ailleurs sur votre ordinateur.

\n

En reprenant l'exemple précédent, notre arborescence de contenus ressemble maintenant à quelque chose comme :

\n
content\n├── english\n│   └── about.md\n├── french\n│   └── about.md\n└── spanish\n    └── about.md
\n

Hugo peut désormais assigner une langue à chacune des pages en fonction du dossier dans lequel elles se trouvent.

\n

Créer des liens vers les traductions 🔗

\n

La création de lien vers les traductions est fondamentale.

\n

En règle générale, nous allons vouloir indiquer à nos visiteurs les traductions disponibles de la page en cours, que ce soit via un menu ou des métadonnées pour le SEO.

\n

Nous avons vu qu'Hugo sait assigner une langue à une page, mais qu'en est-il de la possibilité de lier des traductions entre elles ?

\n

Dans les deux cas, Hugo va se baser sur le nom de fichier et sa localisation par rapport au dossier content. En fonction du système utilisé, on peut utiliser les nomenclatures suivantes :

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Par nom de fichier
content/about.mdcontent/about.fr.md✅
content/about.fr.mdcontent/about.es.md✅
content/about/index.mdcontent/about/index.fr.md✅
content/about.mdcontent/a-propos.fr.md🚫
content/company/about.mdcontent/about.fr.md🚫
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Par dossier
content/english/about.mdcontent/french/about.md✅
content/english/about/index.mdcontent/french/about/index.md✅
content/english/about.mdcontent/french/a-propos.md🚫
content/english/company/about.mdcontent/english/about.md🚫
\n

Notez bien qu'on peut forcer la liaison si elle ne correspond pas à celle par défaut. Il suffit pour cela d'ajouter le paramètre translationKey dans le Front Matter aux pages qui partagent le même contenu.

\n
# Dans les trois pages : about.md, a-propos.fr.md, acerda.es.md\n---\ntranslationKey: about\n---
\n

Grâce à cette clé de traduction, en l'absence de nomenclature commune, Hugo se fera un plaisir de relier ces pages entre elles.

\n

Ajouter des liens vers les traductions dans les modèles de page

\n

Maintenant que nos contenus dans différentes langues sont reliés entre eux, comment en tirer parti dans les gabarits de page ?

\n

Hugo stocke les traductions liées dans deux variables de page :

\n\n

Les traductions sont ici également triées en fonction du paramètre Weight défini dans le fichier configuration.

\n

Pour indiquer aux moteurs de recherche qu'il existe des traductions de contenu, il nous suffit d'ajouter le code suivant dans la balise <head> :

\n
{{ if .IsTranslated }}\n  {{ range .Translations }}\n  <link rel=\"alternate\" hreflang=\"{{ .Language.Lang }}\" href=\"{{ .Permalink }}\" title=\"{{ .Language.LanguageName }}\">\n  {{ end }}\n{{ end }}
\n

Si nous préférons lister toutes les langues, y compris celle de la page en cours il nous suffit de boucler plutôt sur .AllTranslations.

\n

On peut utiliser la même logique pour ajouter un sélecteur de langue qui ne s'affiche que si une ou plusieurs traductions sont disponibles :

\n
{{ if .IsTranslated }}\n  <nav class=\"LangNav\">\n  {{ range .Translations }}\n    <a href=\"{{ .Permalink }}\">{{ .Language.LanguageName }}</a>\n  {{ end}}\n  </nav>\n{{ end }}
\n\n

Les bundles de page

\n

Hugo vous permet de partager des ressources entre traductions et vous laisse aussi la possibilité de traduire une ressource !

\n

Revenons à nos pages about et transformons les en bundles (un dossier qui permet de stocker un contenu et ses ressources associées : images, etc.). Afin que ce soit plus clair, nous opterons pour la gestion par dossiers :

\n
content\n├── english\n│   └── about\n│       ├── index.md\n│   └── header.jpg\n├── español\n│   └── about\n│       └── index.md\n└── french\n    └── about\n        └── index.md
\n
content\n├── english\n│   └── about\n│       ├── index.md\n│   └── header.jpg\n├── spanish\n│   └── about\n│       └── index.md\n└── french\n    └── about\n        └── index.md
\n

Dans cette configuration, toutes les traductions utilisent la ressource de la langue anglaise header.jpg. Hugo nous évite des duplications inutiles en partageant les ressources avec toutes les traductions d'une même page. On peut donc utiliser cette image quelque que soit la langue utilisée à l'aide de la fonction .Resources, en écrivant par exemple ici .Resources.GetMatch \"header.jpg\". Vous n'êtes pas obligé de stocker la ressource dans le dossier de la langue par défaut, ça marchera aussi si la ressource se trouve dans un autre dossier de langue.

\n

C'est bien pratique.\nMais que se passe-t-il si nous devons localiser cette image pour notre audience espagnole ? Comment ajouter une image spécifique pour la page espagnole ?

\n

Il suffit de déposer notre image dans le dossier de la langue espagnole :

\n
content\n├── english\n│   └── about\n│       ├── index.md\n│   └── header.jpg\n├── spanish\n│   └── about\n│       ├── index.md\n│   └── header.jpg ✨\n└── french\n    └── about\n        └── index.md
\n

C'est tout, Hugo prendra en compte qu'une ressource dédiée pour la version espagnole de notre page about.

\n

Et pour la version française ? Quelle image va-t-elle utiliser ? Celle de la version espagnole ou celle de la version anglaise ?

\n

Dans ce cas Hugo va se baser sur la langue qui a le plus de poids et retourner la version correspondante. Comme dans notre configuration des langues, l'anglais a un indice de poids de 1, la version française héritera de la version de la ressource en anglais.

\n

Sachez qu'il est possible de renommer n'importe quel fichier pour lui affecter une langue. Si nous avions choisi ici de nous baser sur la méthode qui repose sur la nomenclature des fichiers, notre bundle pour la page about ressemblerait à ceci :

\n
content\n└── about\n    ├── index.md\n    ├── index.es.md\n    ├── index.fr.md\n    ├── header.jpg\n    └── header.es.jpg
\n\n

Configurer nos URLs

\n

Qu'en est-il des URLs de nos pages ? Nous pouvons redefinir le slug d'une URL depuis le front matter d'une page, mais qu'en est-il de l'URL de base de chacune de nos langues ?

\n

Par défaut, Hugo va stocker les pages de la langue par défaut à la racine du dossier de destination public et les autres langues dans leurs répertoires respectifs.

\n

Donc pour un site en anglais par défaut, les URLs de la page about et de ses traductions seront :

\n\n

C'est pas mal, mais je doute que l'équipe chargée du référencement soit vraiment satisfaite. Pour nous assurer que les URLs des pages correspondent à leur titre, il nous faut encore mettre à jour le slug des pages traduites :

\n
# about.fr.md\ntitle: À Propos\nslug: a-propos
\n
# acerda.es.md\ntitle: Acerda\nslug: acerda
\n

Ce qui a pour effet d'avoir des URLs traduites :

\n\n

Nous pourrions décider de stocker les pages en anglais dans un répertoire dédié simplement en définissant le paramètre defaultContentLanguageInSubdir à true dans notre fichier config.yaml

\n

Localisation des chaînes de caractères

\n

La convention pour la traduction des chaînes de caractères avec Hugo ressemble un peu à celle des fichiers .po de gettext. Les chaînes de chaque langue sont enregistrées dans un fichier nommé en fonction du code de la langue utilisée et stockées dans un dossier i18n/.

\n

Ce dossier peut se trouver à la racine de votre projet ou d'un thème.

\n\n

Pour nos trois langues, ça ressemble à quelque chose comme :

\n
# i18n/en.yaml 🇬🇧\n- id: hello\n  translation: \"Hello\"\n- id: how_are_you\n  translation: \"How are you doing?\"
\n
# i18n/fr.yaml 🇫🇷\n- id: hello\n  translation: \"Bonjour\"\n- id: how_are_you\n  translation: \"Comment allez-vous ?\"
\n
# i18n/es.yaml 🇪🇸\n- id: hello\n  translation: \"Hola\"\n- id: how_are_you\n  translation: \"¿Como estas?\"
\n

Comme vous pouvez le voir dans l'exemple ci-dessus, tout ce dont nous avons besoin c'est d'une chaîne qui servira de clé unique et d'une chaîne de caractère pour la traduction.

\n

Ensuite dans nos modèles de page, la fonction i18n d'Hugo se charge du reste.

\n
    \n
  1. Elle va tester si la clé passée en argument existe et retourner la traduction correspondante si elle existe.
    2. \n
  2. Si la clé n'existe pas pour la langue courante dans le fichier, elle affichera la traduction de la langue par défaut.
    3. \n
  3. Si la clé n'existe pas pour la langue par défaut, elle retourne une chaîne vide.
    4. \n
\n
<header>\n    {{ i18n \"hello\" }}\n    <hr>\n    {{ i18n \"how_are_you\" }}\n</header>
\n
<!-- /es/index.html 🇪🇸 -->\n<header>\n    Hola\n    <hr>\n    ¿Como estas?\n</header>
\n
<!-- /fr/index.html 🇫🇷 -->\n<header>\n    Bonjour\n    <hr>\n    Comment allez-vous ?\n</header>
\n

La fonction i18n a comme alias T. Si taper i18n est trop fatiguant pour vos petits doigts, vous pouvez donc utiliser la syntaxe abrégée : {{ T \"how_are_you\" }}.

\n

Mettre les chaînes au pluriel

\n

Les chaînes ne font pas toujours référence à une entité unique. Elles peuvent parfois qualifier une seule chose, parfois plus. Comment donc nous assurer qu'une phrase sera fidèlement traduite au singulier comme au pluriel ?

\n

Hugo possède bien une fonction pluralize, mais elle ne gère que l'anglais.

\n

Heureusement pour nous, les chaînes de traduction d'Hugo nous permettent de gérer parfaitement les autres langues.

\n

Afin de mieux illustrer cette fonctionnalité, nous allons utiliser des exemples dans lesquels figurent… des rongeurs 🐭 ! N'ayez pas peur, ce sont simplement des pluriels intéressants dans les trois langues.

\n

Comment ça marche ? Hé bien, il s'avère que la valeur de notre traduction peut également être une liste de pluriels.

\n
# i18n/en.yaml 🇬🇧\n- id: mouse\n  translation:\n    one: Mouse\n    other: Mice
\n

Excellent, notre chaîne a maintenant un singulier (one) et une autre version (other) qui sera donc notre pluriel.

\n

Renseignons donc nos autres fichiers :

\n
# i18n/es.yaml 🇪🇸\n- id: mouse\n  translation:\n    one: Ratón\n    other: Ratones
\n
# i18n/fr.yaml 🇫🇷\n- id: mouse\n  translation:\n    other: Souris
\n

Comme en français le mot souris est invariable au singulier et au pluriel, nous n'avons qu'à renseigner la version générique other.

\n

La fonction i18n peut prendre un entier comme deuxième paramètre, afin de préciser à combien d'éléments fait référence notre chaîne et à pouvoir la mettre au pluriel si nécessaire.

\n
{{ range .Pages }}\n    <h3>{{ $.Title }}</h3>\n    {{ with .Params.mice }}\n        {{ i18n \"this_story_has\" }} {{ . }} {{ i18n \"mouse\" . }}.\n    {{ end }}\n    <hr>\n{{ end }}
\n

Imaginons que nous avons deux histoires, la première avec 24 souris et la seconde avec une seule, voici quel serait le HTML compilé :

\n
<h3>Cinderella</h3>\nThis story has 24 Mice.\n<hr>\n<h3>Fantasia</h3>\nThis story has 1 Mouse.\n<hr>
\n

Inclure le nombre d'unités dans la traduction

\n

Vous pouvez même ajouter le nombre exact à la traduction de votre chaîne à l'aide de .Count et fusionner l'ensemble dans une seule chaîne de caractère (notez l'utilisation des guillemets) :

\n
- id: story_mice\n  translation:\n    other: \"This story has {{ .Count }} Mice\"\n    one: This story has only one Mouse
\n

Dorénavant le nombre de souris sera retourné en sortie de la fonction i18n, nous pouvons mettre à jour notre code pour qu'il utilise plutôt cette chaîne unique :

\n
- {{ i18n \"this_story_has\" }} {{ . }} {{ i18n \"mouse\" . }}\n+ {{ i18n \"story_mice\" . }}
\n

Le HTML compilé correspondant sera :

\n
<h3>Cinderella</h3>\nThis story has 24 Mice.\n<hr>\n<h3>Fantasia</h3>\nThis story has only one Mouse.\n<hr>
\n\n

Inclusion du contexte dans la traduction

\n

Vous pouvez également passer en second paramètre un contexte à la fonction i18n plutôt qu'un entier.\nLà encore cela peut nous éviter de découper nos phrases en plusieurs chaînes de traduction, quand nous avons besoin de plus que de .Count.

\n
# i18n/en.yaml\n- id: intro\n  translation:  \"This is the story of {{ .Params.lead }}{{ with .Params.location }} which takes place in {{ . }}{{ end }}\"
\n
# i18n/en.yaml\n- id: intro\n  translation:  \"Voici l'histoire de {{ .Params.lead }}{{ with .Params.location }} qui se déroule à {{ . }}{{ end }}\"
\n

C'est le même principe que le contexte d'un fichier partiel.

\n
<h3>{{ .Title }}</h3>\n<div class=\"intro\">{{ i18n \"intro\" . }}</div>
\n
<h3>The Great Mouse Detective</h3>\n<div class=\"intro\">This is the story of Basil which takes place in London</div>
\n

Lorsque vous passez un contexte en paramètre d'i18n, vous devez garder certaines choses en tête :

\n
    \n
  1. i18n ne pourra évaluer ce paramètre comme un nombre (puisque ce n'en est pas un), donc impossible de mettre cette chaîne au pluriel à l'aide de one et other.
    2. \n
  2. Si cette chaîne est appelée à différents endroits, assurez-vous de toujours lui passer le même contexte ou bien utilisez with comme nous l'avons fait ci-dessus, si vous ne voulez pas vous retrouver avec une erreur bien moche du type can't evaluate field.
    3. \n
\n

Traduction des chaînes avec le système de fichier d'Hugo

\n

Rappelez-vous que nos fichiers i18n sont inclus dans le système de fichier global d'Hugo. En conséquence, tous les fichiers en.yaml présents dans l'arborescence de notre projet Hugo seront fusionnés.

\n

Si une des traductions du thème que nous utilisons ne nous plaît pas, nous n'avons qu'à créer un fichier i18n/en.yaml à la racine de notre projet (ou de notre composant de thème prioritaire) pour y ajouter notre version de cette traduction et uniquement celle-ci.

\n
# i18n/en.yaml\n- id: mouse\n  translation:\n    one: Rodent\n    other: Rodents
\n

C'est tout ! Pour les autres langues, Hugo se basera sur les Souris et les Ratones 🐁 déclarés dans themes/miceandmen/i18n/.

\n

Un dernier mot sur les singuliers et les pluriels

\n

L'anglais comme le français, l'espagnol et bien d'autres langues ne connaît que deux formes de pluralisation, c'est soit du singulier soit du pluriel.

\n

Donc dans Hugo assez logiquement, pour le traitement d'une chaîne en anglais, les seules possibilités de mettre au pluriel seront one ou other.

\n

La version à utiliser est déterminée par ce test tout simple :

\n

si l'entier passé en paramètre de i18n == 1 👉 one
\nsinon 👉 other

\n

C'est tout pour la plupart des langues européennes !

\n

Maintenant, d'autres langues comme le Russe ont des pluriels spécifiques pour few et many, l'arabe a une forme pour zero et une pour two 1

\n

Si nous pouvons deviner sans mal le nombre correspondant au pluriel de zero ou two, connaître le nombre exact d'éléments correspondants à few ou many en Russe ressemble davantage à un casse-tête.

\n

Heureusement, nous pouvons nous reposer sur Hugo et go-i18n de Nick Snyder pour nous aider à assembler toutes les pièces du puzzle.

\n\n

Mais, cela ne veut pas dire pour autant que vous pouvez les utiliser en anglais.

\n

Si la langue courante est l'anglais, que votre total de souris est nul, et que vous précisez que le pluriel pour zero est This story has no mouse, vous vous retrouverez quand même avec la valeur utilisée pour other : This story has 0 Mice.

\n

La valeur zero n'est prise en compte que si la langue courante est l'arabe ou si cette langue supporte un pluriel pour zero.

\n

Conclusion 🏁

\n

Traduire des chaînes de caractères dans Hugo consiste à écrire un ou plusieurs fichiers de données pour chacune des langues supportée par votre projet.

\n

Nous avons vu qu'Hugo offre une solution de localisation très simple et très efficace, que ce soit pour aider les contributeurs à traduire des contenus, ou permettre aux développeurs de supporter plusieurs langues dans les modèles de page.

\n

Si vous avez été amenés à gérer des projets multilingues plus complexes que ceux présentés ici, si vous pensez pouvoir enrichir cet article ou que vous avez vérifié le nombre exact de souris présentes dans Cendrillon2, faite-le savoir en commentaire.

\n
\n
\n
    \n
  1. \n

    http://www.unicode.org/cldr/charts/33/supplemental/language_plural_rules.html ↩

    \n
    2. \n
  2. \n

    Evidemment, j'ai pris un nombre au pif ! ↩

    \n
    3. \n
\n
", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/07/21/hugo-asset-pipeline/", "url": "https://jamstatic.fr/2018/07/21/hugo-asset-pipeline/", "title": "La gestion des assets avec Hugo", "summary": "Depuis la version 0.43 Hugo offre une gestion des assets: Sass, minification, support de postCSS, concaténation des fichiers JS, et plus encore.", "date_published": "2018-07-21T18:54:26+00:00","content_text": "Depuis la version 0.43, Hugo comble un des reproches qui lui a souvent été fait, le manque de solution native pour gérer les assets, à savoir la génération de fichiers CSS et JS pour la production — et le développement). Cette nouvelle possibilité fait d'Hugo une solution toujours plus performante pour le développement de sites statiques.\nHugo est surtout apprécié pour sa performance et son modèle de structuration de contenu, mais en ce qui concerne le traitement des fichiers CSS et JS, il fallait jusqu'ici avoir recours à l'écosystème npm, tout ça pour simplement pouvoir compiler des fichiers Sass, voire concaténer et minifier des fichiers JS. C'est désormais une dépendance dont on pourra se passer. Vous pouvez dire adieu à Webpack, Gulp et à votre package.json jamais à jour.\nTraitement des assets\n\n\n\n\n\n\nPhoto de Neil Cooper\n\nLe principe est simple : tout ce qui se trouve dans le dossier \/assets (que ce soit dans un thème ou pas) pourra être ensuite traité par des fonctions spécifiques aux assets. Pour les plus exigeants, ce chemin par défaut est paramétrable via la directive assetDir dans votre fichier de configuration.\nOn peut donc par exemple écrire ceci dans un fichier de layout :\n{{ $styles := resources.Get \"scss\/main.scss\" | toCSS | minify }}\n<link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">\nIci on récupère le contenu du fichier \/assets\/scss\/main.scss et on lui applique successivement deux fonctions : d'abord toCSS (alias de resources.ToCSS) pour compiler le fichier Sass puis minify (alias de resources.Minify). La syntaxe des pipes en Go template est la même que celle que vous utilisez déjà dans votre shell UNIX ou que celle des filtres Liquid, ça rend les choses plutôt intuitives.\nDifficile de faire plus concis et plus simple vous en conviendrez.\nMaintenant vous pourriez argumenter que pendant le développement, vous n'avez pas besoin de la minification. Par contre vous aimeriez bien générer des fichiers source map pour développer dans votre navigateur web préféré. Qu'à cela ne tienne, grâce à la fonction isServer qui détecte si vous êtes en train de développer localement avec hugo server ou pas, vous pouvez personnaliser ce qui est généré.\nPrenons donc un exemple un peu plus réaliste :\n{{ if .Site.IsServer }}\n {{ $cssOpts := (dict \"targetPath\" \"assets\/css\/main.css\" \"enableSourceMap\" true) }}\n {{ $styles := resources.Get \"scss\/main.scss\" | toCSS $cssOpts }}\n <link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">\n{{ else }}\n {{$cssOpts := (dict \"targetPath\" \"assets\/css\/main.css\") }}\n {{ $styles := resources.Get \"scss\/main.scss\" | toCSS $cssOpts | postCSS | minify | fingerprint }}\n <link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">\n{{ end }}\nIci, pendant le développement avec hugo server, on stocke d'abord les options à passer à la fonction toCSS dans une liste de clés-valeurs, le chemin où nous voulons générer notre fichier CSS ainsi que le mapping avec le fichier Sass source.\nPuis comme précédemment on applique le tout à notre fichier principal Sass. Enfin on pointe vers l'URL du fichier généré dans la balise link.\nLes options de la fonction toCSS sont légèrement différentes si c'est pour être hébergé en production, à ce moment-là on ne génère pas de fichier source map. Par contre on peut choisir d'appliquer d'autres fonctions à notre fichier CSS, comme par exemple un post-traitement avec postCSS, au hasard autoprefixer ou l'application d'une empreinte unique pour faciliter l'invalidation de cache à chaque nouvelle version du fichier. Notez que si vous utilisez la fonction postCSS, cela implique d'avoir les packages npm qui vont bien sur votre machine, que ce soit en global ou en local.\nEt ensuite ?\nVous pouvez aller jeter un œil au dépôt d'exemple de l'utilisation de Sass avec Hugo sur GitHub pour un exemple plus complet, qui montre notamment comment surcharger des variables Sass depuis le fichier de configuration d'Hugo. Bud Parr a également publié un exemple de configuration avec PostCSS, TailwindCSS, PurgeCSS et autoprefixer.\nVous pouvez également placer des images dans le répertoire assets et procéder à des transformations comme c'était déjà possible au niveau des ressources d'une page.\nPour le JS, sachez qu'il existe une fonction pour la concaténation, qui vous permettra de faire vos bundle en fonction des fichiers dont vous avez besoin dans vos layouts.\nJe vous recommande chaudement de lire l'article de Régis Philibert qui détaille l'utilisation des différentes fonctions offertes par Hugo pour la gestion des assets et bien entendu de vous référer à la documentation officielle qui est toujours à jour.\nMine de rien, non seulement ces ajouts vont vous permettre de supprimer des dépendances à vos projets Hugo mais en plus ils permettent de bénéficier d'une meilleure expérience de développement. Non parce que lancer Webpack pour démarrer le serveur d'Hugo, c'est… lourd.\nOn notera qu'il existe maintenant deux versions des binaires d'Hugo, celle avec le support de la gestion des assets c'est la version extended.\nSi vous utilisez Netlify pour générer automatiquement votre site à chaque commit, sachez que la version extended n'est pas encore disponible à l'heure où j'écris ces lignes.\nLa génération des fichiers CSS et des fichiers JS n'est pas quelque chose que vous avez forcément besoin de lancer à chaque build, ou à chaque fois qu'un contributeur édite un fichier Markdown dans votre headless CMS.\nEn fonction de votre contexte vous pouvez choisir de :\n\ngénérer les assets localement avec hugo et commiter les fichiers générés dans le répertoire resources à chaque fois que vous modifiez le contenu du dossier assets,\nrecopier et commiter la version étendue du ficher binaire d'Hugo dans le répertoire bin de votre dépôt et modifier la commande de build en .\/bin\/hugo au lieu de hugo.\n\nEn combinant ces fonctions aux conventions existantes d'Hugo , les développeurs de thèmes peuvent maintenant fournir des fichiers de configuration pour toujours plus de personnalisation.\nConclusion\nHugo continue de se tailler une bonne place dans le monde des générateurs de site statique et mérite plus que jamais que vous tentiez l'expérience. Il se définit désormais comme un véritable framework de développement, si l'on en croit sa baseline officielle. Hugo n'en reste pas moins une application monolithique comparée aux autres SSG de l'écosystème npm comme Gatsby ou Next, à vous de voir si l'ensemble de fonctionnalités dont il dispose maintenant suffit pour votre projet.", "content_html": "\n

Hugo est surtout apprécié pour sa performance et son modèle de structuration de contenu, mais en ce qui concerne le traitement des fichiers CSS et JS, il fallait jusqu'ici avoir recours à l'écosystème npm, tout ça pour simplement pouvoir compiler des fichiers Sass, voire concaténer et minifier des fichiers JS. C'est désormais une dépendance dont on pourra se passer. Vous pouvez dire adieu à Webpack, Gulp et à votre package.json jamais à jour.

\n

Traitement des assets

\n
\n\n\n\n\"Photo\n\n
Photo de Neil Cooper
\n
\n

Le principe est simple : tout ce qui se trouve dans le dossier /assets (que ce soit dans un thème ou pas) pourra être ensuite traité par des fonctions spécifiques aux assets. Pour les plus exigeants, ce chemin par défaut est paramétrable via la directive assetDir dans votre fichier de configuration.

\n

On peut donc par exemple écrire ceci dans un fichier de layout :

\n
{{ $styles := resources.Get \"scss/main.scss\" | toCSS | minify }}\n<link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">
\n

Ici on récupère le contenu du fichier /assets/scss/main.scss et on lui applique successivement deux fonctions : d'abord toCSS (alias de resources.ToCSS) pour compiler le fichier Sass puis minify (alias de resources.Minify). La syntaxe des pipes en Go template est la même que celle que vous utilisez déjà dans votre shell UNIX ou que celle des filtres Liquid, ça rend les choses plutôt intuitives.\nDifficile de faire plus concis et plus simple vous en conviendrez.

\n

Maintenant vous pourriez argumenter que pendant le développement, vous n'avez pas besoin de la minification. Par contre vous aimeriez bien générer des fichiers source map pour développer dans votre navigateur web préféré. Qu'à cela ne tienne, grâce à la fonction isServer qui détecte si vous êtes en train de développer localement avec hugo server ou pas, vous pouvez personnaliser ce qui est généré.

\n

Prenons donc un exemple un peu plus réaliste :

\n
{{ if .Site.IsServer }}\n  {{ $cssOpts := (dict \"targetPath\" \"assets/css/main.css\" \"enableSourceMap\" true) }}\n  {{ $styles := resources.Get \"scss/main.scss\" | toCSS $cssOpts }}\n  <link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">\n{{ else }}\n  {{$cssOpts := (dict \"targetPath\" \"assets/css/main.css\") }}\n  {{ $styles := resources.Get \"scss/main.scss\" | toCSS $cssOpts | postCSS | minify | fingerprint }}\n  <link rel=\"stylesheet\" href=\"{{ $styles.Permalink }}\" media=\"screen\">\n{{ end }}
\n

Ici, pendant le développement avec hugo server, on stocke d'abord les options à passer à la fonction toCSS dans une liste de clés-valeurs, le chemin où nous voulons générer notre fichier CSS ainsi que le mapping avec le fichier Sass source.\nPuis comme précédemment on applique le tout à notre fichier principal Sass. Enfin on pointe vers l'URL du fichier généré dans la balise link.

\n

Les options de la fonction toCSS sont légèrement différentes si c'est pour être hébergé en production, à ce moment-là on ne génère pas de fichier source map. Par contre on peut choisir d'appliquer d'autres fonctions à notre fichier CSS, comme par exemple un post-traitement avec postCSS, au hasard autoprefixer ou l'application d'une empreinte unique pour faciliter l'invalidation de cache à chaque nouvelle version du fichier. Notez que si vous utilisez la fonction postCSS, cela implique d'avoir les packages npm qui vont bien sur votre machine, que ce soit en global ou en local.

\n

Et ensuite ?

\n

Vous pouvez aller jeter un œil au dépôt d'exemple de l'utilisation de Sass avec Hugo sur GitHub pour un exemple plus complet, qui montre notamment comment surcharger des variables Sass depuis le fichier de configuration d'Hugo. Bud Parr a également publié un exemple de configuration avec PostCSS, TailwindCSS, PurgeCSS et autoprefixer.

\n

Vous pouvez également placer des images dans le répertoire assets et procéder à des transformations comme c'était déjà possible au niveau des ressources d'une page.

\n

Pour le JS, sachez qu'il existe une fonction pour la concaténation, qui vous permettra de faire vos bundle en fonction des fichiers dont vous avez besoin dans vos layouts.

\n

Je vous recommande chaudement de lire l'article de Régis Philibert qui détaille l'utilisation des différentes fonctions offertes par Hugo pour la gestion des assets et bien entendu de vous référer à la documentation officielle qui est toujours à jour.

\n

Mine de rien, non seulement ces ajouts vont vous permettre de supprimer des dépendances à vos projets Hugo mais en plus ils permettent de bénéficier d'une meilleure expérience de développement. Non parce que lancer Webpack pour démarrer le serveur d'Hugo, c'est… lourd.

\n

On notera qu'il existe maintenant deux versions des binaires d'Hugo, celle avec le support de la gestion des assets c'est la version extended.

\n

Si vous utilisez Netlify pour générer automatiquement votre site à chaque commit, sachez que la version extended n'est pas encore disponible à l'heure où j'écris ces lignes.

\n

La génération des fichiers CSS et des fichiers JS n'est pas quelque chose que vous avez forcément besoin de lancer à chaque build, ou à chaque fois qu'un contributeur édite un fichier Markdown dans votre headless CMS.

\n

En fonction de votre contexte vous pouvez choisir de :

\n\n

En combinant ces fonctions aux conventions existantes d'Hugo , les développeurs de thèmes peuvent maintenant fournir des fichiers de configuration pour toujours plus de personnalisation.

\n

Conclusion

\n

Hugo continue de se tailler une bonne place dans le monde des générateurs de site statique et mérite plus que jamais que vous tentiez l'expérience. Il se définit désormais comme un véritable framework de développement, si l'on en croit sa baseline officielle. Hugo n'en reste pas moins une application monolithique comparée aux autres SSG de l'écosystème npm comme Gatsby ou Next, à vous de voir si l'ensemble de fonctionnalités dont il dispose maintenant suffit pour votre projet.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/05/31/startups-jamstack/", "url": "https://jamstatic.fr/2018/05/31/startups-jamstack/", "title": "Les startups de l’écosystème Jamstack", "summary": "Les capital risqueurs de la Silicon Valley misent sur les startups qui forment l'écosytème de la Jamstack.", "date_published": "2018-05-31T18:21:08+00:00","content_text": "Devant la tendance croissante de l'adoption d'outils et de services web modernes pour gérer les sites ou les applications web, les investisseurs de la Silicon Valley misent assez tôt sur les startups issus de cet écosystème : Netlify, Algolia, Contentful et plus récemment Gatsby ont tous levé quelques millions de dollars pour les aider dans leur développement. Et ce n'est que le début, les annonces de financement devraient se poursuivre dans les prochains mois.\nDans cet article CRV montre une vue d'ensemble du résultat de plusieurs tendances qui ont permis l'émergence d'une nouvelle architecture frontend et par conséquence d'un écosystème fertile de startups.\nLa manière dont les sites web et les applications sont développés est en train de prendre un tournant architectural important — que ce soit les outils utilisés par les développeurs pour les construire ou l'UI\/UX proposée aux utilisateurs finaux. C'est une véritable révolution qui est en train de chambouler le monde du développement d'applications.\nPourquoi maintenant ?\nL'explosion de JavaScript : JS est devenu tellement puissant, avec un haut niveau d'abstraction il permet le développement d'applications plus interactives, plus rapides et l'amélioration de l'expérience de l'utilisateur final.\nLa prolifération des APIs : des microservices pour le backend à la popularité grandissante de GraphQL et aux frontends librement couplés, les APIs sont un élément central du changement architectural auquel nous assistons.\nDavantage de développeurs : le nombre grandissant de développeurs et la réduction du niveau de compétences moyen dans l'industrie. Tout cela fait qu'il y a beaucoup plus de développeurs qui ont envie d'apprendre et de se former à de nouveaux outils.\nL'essor de Git : les processus basés sur Git sont désormais au cœur de la collaboration entre développeurs et du versionnement de projet.\nLes progrès des infrastructures du Cloud : la réduction des coûts de fonctionnement, les architectures serverless et un outillage plus complet permettent aux développeurs de se concentrer sur le design et le développement de l'interface client et de bâtir de façon plus efficace des applications plus performantes.\nQuelle que soit votre idéologie — les clients lourds\/légers, les Single Page Applications (SPA) avec rendu côté serveur, les sites dynamiques\/statiques — la manière dont la partie cliente est développée est en train de changer\nL'histoire de la Jamstack\nLes sites dynamiques ont pris le pas sur les sites statiques, car ils proposaient plus d'interactivité et de personnalisation, cela n'allait pas sans problèmes de performance, de sécurité et s'accompagnait de coûts de fonctionnement élevés. Avec les navigateurs web modernes, les enseignements tirés du développement d'application mobile, les offres de cloud public arrivées enfin à maturité, l'interactivité d'HTML5 couplé à JavaScript et à des APIs comme Disqus ou Algolia, nous avons l'opportunité de revenir à la simplicité des sites web statiques. Pour faire passer le message aux développeurs, des gens comme Matt Biilmann, le créateur et le CEO de Netlify, ont diffusé le concept de la Jamstack: une approche différente, serverless pour développer des sites web modernes et performants. JAM signifie JavaScript, APIs et Markup et l'idée centrale est de ne plus avoir à gérer ses propres serveurs, d'héberger le code sur des CDNs rapides, fiables et sécurisés et de faire interagir les navigateurs avec les APIs qui peuvent s'occuper des composants « dynamiques ». La Jamstack personnifie toutes les tendances soulignées plus haut.\nLe paysage de la Jamstack\nCette image illustre le paysage florissant des startups avec quelques projets open source et des membres clés de la communauté, qui profitent des tendances mentionnées plus haut.\n\n\n\n\n\nLes bénéfices\nIl en résulte des sites plus sécurisés, des déploiements et des temps de chargement plus rapides, moins onéreux et plus faciles à gérer. Ça a l'air trop beau pour être vrai ? Contrairement à la stack LAMP, il n'y a pas de base de données dans la Jamstack, donc moins d'appels aux backend et une surface d'attaque réduite. Les sites web (comme ceux développés avec WordPress) ont particulièrement été la cible d'attaques malveillantes, mais en l'absence de base de données et de plugins, les menaces sont considérablement réduites.\nLe découplage de la partie client de la partie serveur permet également aux développeurs de se connecter aux meilleures APIs tierces comme celle d'Algolia pour la recherche par exemple. La partie CMS reste critique et des CMS headless (ou API-first comme Contentful or Tipe) permettent plus de collaboration entre le design, le marketing et les développeurs. Avec un process de travail basé sur Git, il est bien plus simple de mettre à jour un site ou une application, on peut déployer à partir de GitHub, s'assurer que le contenu est à jour, revenir à une version précédente et identifier l'origine des anomalies.\nEt ensuite ?\nPermettre une meilleure collaboration entre toutes les parties prenantes du frontend — les créateurs de contenus, les gens du marketing, du design et du développement. « Les développeurs détestent avoir à créer et éditer du texte, les créateurs de contenu détestent devoir passer par les développeurs pour apporter des modifications simples » — Scott Moss, CEO de Tipe.\nLa conception d'interface basée sur des composants est en pleine expansion, l'utilisation de Storybook décolle (10% des téléchargements React) et les composants réutilisables vont accélérer la vitesse de développement, en particulier celle des équipes. « L'adoption de React, Vue et Angular s'accompagne d'un changement de paradigme vers le développement basé sur des composants et Storybook est au cœur de ce mouvement » — Zoltan Olah, CEO de Chroma.\nDes services pour le frontend : des plate-formes comme Vercel et Netlify sont en train d'émerger, elles permettent de s'affranchir du temps et de la difficulté des différents processus de génération de site, de compilation des assets, de déploiement et de publication continue sur les serveurs d'hébergement.\nL'Edge Computing ouvre tant de nouvelles manières de concevoir des applications. Une fois que vous avez accès à du stockage performant à la périphérie du réseau, vous allez pouvoir facilement segmenter et personnaliser le trafic, gérer le contenu, en devant rarement aller taper sur le serveur d'origine ce qui vous permettra d'avoir des applications plus rapides.\nConclusion\nLes tendances du développement frontend et le changement architectural qui en résulte est très prometteur pour l'écosystème des startups et des capital-risqueurs. CRV aime prendre des risques au plus tôt, et a déjà investi dans 6 startups qui font partie du paysage de la Jamstack (dont 3 qui seront annoncées publiquement très bientôt). Si vous êtes un créateur de startup lié à cet écosystème, un investisseur ou que vous voulez simplement papoter, écrivez à reid@crv.com.", "content_html": "\n

Dans cet article CRV montre une vue d'ensemble du résultat de plusieurs tendances qui ont permis l'émergence d'une nouvelle architecture frontend et par conséquence d'un écosystème fertile de startups.

\n

La manière dont les sites web et les applications sont développés est en train de prendre un tournant architectural important — que ce soit les outils utilisés par les développeurs pour les construire ou l'UI/UX proposée aux utilisateurs finaux. C'est une véritable révolution qui est en train de chambouler le monde du développement d'applications.

\n

Pourquoi maintenant ?

\n

L'explosion de JavaScript : JS est devenu tellement puissant, avec un haut niveau d'abstraction il permet le développement d'applications plus interactives, plus rapides et l'amélioration de l'expérience de l'utilisateur final.

\n

La prolifération des APIs : des microservices pour le backend à la popularité grandissante de GraphQL et aux frontends librement couplés, les APIs sont un élément central du changement architectural auquel nous assistons.

\n

Davantage de développeurs : le nombre grandissant de développeurs et la réduction du niveau de compétences moyen dans l'industrie. Tout cela fait qu'il y a beaucoup plus de développeurs qui ont envie d'apprendre et de se former à de nouveaux outils.

\n

L'essor de Git : les processus basés sur Git sont désormais au cœur de la collaboration entre développeurs et du versionnement de projet.

\n

Les progrès des infrastructures du Cloud : la réduction des coûts de fonctionnement, les architectures serverless et un outillage plus complet permettent aux développeurs de se concentrer sur le design et le développement de l'interface client et de bâtir de façon plus efficace des applications plus performantes.

\n

Quelle que soit votre idéologie — les clients lourds/légers, les Single Page Applications (SPA) avec rendu côté serveur, les sites dynamiques/statiques — la manière dont la partie cliente est développée est en train de changer

\n

L'histoire de la Jamstack

\n

Les sites dynamiques ont pris le pas sur les sites statiques, car ils proposaient plus d'interactivité et de personnalisation, cela n'allait pas sans problèmes de performance, de sécurité et s'accompagnait de coûts de fonctionnement élevés. Avec les navigateurs web modernes, les enseignements tirés du développement d'application mobile, les offres de cloud public arrivées enfin à maturité, l'interactivité d'HTML5 couplé à JavaScript et à des APIs comme Disqus ou Algolia, nous avons l'opportunité de revenir à la simplicité des sites web statiques. Pour faire passer le message aux développeurs, des gens comme Matt Biilmann, le créateur et le CEO de Netlify, ont diffusé le concept de la Jamstack: une approche différente, serverless pour développer des sites web modernes et performants. JAM signifie JavaScript, APIs et Markup et l'idée centrale est de ne plus avoir à gérer ses propres serveurs, d'héberger le code sur des CDNs rapides, fiables et sécurisés et de faire interagir les navigateurs avec les APIs qui peuvent s'occuper des composants « dynamiques ». La Jamstack personnifie toutes les tendances soulignées plus haut.

\n

Le paysage de la Jamstack

\n

Cette image illustre le paysage florissant des startups avec quelques projets open source et des membres clés de la communauté, qui profitent des tendances mentionnées plus haut.

\n\n\n\n\"\"\n\n

Les bénéfices

\n

Il en résulte des sites plus sécurisés, des déploiements et des temps de chargement plus rapides, moins onéreux et plus faciles à gérer. Ça a l'air trop beau pour être vrai ? Contrairement à la stack LAMP, il n'y a pas de base de données dans la Jamstack, donc moins d'appels aux backend et une surface d'attaque réduite. Les sites web (comme ceux développés avec WordPress) ont particulièrement été la cible d'attaques malveillantes, mais en l'absence de base de données et de plugins, les menaces sont considérablement réduites.

\n

Le découplage de la partie client de la partie serveur permet également aux développeurs de se connecter aux meilleures APIs tierces comme celle d'Algolia pour la recherche par exemple. La partie CMS reste critique et des CMS headless (ou API-first comme Contentful or Tipe) permettent plus de collaboration entre le design, le marketing et les développeurs. Avec un process de travail basé sur Git, il est bien plus simple de mettre à jour un site ou une application, on peut déployer à partir de GitHub, s'assurer que le contenu est à jour, revenir à une version précédente et identifier l'origine des anomalies.

\n

Et ensuite ?

\n

Permettre une meilleure collaboration entre toutes les parties prenantes du frontend — les créateurs de contenus, les gens du marketing, du design et du développement. « Les développeurs détestent avoir à créer et éditer du texte, les créateurs de contenu détestent devoir passer par les développeurs pour apporter des modifications simples » — Scott Moss, CEO de Tipe.

\n

La conception d'interface basée sur des composants est en pleine expansion, l'utilisation de Storybook décolle (10% des téléchargements React) et les composants réutilisables vont accélérer la vitesse de développement, en particulier celle des équipes. « L'adoption de React, Vue et Angular s'accompagne d'un changement de paradigme vers le développement basé sur des composants et Storybook est au cœur de ce mouvement » — Zoltan Olah, CEO de Chroma.

\n

Des services pour le frontend : des plate-formes comme Vercel et Netlify sont en train d'émerger, elles permettent de s'affranchir du temps et de la difficulté des différents processus de génération de site, de compilation des assets, de déploiement et de publication continue sur les serveurs d'hébergement.

\n

L'Edge Computing ouvre tant de nouvelles manières de concevoir des applications. Une fois que vous avez accès à du stockage performant à la périphérie du réseau, vous allez pouvoir facilement segmenter et personnaliser le trafic, gérer le contenu, en devant rarement aller taper sur le serveur d'origine ce qui vous permettra d'avoir des applications plus rapides.

\n

Conclusion

\n

Les tendances du développement frontend et le changement architectural qui en résulte est très prometteur pour l'écosystème des startups et des capital-risqueurs. CRV aime prendre des risques au plus tôt, et a déjà investi dans 6 startups qui font partie du paysage de la Jamstack (dont 3 qui seront annoncées publiquement très bientôt). Si vous êtes un créateur de startup lié à cet écosystème, un investisseur ou que vous voulez simplement papoter, écrivez à reid@crv.com.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://strapi.io/blog/building-a-static-website-using-gatsby-and-strapi", "url": "https://strapi.io/blog/building-a-static-website-using-gatsby-and-strapi", "title": "Développer un blog statique avec Gatsby et Strapi", "summary": "Découvrez comment développer un blog en utilisant Gatsby et Strapi en quelques minutes.", "date_published": "2018-04-26T00:00:00+00:00","content_text": "Une nouvelle version de ce tutoriel a été publié en Février 2020 sur https:\/\/strapi.io\/blog\/build-a-static-blog-with-gatsby-and-strapi\nIntroduction\nUn site statique est un site dont le contenu est fixe. Techniquement, il est composé d’une simple liste de fichiers HTML, qui affiche les mêmes informations quel que soit le visiteur. Contrairement aux sites dynamiques, il ne requiert ni programmation back-end ni base de données. Publier un site statique est simple : il suffit d’uploader les fichiers sur un service de stockage et le tour est joué. Les deux principaux avantages d’un site web sont la sécurité et la vitesse : étant donné qu’il n’y a pas de base de données le site ne peut pas se faire hacker, et puisqu’il n’y a pas de génération de page à chaque requête, la navigation pour l’utilisateur est plus fluide.\nPour faciliter leur création, de nombreux générateurs de sites statiques sont disponibles: Jekyll, Hugo, Hexo, etc. La plupart du temps, le contenu est géré via des fichiers (idéalement en format Markdown) statiques ou via une API de contenu. Ensuite, le générateur requête le contenu, l’injecte dans les templates définis par le développeur et génère un ensemble de fichiers HTML, CSS et JavaScript.\nLes Progressive Web Apps (PWA) sont des applications web, reposant fortement sur l’utilisation de JavaScript, qui se veulent être fiables, rapides et engageantes. Étant donné qu’elles rendent la navigation plus rapide et qu’elles offrent une expérience utilisateur bien meilleure, les PWA sont devenues la manière par défaut de construire des interfaces web. Pour cette raison, de nombreux frameworks front-end ont fait leur apparition au cours des dernières années : Angular, React, et plus récemment, Vue.\n\nGatsby : quand les sites statiques rencontrent les Progressive Web Apps.\n\nLes sites Web statiques et PWA ont tous les deux de solides avantages, ce qui nous incite à trouver un moyen de les utiliser tous les deux dans le même projet. Heureusement, quelques outils ont réussi à faire le pont entre les deux, notamment celui dont on entend le plus parler depuis quelques mois : Gatsby. Nous avons donc décidé de vous donner un exemple complet pour vous apprendre à commencer à l’utiliser facilement. Un site statique a besoin d’une source de contenu : dans cet exemple, nous allons le délivrer grâce à une API créée avec Strapi.\nQu’est-ce que Gatsby ?\nD’après ses créateurs, Gatsby est un \"blazing-fast website framework for React\". Il permet aux développeurs de créer des sites construits avec React en quelques minutes. Que vous vouliez développer un blog ou un site vitrine, Gatsby devrait correspondre à vos besoins.\n\n\nLogo Gatsby\n\nÉtant donné que Gatsby utilise React, les pages générées ne sont jamais rechargées, ce qui rend le site extrêmement rapide. De nombreux plugins sont disponibles pour permettre aux développeurs de gagner du temps et de récupérer la donnée depuis n’importe quelle source (fichiers Markdown, CMS, etc.). Gatsby est fortement basé sur le concept de la \"node\" interface, qui est le centre du système de données de Gatsby.\nCréé par Kyle Mathews, le projet a été officiellement publié en juillet 2017 et est d’ores et déjà utilisé par des dizaines d’entreprises.\nQu’est-ce que Strapi?\nStrapi est le Content Management Framework le plus avancé sur la technologie Node.js. À mi-chemin entre un famework Nodejs et un Headless CMS (API-first), il permet d’économiser des semaines de développement.\n\n\nLogo Strapi\n\nGrâce à son système extensible de plugin, il propose de nombreuses fonctionnalités : panel d’administration, authentification et gestion des permissions, gestion de contenu, générateur d’API, etc.\nContrairement aux CMS en ligne, Strapi est 100% open-source, ce qui veut dire que :\n\nStrapi est totalement gratuit\nVous pouvez l’héberger sur vos propres serveurs. Vous êtes donc propriétaire de votre donnée.\nIl est entièrement personnalisable et extensible, grâce au système de plugins.\n\nInstallation de l’API\nTout d’abord, nous allons commencer par créer une API avec Strapi et ajouter du contenu.\nCréation du projet Strapi\nInstallation de Strapi\nPrérequis: vérifiez que Node 8 (ou plus) et MongoDB sont installés et démarrés sur votre machine.\nInstallez Strapi via npm :\nnpm i strapi@alpha -g\nNote : Strapi v3 est encore en version alpha, mais cela ne posera aucun problème pour la réalisation de ce tutoriel.\nCréation d’un projet Strapi\nCréez un dossier nommé gatsby-strapi-tutorial :\nmkdir gatsby-strapi-tutorial\nGénérez l’API au sein de ce nouveau dossier :\ncd gatsby-strapi-tutorial\nstrapi new api\nDémarrage du serveur\nEntrez à l’intérieur du projet généré :\ncd api\nDémarrez le serveur Node.js :\nstrapi start\nÀ partir de maintenant, vous devriez être à même de voir le panel d’administration de votre projet : http:\/\/localhost:1337\/admin.\nCréation du premier utilisateur\nAjoutez votre premier utilisateur depuis la page d’inscription.\n\n\n\n\n\n\nÉcran de création d’un utilisateur\n\nCréation d’un type de contenu\nLes API Strapi sont basées sur une structure de données appelée Content Types (équivalent des modèles dans les frameworks et des Content Types dans WordPress).\nCréez un Content Type nommé article contenant trois champs : title (type string), content (type text) et author (type relation: un utilisateur doit pouvoir être lié à plusieurs articles).\n\n\n\n\n\n\nÉcran de définition de relation\n\n\n\n\n\n\n\nÉcran des champs d’un article\n\nAjout d’articles\nAjoutez quelques articles en base de données. Pour cela, suivez les étapes suivantes :\n\nVisitez la page listant les articles.\nCliquer sur Add New Article.\nRenseignez un titre et un contenu, liez l’article à un auteur, puis valider.\nAjouter deux autres articles.\n\n\n\n\n\n\n\nÉcran listant des articles\n\nAutorisation d’accès\nPour des raisons de sécurité, l’accès à l’API est, par défaut, restreint.\nPour autoriser l’accès, visitez la section Auth & Permissions du rôle Guest, sélectionnez l’action Article - find et sauvegardez. À partir de ce moment, vous devriez être à même de requêter la liste d’articles.\nL’accès à l’API des auteurs est également restreint. Autorisez l’accès aux anonymes en sélectionnant l’action Users & Permissions - find puis en sauvegardant.\n\n\n\n\n\n\nÉcran du rôle Guest\n\nDéveloppement du site statique\nBien joué, votre API est prête à l’utilisation ! Nous allons maintenant commencer le développement du site statique.\nInstallation de Gatsby\nCommençez par installer Gatsby :\nnpm install --global gatsby-cli\nCréation d’un projet Gatsby\nDans le dossier gatsby-strapi-tutorial que vous avez précédemment créé, générez votre tout nouveau blog :\ngatsby new blog\nDémarrage en mode développement\nEntrez dans le dossier du projet :\ncd blog\nDémarrez le serveur :\ngatsby develop\nÀ partir de ce moment, votre site Gatsby devrait être disponible à l’adresse suivante : http:\/\/localhost:8000.\nInstallation du plugin source Strapi\nLorsque l’on crée un site statique, la donnée peut venir de différentes sources : fichiers Markdown, fichiers CSV, un site WordPress (utilisant le plugin JSON REST API), etc.\nGatsby l’a bien compris. C’est pourquoi ses créateurs ont décidé de construire une couche spécifique et indépendante : le Data layer. Le système entier repose sur GraphQL.\nPour connecter Gatsby à une nouvelle source de données, il faut développer un \"plugin source\". Heureusement, de nombreux plugins source sont déjà disponibles. Vous devriez donc réussir à trouver celui qui correspond le mieux à vos besoins.\nDans cet exemple nous utilisons Strapi. Nous allons donc évidemment avoir besoin d’un plugin source dédié au API Strapi. Bonne nouvelle : celui-ci existe déjà !\nInstallons-le :\nnpm install --save gatsby-source-strapi\nLe plugin a besoin d’être configuré. Remplacez le contenu du fichier gatsby-config.js avec :\nPath : gatsby-config.js\nmodule.exports = {\n siteMetadata: {\n title: `Gatsby Default Starter`,\n },\n plugins: [\n `gatsby-plugin-react-helmet`,\n {\n resolve: `gatsby-source-strapi`,\n options: {\n apiURL: `http:\/\/localhost:1337`,\n contentTypes: [\n \/\/ List of the Content Types you want to be able to request from Gatsby.\n `article`,\n `user`,\n ],\n },\n },\n ],\n};\nEnsuite, redémarrez le serveur afin que Gatsby prenne en compte ces changements.\nListe d’articles\nDans un premier temps, nous voulons afficher la liste d’articles. Pour cela, remplacez le contenu de la page d’accueil par le suivant :\nPath : src\/pages\/index.js\nimport React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst IndexPage = ({ data }) => (\n <div>\n <h1>Hi people<\/h1>\n <p>Welcome to your new Gatsby site.<\/p>\n <p>Now go build something great.<\/p>\n <ul>\n {data.allStrapiArticle.edges.map((document) => (\n <li key={document.node.id}>\n <h2>\n <Link to={`\/${document.node.id}`}>{document.node.title}<\/Link>\n <\/h2>\n <p>{document.node.content}<\/p>\n <\/li>\n ))}\n <\/ul>\n <Link to=\"\/page-2\/\">Go to page 2<\/Link>\n <\/div>\n);\n\nexport default IndexPage;\n\nexport const pageQuery = graphql`\n query IndexQuery {\n allStrapiArticle {\n edges {\n node {\n id\n title\n content\n }\n }\n }\n }\n`;\nQue venons-nous de faire ?\nÀ la fin du fichier nous exportons pageQuery : une requête GraphQL qui requête la liste entière des articles. Comme vous pouvez le voir, nous requêtons uniquement les champs id, title et content grâce à la précision du langage GraphQL.\nEnsuite, nous passons l’objet déstructuré { data } comme paramètre de IndexPage et nous bouclons sur son objet allStrapiArticles afin d’afficher la donnée.\n\n\n\n\n\n\nExemple d’écran d’accueil\n\nAstuce : générez vos requêtes GraphQL en quelques secondes !\nGatsby inclut l’excellente interface GraphiQL. Cela facilite grandement la création de requêtes GraphQL. Jetez-y un œil et tentez de créer quelques requêtes.\nVue article\nNotre site commence à ressembler à un blog. C’est une bonne nouvelle ! Cependant, une partie importante est encore manquante : la page article.\nCommençons par créer le template contenant la requête GraphQL et définissant le contenu affiché :\nPath : src\/templates\/article.js\nimport React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst ArticleTemplate = ({ data }) => (\n <div>\n <h1>{data.strapiArticle.title}<\/h1>\n <p>\n by{\" \"}\n <Link to={`\/authors\/${data.strapiArticle.author.id}`}>\n {data.strapiArticle.author.username}\n <\/Link>\n <\/p>\n <p>{data.strapiArticle.content}<\/p>\n <\/div>\n);\n\nexport default ArticleTemplate;\n\nexport const query = graphql`\n query ArticleTemplate($id: String!) {\n strapiArticle(id: { eq: $id }) {\n title\n content\n author {\n id\n username\n }\n }\n }\n`;\nTout semble prêt, mais en réalité, Gatsby ne sait pas quand ce template devrait être affiché. Chaque article a besoin d’une URL. Nous allons donc informer Gatsby des nouvelles URLs que nous souhaitons, grâce à la fonction createPage.\nTout d’abord, nous allons déclarer une nouvelle fonction nommée makeRequest afin d’exécuter la requête GraphQL. Ensuite, nous exportons une fonction nommée createPages dans laquelle nous récupérons la liste d’articles et créons une page pour chacun d’entre eux. Voici le résultat :\nPath : gatsby-node.js\nconst path = require(`path`);\n\nconst makeRequest = (graphql, request) =>\n new Promise((resolve, reject) => {\n \/\/ Query for nodes to use in creating pages.\n resolve(\n graphql(request).then((result) => {\n if (result.errors) {\n reject(result.errors);\n }\n\n return result;\n })\n );\n });\n\n\/\/ Implement the Gatsby API “createPages”. This is called once the\n\/\/ data layer is bootstrapped to let plugins create pages from data.\nexports.createPages = ({ boundActionCreators, graphql }) => {\n const { createPage } = boundActionCreators;\n\n const getArticles = makeRequest(\n graphql,\n `\n {\n allStrapiArticle {\n edges {\n node {\n id\n }\n }\n }\n }\n `\n ).then((result) => {\n \/\/ Create pages for each article.\n result.data.allStrapiArticle.edges.forEach(({ node }) => {\n createPage({\n path: `\/${node.id}`,\n component: path.resolve(`src\/templates\/article.js`),\n context: {\n id: node.id,\n },\n });\n });\n });\n\n \/\/ Query for articles nodes to use in creating pages.\n return getArticles;\n};\nRedémarrez le serveur Gatsby.\nÀ partir de maintenant, vous devriez pouvoir visiter les pages de chaque article en cliquant sur les liens affichés sur la page d’accueil.\n\n\n\n\n\n\nExemple de page\n\nVue auteur\nLes articles sont rédigés par des auteurs. Eux-aussi méritent une page dédiée.\nLa création de la page auteur est très similaire à celle de la page article. Premièrement, nous créons le template :\nPath : src\/templates\/user.js\nimport React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst UserTemplate = ({ data }) => (\n <div>\n <h1>{data.strapiUser.username}<\/h1>\n <ul>\n {data.strapiUser.articles.map((article) => (\n <li key={article.id}>\n <h2>\n <Link to={`\/${article.id}`}>{article.title}<\/Link>\n <\/h2>\n <p>{article.content}<\/p>\n <\/li>\n ))}\n <\/ul>\n <\/div>\n);\n\nexport default UserTemplate;\n\nexport const query = graphql`\n query UserTemplate($id: String!) {\n strapiUser(id: { eq: $id }) {\n id\n username\n articles {\n id\n title\n content\n }\n }\n }\n`;\nEnsuite, nous mettons à jour le fichier gatsby-node.js pour créer les URLs :\nPath : gatsby-node.js\nconst path = require(`path`);\n\nconst makeRequest = (graphql, request) =>\n new Promise((resolve, reject) => {\n \/\/ Query for article nodes to use in creating pages.\n resolve(\n graphql(request).then((result) => {\n if (result.errors) {\n reject(result.errors);\n }\n\n return result;\n })\n );\n });\n\n\/\/ Implement the Gatsby API “createPages”. This is called once the\n\/\/ data layer is bootstrapped to let plugins create pages from data.\nexports.createPages = ({ boundActionCreators, graphql }) => {\n const { createPage } = boundActionCreators;\n\n const getArticles = makeRequest(\n graphql,\n `\n {\n allStrapiArticle {\n edges {\n node {\n id\n }\n }\n }\n }\n `\n ).then((result) => {\n \/\/ Create pages for each article.\n result.data.allStrapiArticle.edges.forEach(({ node }) => {\n createPage({\n path: `\/${node.id}`,\n component: path.resolve(`src\/templates\/article.js`),\n context: {\n id: node.id,\n },\n });\n });\n });\n\n const getAuthors = makeRequest(\n graphql,\n `\n {\n allStrapiUser {\n edges {\n node {\n id\n }\n }\n }\n }\n `\n ).then((result) => {\n \/\/ Create pages for each user.\n result.data.allStrapiUser.edges.forEach(({ node }) => {\n createPage({\n path: `\/authors\/${node.id}`,\n component: path.resolve(`src\/templates\/user.js`),\n context: {\n id: node.id,\n },\n });\n });\n });\n\n \/\/ Queries for articles and authors nodes to use in creating pages.\n return Promise.all([getArticles, getAuthors]);\n};\nDernière étape : redémarrez le serveur et visitez la page auteur depuis la page d’un article.\n\n\n\n\n\n\nExemple de page\n\nConclusion\nFélicitations ! Vous avez créé un blog super rapide et facile à maintenir !\nÉtant donné que le contenu est géré dans Strapi, les auteurs peuvent écrire leurs articles depuis une vraie interface et vous, en tant que développeur, n’avez qu’à recompiler le site pour mettre à jour le contenu.\nQue faire ensuite ?\nN’hésitez pas à continuer le projet pour découvrir plus en profondeur les avantages de Gatsby et de Strapi. Voici une liste de fonctionnalités que vous pourriez ajouter à votre projet : liste des auteurs, catégories d’articles, système de commentaire avec l’API Strapi ou Disqus, etc. Vous pouvez aussi créer tout type de site (boutique e-commerce, site vitrine, etc.).\nLorsque votre projet sera terminé, vous voudrez probablement le déployer. Le site statique généré par Gatsby peut facilement être publiée sur des services de stockage tels que Netlify, S3\/Cloudfront, GitHub pages, GitLab, Heroku, etc. L’API Strapi n’est rien d’autre qu’une application Node.js. Elle peut donc être mise en ligne sur Heroku ou sur n’importe quelle instance Linux ayant Node.js installé dessus.\nLe code source de ce tutoriel est disponible sur GitHub. Pour le tester, clonez-le repository et suivez les instructions présentes dans le Readme.\nNous espérons que vous avez apprécié ce tutoriel. N’hésitez pas à le commenter, le partager, et indiquer quelle est votre manière favorite de créer des sites avec React et d’en gérer le contenu.", "content_html": "\n

Introduction

\n

Un site statique est un site dont le contenu est fixe. Techniquement, il est composé d’une simple liste de fichiers HTML, qui affiche les mêmes informations quel que soit le visiteur. Contrairement aux sites dynamiques, il ne requiert ni programmation back-end ni base de données. Publier un site statique est simple : il suffit d’uploader les fichiers sur un service de stockage et le tour est joué. Les deux principaux avantages d’un site web sont la sécurité et la vitesse : étant donné qu’il n’y a pas de base de données le site ne peut pas se faire hacker, et puisqu’il n’y a pas de génération de page à chaque requête, la navigation pour l’utilisateur est plus fluide.

\n

Pour faciliter leur création, de nombreux générateurs de sites statiques sont disponibles: Jekyll, Hugo, Hexo, etc. La plupart du temps, le contenu est géré via des fichiers (idéalement en format Markdown) statiques ou via une API de contenu. Ensuite, le générateur requête le contenu, l’injecte dans les templates définis par le développeur et génère un ensemble de fichiers HTML, CSS et JavaScript.

\n

Les Progressive Web Apps (PWA) sont des applications web, reposant fortement sur l’utilisation de JavaScript, qui se veulent être fiables, rapides et engageantes. Étant donné qu’elles rendent la navigation plus rapide et qu’elles offrent une expérience utilisateur bien meilleure, les PWA sont devenues la manière par défaut de construire des interfaces web. Pour cette raison, de nombreux frameworks front-end ont fait leur apparition au cours des dernières années : Angular, React, et plus récemment, Vue.

\n
\n

Gatsby : quand les sites statiques rencontrent les Progressive Web Apps.

\n
\n

Les sites Web statiques et PWA ont tous les deux de solides avantages, ce qui nous incite à trouver un moyen de les utiliser tous les deux dans le même projet. Heureusement, quelques outils ont réussi à faire le pont entre les deux, notamment celui dont on entend le plus parler depuis quelques mois : Gatsby. Nous avons donc décidé de vous donner un exemple complet pour vous apprendre à commencer à l’utiliser facilement. Un site statique a besoin d’une source de contenu : dans cet exemple, nous allons le délivrer grâce à une API créée avec Strapi.

\n

Qu’est-ce que Gatsby ?

\n

D’après ses créateurs, Gatsby est un \"blazing-fast website framework for React\". Il permet aux développeurs de créer des sites construits avec React en quelques minutes. Que vous vouliez développer un blog ou un site vitrine, Gatsby devrait correspondre à vos besoins.

\n
\n\"Logo\n
Logo Gatsby
\n
\n

Étant donné que Gatsby utilise React, les pages générées ne sont jamais rechargées, ce qui rend le site extrêmement rapide. De nombreux plugins sont disponibles pour permettre aux développeurs de gagner du temps et de récupérer la donnée depuis n’importe quelle source (fichiers Markdown, CMS, etc.). Gatsby est fortement basé sur le concept de la \"node\" interface, qui est le centre du système de données de Gatsby.

\n

Créé par Kyle Mathews, le projet a été officiellement publié en juillet 2017 et est d’ores et déjà utilisé par des dizaines d’entreprises.

\n

Qu’est-ce que Strapi?

\n

Strapi est le Content Management Framework le plus avancé sur la technologie Node.js. À mi-chemin entre un famework Nodejs et un Headless CMS (API-first), il permet d’économiser des semaines de développement.

\n
\n\"Logo\n
Logo Strapi
\n
\n

Grâce à son système extensible de plugin, il propose de nombreuses fonctionnalités : panel d’administration, authentification et gestion des permissions, gestion de contenu, générateur d’API, etc.

\n

Contrairement aux CMS en ligne, Strapi est 100% open-source, ce qui veut dire que :

\n\n

Installation de l’API

\n

Tout d’abord, nous allons commencer par créer une API avec Strapi et ajouter du contenu.

\n

Création du projet Strapi

\n

Installation de Strapi

\n

Prérequis: vérifiez que Node 8 (ou plus) et MongoDB sont installés et démarrés sur votre machine.

\n

Installez Strapi via npm :

\n
npm i strapi@alpha -g
\n

Note : Strapi v3 est encore en version alpha, mais cela ne posera aucun problème pour la réalisation de ce tutoriel.

\n

Création d’un projet Strapi

\n

Créez un dossier nommé gatsby-strapi-tutorial :

\n
mkdir gatsby-strapi-tutorial
\n

Générez l’API au sein de ce nouveau dossier :

\n
cd gatsby-strapi-tutorial\nstrapi new api
\n

Démarrage du serveur

\n

Entrez à l’intérieur du projet généré :

\n
cd api
\n

Démarrez le serveur Node.js :

\n
strapi start
\n

À partir de maintenant, vous devriez être à même de voir le panel d’administration de votre projet : http://localhost:1337/admin.

\n

Création du premier utilisateur

\n

Ajoutez votre premier utilisateur depuis la page d’inscription.

\n
\n\n\n\n\"Écran\n\n
Écran de création d’un utilisateur
\n
\n

Création d’un type de contenu

\n

Les API Strapi sont basées sur une structure de données appelée Content Types (équivalent des modèles dans les frameworks et des Content Types dans WordPress).

\n

Créez un Content Type nommé article contenant trois champs : title (type string), content (type text) et author (type relation: un utilisateur doit pouvoir être lié à plusieurs articles).

\n
\n\n\n\n\"Écran\n\n
Écran de définition de relation
\n
\n
\n\n\n\n\"Écran\n\n
Écran des champs d’un article
\n
\n

Ajout d’articles

\n

Ajoutez quelques articles en base de données. Pour cela, suivez les étapes suivantes :

\n
    \n
  1. Visitez la page listant les articles.
    2. \n
  2. Cliquer sur Add New Article.
    3. \n
  3. Renseignez un titre et un contenu, liez l’article à un auteur, puis valider.
    4. \n
  4. Ajouter deux autres articles.
    5. \n
\n
\n\n\n\n\"Écran\n\n
Écran listant des articles
\n
\n

Autorisation d’accès

\n

Pour des raisons de sécurité, l’accès à l’API est, par défaut, restreint.

\n

Pour autoriser l’accès, visitez la section Auth & Permissions du rôle Guest, sélectionnez l’action Article - find et sauvegardez. À partir de ce moment, vous devriez être à même de requêter la liste d’articles.

\n

L’accès à l’API des auteurs est également restreint. Autorisez l’accès aux anonymes en sélectionnant l’action Users & Permissions - find puis en sauvegardant.

\n
\n\n\n\n\"Écran\n\n
Écran du rôle Guest
\n
\n

Développement du site statique

\n

Bien joué, votre API est prête à l’utilisation ! Nous allons maintenant commencer le développement du site statique.

\n

Installation de Gatsby

\n

Commençez par installer Gatsby :

\n
npm install --global gatsby-cli
\n

Création d’un projet Gatsby

\n

Dans le dossier gatsby-strapi-tutorial que vous avez précédemment créé, générez votre tout nouveau blog :

\n
gatsby new blog
\n

Démarrage en mode développement

\n

Entrez dans le dossier du projet :

\n
cd blog
\n

Démarrez le serveur :

\n
gatsby develop
\n

À partir de ce moment, votre site Gatsby devrait être disponible à l’adresse suivante : http://localhost:8000.

\n

Installation du plugin source Strapi

\n

Lorsque l’on crée un site statique, la donnée peut venir de différentes sources : fichiers Markdown, fichiers CSV, un site WordPress (utilisant le plugin JSON REST API), etc.

\n

Gatsby l’a bien compris. C’est pourquoi ses créateurs ont décidé de construire une couche spécifique et indépendante : le Data layer. Le système entier repose sur GraphQL.

\n

Pour connecter Gatsby à une nouvelle source de données, il faut développer un \"plugin source\". Heureusement, de nombreux plugins source sont déjà disponibles. Vous devriez donc réussir à trouver celui qui correspond le mieux à vos besoins.

\n

Dans cet exemple nous utilisons Strapi. Nous allons donc évidemment avoir besoin d’un plugin source dédié au API Strapi. Bonne nouvelle : celui-ci existe déjà !

\n

Installons-le :

\n
npm install --save gatsby-source-strapi
\n

Le plugin a besoin d’être configuré. Remplacez le contenu du fichier gatsby-config.js avec :

\n

Path : gatsby-config.js

\n
module.exports = {\n  siteMetadata: {\n    title: `Gatsby Default Starter`,\n  },\n  plugins: [\n    `gatsby-plugin-react-helmet`,\n    {\n      resolve: `gatsby-source-strapi`,\n      options: {\n        apiURL: `http://localhost:1337`,\n        contentTypes: [\n          // List of the Content Types you want to be able to request from Gatsby.\n          `article`,\n          `user`,\n        ],\n      },\n    },\n  ],\n};
\n

Ensuite, redémarrez le serveur afin que Gatsby prenne en compte ces changements.

\n

Liste d’articles

\n

Dans un premier temps, nous voulons afficher la liste d’articles. Pour cela, remplacez le contenu de la page d’accueil par le suivant :

\n

Path : src/pages/index.js

\n
import React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst IndexPage = ({ data }) => (\n  <div>\n    <h1>Hi people</h1>\n    <p>Welcome to your new Gatsby site.</p>\n    <p>Now go build something great.</p>\n    <ul>\n      {data.allStrapiArticle.edges.map((document) => (\n        <li key={document.node.id}>\n          <h2>\n            <Link to={`/${document.node.id}`}>{document.node.title}</Link>\n          </h2>\n          <p>{document.node.content}</p>\n        </li>\n      ))}\n    </ul>\n    <Link to=\"/page-2/\">Go to page 2</Link>\n  </div>\n);\n\nexport default IndexPage;\n\nexport const pageQuery = graphql`\n  query IndexQuery {\n    allStrapiArticle {\n      edges {\n        node {\n          id\n          title\n          content\n        }\n      }\n    }\n  }\n`;
\n

Que venons-nous de faire ?

\n

À la fin du fichier nous exportons pageQuery : une requête GraphQL qui requête la liste entière des articles. Comme vous pouvez le voir, nous requêtons uniquement les champs id, title et content grâce à la précision du langage GraphQL.

\n

Ensuite, nous passons l’objet déstructuré { data } comme paramètre de IndexPage et nous bouclons sur son objet allStrapiArticles afin d’afficher la donnée.

\n
\n\n\n\n\"Exemple\n\n
Exemple d’écran d’accueil
\n
\n

Astuce : générez vos requêtes GraphQL en quelques secondes !

\n

Gatsby inclut l’excellente interface GraphiQL. Cela facilite grandement la création de requêtes GraphQL. Jetez-y un œil et tentez de créer quelques requêtes.

\n

Vue article

\n

Notre site commence à ressembler à un blog. C’est une bonne nouvelle ! Cependant, une partie importante est encore manquante : la page article.

\n

Commençons par créer le template contenant la requête GraphQL et définissant le contenu affiché :

\n

Path : src/templates/article.js

\n
import React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst ArticleTemplate = ({ data }) => (\n  <div>\n    <h1>{data.strapiArticle.title}</h1>\n    <p>\n      by{\" \"}\n      <Link to={`/authors/${data.strapiArticle.author.id}`}>\n        {data.strapiArticle.author.username}\n      </Link>\n    </p>\n    <p>{data.strapiArticle.content}</p>\n  </div>\n);\n\nexport default ArticleTemplate;\n\nexport const query = graphql`\n  query ArticleTemplate($id: String!) {\n    strapiArticle(id: { eq: $id }) {\n      title\n      content\n      author {\n        id\n        username\n      }\n    }\n  }\n`;
\n

Tout semble prêt, mais en réalité, Gatsby ne sait pas quand ce template devrait être affiché. Chaque article a besoin d’une URL. Nous allons donc informer Gatsby des nouvelles URLs que nous souhaitons, grâce à la fonction createPage.

\n

Tout d’abord, nous allons déclarer une nouvelle fonction nommée makeRequest afin d’exécuter la requête GraphQL. Ensuite, nous exportons une fonction nommée createPages dans laquelle nous récupérons la liste d’articles et créons une page pour chacun d’entre eux. Voici le résultat :

\n

Path : gatsby-node.js

\n
const path = require(`path`);\n\nconst makeRequest = (graphql, request) =>\n  new Promise((resolve, reject) => {\n    // Query for nodes to use in creating pages.\n    resolve(\n      graphql(request).then((result) => {\n        if (result.errors) {\n          reject(result.errors);\n        }\n\n        return result;\n      })\n    );\n  });\n\n// Implement the Gatsby API “createPages”. This is called once the\n// data layer is bootstrapped to let plugins create pages from data.\nexports.createPages = ({ boundActionCreators, graphql }) => {\n  const { createPage } = boundActionCreators;\n\n  const getArticles = makeRequest(\n    graphql,\n    `\n    {\n      allStrapiArticle {\n        edges {\n          node {\n            id\n          }\n        }\n      }\n    }\n    `\n  ).then((result) => {\n    // Create pages for each article.\n    result.data.allStrapiArticle.edges.forEach(({ node }) => {\n      createPage({\n        path: `/${node.id}`,\n        component: path.resolve(`src/templates/article.js`),\n        context: {\n          id: node.id,\n        },\n      });\n    });\n  });\n\n  // Query for articles nodes to use in creating pages.\n  return getArticles;\n};
\n

Redémarrez le serveur Gatsby.

\n

À partir de maintenant, vous devriez pouvoir visiter les pages de chaque article en cliquant sur les liens affichés sur la page d’accueil.

\n
\n\n\n\n\"Exemple\n\n
Exemple de page
\n
\n

Vue auteur

\n

Les articles sont rédigés par des auteurs. Eux-aussi méritent une page dédiée.

\n

La création de la page auteur est très similaire à celle de la page article. Premièrement, nous créons le template :

\n

Path : src/templates/user.js

\n
import React from \"react\";\nimport Link from \"gatsby-link\";\n\nconst UserTemplate = ({ data }) => (\n  <div>\n    <h1>{data.strapiUser.username}</h1>\n    <ul>\n      {data.strapiUser.articles.map((article) => (\n        <li key={article.id}>\n          <h2>\n            <Link to={`/${article.id}`}>{article.title}</Link>\n          </h2>\n          <p>{article.content}</p>\n        </li>\n      ))}\n    </ul>\n  </div>\n);\n\nexport default UserTemplate;\n\nexport const query = graphql`\n  query UserTemplate($id: String!) {\n    strapiUser(id: { eq: $id }) {\n      id\n      username\n      articles {\n        id\n        title\n        content\n      }\n    }\n  }\n`;
\n

Ensuite, nous mettons à jour le fichier gatsby-node.js pour créer les URLs :

\n

Path : gatsby-node.js

\n
const path = require(`path`);\n\nconst makeRequest = (graphql, request) =>\n  new Promise((resolve, reject) => {\n    // Query for article nodes to use in creating pages.\n    resolve(\n      graphql(request).then((result) => {\n        if (result.errors) {\n          reject(result.errors);\n        }\n\n        return result;\n      })\n    );\n  });\n\n// Implement the Gatsby API “createPages”. This is called once the\n// data layer is bootstrapped to let plugins create pages from data.\nexports.createPages = ({ boundActionCreators, graphql }) => {\n  const { createPage } = boundActionCreators;\n\n  const getArticles = makeRequest(\n    graphql,\n    `\n    {\n      allStrapiArticle {\n        edges {\n          node {\n            id\n          }\n        }\n      }\n    }\n    `\n  ).then((result) => {\n    // Create pages for each article.\n    result.data.allStrapiArticle.edges.forEach(({ node }) => {\n      createPage({\n        path: `/${node.id}`,\n        component: path.resolve(`src/templates/article.js`),\n        context: {\n          id: node.id,\n        },\n      });\n    });\n  });\n\n  const getAuthors = makeRequest(\n    graphql,\n    `\n    {\n      allStrapiUser {\n        edges {\n          node {\n            id\n          }\n        }\n      }\n    }\n    `\n  ).then((result) => {\n    // Create pages for each user.\n    result.data.allStrapiUser.edges.forEach(({ node }) => {\n      createPage({\n        path: `/authors/${node.id}`,\n        component: path.resolve(`src/templates/user.js`),\n        context: {\n          id: node.id,\n        },\n      });\n    });\n  });\n\n  // Queries for articles and authors nodes to use in creating pages.\n  return Promise.all([getArticles, getAuthors]);\n};
\n

Dernière étape : redémarrez le serveur et visitez la page auteur depuis la page d’un article.

\n
\n\n\n\n\"Exemple\n\n
Exemple de page
\n
\n

Conclusion

\n

Félicitations ! Vous avez créé un blog super rapide et facile à maintenir !

\n

Étant donné que le contenu est géré dans Strapi, les auteurs peuvent écrire leurs articles depuis une vraie interface et vous, en tant que développeur, n’avez qu’à recompiler le site pour mettre à jour le contenu.

\n

Que faire ensuite ?

\n

N’hésitez pas à continuer le projet pour découvrir plus en profondeur les avantages de Gatsby et de Strapi. Voici une liste de fonctionnalités que vous pourriez ajouter à votre projet : liste des auteurs, catégories d’articles, système de commentaire avec l’API Strapi ou Disqus, etc. Vous pouvez aussi créer tout type de site (boutique e-commerce, site vitrine, etc.).

\n

Lorsque votre projet sera terminé, vous voudrez probablement le déployer. Le site statique généré par Gatsby peut facilement être publiée sur des services de stockage tels que Netlify, S3/Cloudfront, GitHub pages, GitLab, Heroku, etc. L’API Strapi n’est rien d’autre qu’une application Node.js. Elle peut donc être mise en ligne sur Heroku ou sur n’importe quelle instance Linux ayant Node.js installé dessus.

\n

Le code source de ce tutoriel est disponible sur GitHub. Pour le tester, clonez-le repository et suivez les instructions présentes dans le Readme.

\n

Nous espérons que vous avez apprécié ce tutoriel. N’hésitez pas à le commenter, le partager, et indiquer quelle est votre manière favorite de créer des sites avec React et d’en gérer le contenu.

", "authors": [ { "name": "pierre" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/04/06/comparatif-hugo-jekyll/", "url": "https://jamstatic.fr/2018/04/06/comparatif-hugo-jekyll/", "title": "Hugo ou Jekyll ? Six critères de comparaison", "summary": "Jekyll et Hugo sont parmi les générateurs de site statiques les plus populaires. Quel est celui qu'il vous faut ?", "date_published": "2018-04-06T18:10:03+00:00","content_text": "\nChoisir les bons outils pour bâtir un site web n'est pas chose aisée de nos jours. Il y a tellement d’options ! Générer un site statique est une de ces options, qui comporte son lot d’avantages comme une sécurité de premier plan, une performance de feu et une réduction des coûts d’hébergement.\nQuand il est question de générer des sites statiques, les deux solutions qui dominent actuellement le marché sont Jekyll et Hugo. La vraie question est de savoir quel est celui qui est le mieux pour vous ?\nPour répondre à cette question, nous allons examiner ensemble les fonctionnalités, la rapidité et l’extensibilité de chacun d’entre eux, peser les avantages et les inconvénients de ces deux générateurs. Après avoir lu cet article, vous saurez clairement lequel des deux est le bon pour démarrer votre projet.\nVersion courte : Jekyll est un générateur de site statique flexible et parfait pour débuter. Hugo a une courbe d’apprentissage un peu plus élevée, mais il est très rapide et intègre plein de fonctionnalités. Lisez la suite pour en apprendre plus sur les différences entre ces deux outils._\nJekyll\nCréé par Tom Preston-Werner, le fondateur de GitHub, Jekyll est à l’origine de la mouvance des sites statiques à laquelle nous assistons actuellement.\nCommencé en 2008, Jekyll est présenté comme un \"générateur de site statique simple, prêt-à-bloguer\".\nC’est le GSS (générateur de site statique) le plus populaire à l’heure actuelle avec plus de 33 000 étoiles sur GitHub ce qui est largement dû à son intégration dans GitHub Pages.\nLa valeur ajoutée de Jekyll c'est qu'il vous permet de prendre le HTML statique de n'importe quel site web et de le transformer rapidement en site statique fonctionnel grâce à Liquid, un langage simple utilisé pour définir les gabarits de page.\nInstallation\nInstaller Jekyll n'est pas une mince affaire, surtout sous Windows.\nJekyll est développé en Ruby et demande donc d’avoir une version récente de Ruby installé sur votre machine.\nCe n'est pas si terrible que ça, mais ce n'est pas aussi simple que de télécharger une application. Heureusement le procédé d’installation de Jekyll est bien documenté.\nContenu\nDans Jekyll, tout votre contenu est stocké dans des fichiers texte plutôt que dans une base de données. Vous pouvez donc manipuler votre modèle de contenu simplement en ouvrant des fichiers dans votre éditeur de texte favori.\nLa forme de contenu la plus simple dans Jekyll est stocké à la racine de votre projet sous forme de fichiers au format Markdown ou HTML. Ces fichiers de contenus sont traités pendant l’étape de génération, durant laquelle un fichier HTML correspondant est généré à partir des gabarits de votre thème.\nDes champs Front Matter peuvent être ajoutés à ces fichiers, ils vous permettent de définir les données qui peuvent être utilisées dans vos gabarits.\n---\ntitle: Accueil\ndate: 2017-01-30\ntags: [bonjour, monde]\n---\n## Bonjour monde\nC’est le contenu de ma page !\nJekyll supporte les contenus chronologiques (comme des articles de blog) qui sont stockés dans le dossier _posts et qui respectent la nomenclature yyyy-mm-dd-titre-de-l-article.md.\nJekyll supporte aussi le chargement de données modelées à partir de fichiers YAML, JSON ou CSV situés dans le répertoire _data. Ces données sont accessibles dans vos gabarits à l’aide de {{ site.data }}.\nThèmes et gabarits\nJekyll possède une large communauté et un choix de thèmes gratuits ou payants prêts à l’emploi.\nLes thèmes s'installent facilement, soit en les téléchargeant et en les ajoutant à votre projet Jekyll, soit en les installant comme une gem Ruby.\nLes thèmes pour Jekyll sont développés à l’aide du moteur de templating Liquid de Shopify. Liquid est un moteur de templating sécurisé conçu pour faire tourner du code tiers sur leurs serveurs. Liquid est conçu pour vous aider à faire ce que vous voulez sans qu'il y ait besoin d’ajouter de code Ruby natif.\n<div class=“container”>\n{% for post in site.posts %}\n <div class=\"article\">\n <h2>{{ post.title }}<\/h2>\n <p>{{ post.content }}<\/p>\n {% for tag in post.tags %}\n <span>{{ tag }}<\/span>\n {% endfor %}\n <\/div>\n{% endfor %}\n<\/div>\nC’est génial pour les débutants et les développeurs qui veulent créer des modèles fonctionnels, propres et simples.\nToutefois, cela signifie que vous aurez à étendre les possibilités à l’aide d’extensions personnalisées en Liquid via des plugins Jekyll si vous souhaitez ajouter des fonctionnalités supplémentaires.\nPour les développeurs issus du monde des CMS traditionnels comme WordPress, Liquid devrait être facile à prendre en main.\nWorkflow de développement\nDévelopper avec Jekyll, c'est vraiment génial comparé au développement avec des CMS traditionnels propulsés par une base de données.\nJekyll intègre un serveur de développement, qu'on peut lancer avec la commande bundle exec jekyll serve.\nVous pouvez ainsi accéder à votre site statique généré sur une adresse IP locale et voir les changements apportés à votre contenu et à vos modèles.\nGestion des assets\nJekyll fournit aussi une gestion intégrée des assets très basique, elle compile les fichiers Sass et CoffeeScript.\nTous les fichiers .scss, .sass ou .coffee qui possèdent des délimiteurs Front Matter seront traités par Jekyll et transformés en fichiers .css et .js.\n---\n---\nalert \"Hello world!\"\nLe fait de devoir ajouter du Front Matter à chaque fichier fait que beaucoup de sites importants qui tournent en production sous Jekyll, optent pour des outils de génération plus modernes comme Gulp ou Webpack.\nCes outils vous donnent plus de contrôle sur vos fichiers CSS, JS, vos images et votre HTML et permettent la minification et l’optimisation. Ces outils vous donnent aussi accès à BrowerSync ou LiveReload, qui facilitent le développement[^livereload].\nFonctionnalités utiles\nLe cœur de Jekyll propose des fonctionnalités minimales[^core] et n'intègre pas une bonne partie des choses qu'on pourrait attendre d’un site web moderne comme:\n\nla gestion des menus,\nla génération de sitemap XML[^core-plugin],\nla génération d’un flux RSS\/Atom[^core-plugin],\nla gestion des scripts Analytics,\nla gestion des commentaires,\nla gestion multilingue\/i18n,\net bien plus…\n\nPour cela il faudra utiliser des plugins Jekyll tiers, qui sont de cinq types :\n\nles générateurs, qui permettent de compléter et de modifier le processus de génération de Jekyll,\nles convertisseurs, qui permettent d’ajouter le support de nouveaux formats de fichiers,\nles commandes, qui permettent d’étendre les options de la ligne de commande de Jekyll,\nles tags, qui permettent d’ajouter de nouvelles balises Liquid,\nles filtres, qui permettent de modifier le rendu des balises Liquid et des variables.\n\nPar exemple, Forestry a dévelopé le plugin jekyll-menus qui permet de gérer les menus dans le CMS Forestry.\nUne autre fonctionnalité bien pratique de Jekyll est l’import de contenus depuis WordPress. Avec 30% de l’Internet enfermé dans WordPress, il est bon de savoir que de migrer vers une stack moderne est aisé.\nPerformance\nForestry a déjà publié un comparatif des performances de Jekyll et Hugo.\nLes résultats des tests montrent que Jekyll est bien plus lent qu'Hugo, qui s'avère 35 fois plus rapide en moyenne. Pour les sites de taille modeste, la différence n'est pas gênante, mais à force cela peut faire une grande différence.\nJekyll met dans la majorité de ces tests entre 1,4 et 6 secondes. Imaginez que vous ayez une équipe qui fasse une centaine de modifications par semaine sur votre site, votre blog ou votre documentation…\nCela représente potentiellement plus de 10 heures de perdues lors de la génération chaque année !\nJekyll en résumé\nMaintenant que nous avons passé en revue les fonctionnalités de base de Jekyll, prenons un peu de recul et examinons d’un œil externe ce générateur de site statique en pesant les pour et les contre.\nPour :\n\nUn moteur de gabarits simple. Les gabarits de page de Jekyll sont très semblables à la syntaxe qu'on trouve dans WordPress ou Craft.\nUn large choix de thèmes. Il existe plein de thèmes prêt à l’emploi pour Jekyll.\nUn large choix de plugins. Il existe des dizaines de plugins pour ajouter les fonctionnalités dont vous avez besoin.\nIntégration dans GitHub Pages. Installer un site avec Jekyll et GitHub Pages est un jeu d’enfant.\n\nContre :\n\nUne génération lente. Si vous développez un petit site, ce n'est pas un problème. Mais les sites plus importants pourraient voir les temps de génération augmenter.\nUn manque de fonctionnalités natives. Les fonctionnalités de premier ordre sont mieux supportées et intégrées. Ce point fait défaut à Jekyll.[^plugins]\n\nVous pouvez consulter le guide de Forestry pour développer avec Jekyll pour apprendre à développer un site avec Jekyll et le connecter au CMS Forestry.\nHugo\nHugo est le générateur de site statique créé1 par Steve Francia, un des principaux contributeurs au langage de programmation Go de Google. Hugo est bien entendu développé en Go !\nApparu en 2013, Hugo est rapidement devenu le deuxième GSS le plus populaire derrière Jekyll et compte à ce jour plus de 24 000 étoiles sur GitHub.\nHugo possède un avantage énorme sur tous les autres GSS. Il est rapide.\nIl possède aussi une des communautés les plus (si ce n'est la plus) actives pour un GSS.\nInstallation\nInstaller Hugo est plus simple que d’installer Jekyll, que vous utilisiez Windows ou un système basé sur UNIX.\nVu qu'Hugo est développé un Go – un langage compilé – installer ou mettre à jour Hugo consiste simplement à télécharger un fichier binaire et dire à votre système de l’utiliser.\nHugo propose une documentation détaillée pour faire cela.\nContenu\nTout comme Jekyll, tous les contenus de votre projet sont stockés dans des fichiers textes.\nDans Hugo, dans les contenus destinés à être générés sont stockés dans le dossier content de votre projet. Vous pouvez utiliser différents formats : Markdown, Mark, et HTML sont supportés par défaut, et il existe des extensions tierces pour supporter Asciidoc and reStructuredText2.\nHugo supporte aussi TOML, YAML, et JSON pour le Front Matter, alors que Jekyll ne supporte que le YAML.\n+++\ntitle = \"Accueil\"\ndate = \"2017-01-30\"\ntags = [\"bonjour\", \"monde\"]\n+++\n## Bonjour Monde\nCeci est un exemple de Front Matter en TOML\nHugo supporte également les données externes, qui peuvent être stockées dans le répertoire \/data de votre projet ou bien récupérées depuis des sources de tierce-partie comme des APIs REST. Les formats supportés pour les sources sont JSON et CSV.\nThèmes & gabarits\nMême si Hugo n'a que 4 ans, de nombreux thèmes sont déjà disponibles pour ce GSS en forte croissance.\nSi vous utilisez la ligne de commande, installer des thèmes depuis le dépôt des thèmes d’Hugo est assez simple.\nHugo utilise le package de template de Go par défaut. Tout comme avec Liquid, il est possible d’ajouter un peu logique dans vos gabarits.\n<div class=“container”>\n{{ range .Site.Pages}\n <div class=\"article\">\n <h2>{{ .Title }}<\/h2>\n <p>{{ .Content }}<\/p>\n {{ range .Tags }}\n <span>{{ . }}<\/span>\n {{ end }}\n <\/div>\n{{ end }}\n<\/div>\nUne fois de plus, c'est très bien pour les débutants mais vous allez devoir étendre les possibilités du moteur de template à l’aide de shortcodes pour ajouter des fonctionnalités supplémentaires.\nMalheureusement la syntaxe du package de template de Go n'est pas aussi évidente pour les débutants que celle de Liquid et ne semblera pas aussi familière à première vue.\nToutefois, Hugo propose aussi le support des deux moteurs de template Amber et Ace. Ces deux langages pourront sembler plus familiers aux développeurs issus des CMS traditionnels comme WordPress.\nWorkflow de développement\nIl est plus agréable de développer avec Hugo qu'avec Jekyll, car la génération est quasi-instantanée et le serveur LiveReload est actif par défaut.\nDans le dossier de votre projet, lancez la commande hugo serve pour lancer le serveur de développement.\nCela vous permet d’accéder à votre site sur une adresse IP locale. Chaque changement effectué dans votre projet, déclenche une génération et recharge automatiquement le site dans votre navigateur.\nGestion des assets\nJusqu'à la version 0.43, Hugo ne procèdait à aucune transformation de vos assets (CSS, JS, SVG, etc.), il se contentait de recopier tous les fichiers qui se trouvent dans le répertoire \/static de votre projet. Maintenant vous n'avez plus besoin d'externaliser votre processus de génération à Webpack ou Gulp pour compiler vos fichiers Sass ou minifier vos CSS et votre JS.\nFonctionnalités utiles\nHugo brille par la multitude de fonctionnalités puissantes qu'il intègre par défaut comparativement à Jekyll et à d’autres GSS.\nAvec le support par défaut des menus, des flux ou des sitemaps, la configuration d’un site web pour la production est un jeu d’enfant.\nMais Hugo brille encore plus quand vous travaillez sur un site avec beaucoup de contenus, comme un journal, un site gouvernemental ou un site de documentation.\nPar exemple avec la fonctionnalité d’exports personnalisés, vous pouvez générer en même temps : votre site statique, sa version alternative pour Google AMP, ainsi que des fichiers JSON prêts à être consommés par une application mobile.\nParmi les fonctionnalités bien pratiques d’Hugo on peut citer :\n\nLa gestion des menus,\nLa génération de Sitemap XML,\nLa génération de flux RSS\/Atom,\nL'intégration d’Analytics (via Google Analytics)\nL'intégration de commentaires (via Disqus)\nLa gestion du multilingue\/i18n\nLes formats d’export personnalisés\n\nEnvie de passer à Hugo, mais encore sous Jekyll ?\nHugo peut importer votre site Jekyll en ligne de commande !\nPerformance\nHugo est extrêmement rapide. Forestry a publié un article sur la performance de Hugo et de Jekyll et a comparé les deux. Hugo est sorti vainqueur haut la main.\nRendez-vous compte, lors de ces tests Hugo a généré les sites en moyenne 35 fois plus vite que Jekyll, la génération de la plupart de ces sites a pris moins d’une seconde.\nLors d’un test, @darinpope un utilisateur d’Hugo a réussi à générer 600 000 pages en moins de 5 minutes !.\nHugo en résumé\nMaintenant que nous avons passé en revue les fonctionnalités natives d’Hugo, prenons un peu de recul et jetons un regard externe sur ce générateur de site statique en pesant le pour et le contre.\nPour :\n\nExtrêmement rapide. Des temps de génération de l’ordre de la seconde.\nExtrêmement versatile. Plein de fonctionnalités par défaut pour des sites web d’entreprises.\nParé pour l’entreprise Avec le support des exports multiples et des sites multilingues, vous êtes opérationnel !\nUne communauté florissante. Il est facile d’avoir de l’aide. Posez une question sur le forum et vous aurez une réponse.\n\nContre :\n\nPas d’extensions. Hugo ne prend pas les plugins en charge, il n'est donc pas possible d’ajouter des fonctionnalités personnalisées.\nUne syntaxe de gabarit compliquée. Bien que le moteur de gabarits d’Hugo soit versatile, il est assez peu intuitif et compliqué pour les débutants.\n\nReportez-vous au guide de Forestry pour développer avec Hugo pour apprendre comment développer un site avec Hugo et le connecter au CMS Forestry.\nEn résumé\nNous avons passé en revue les fonctionnalités de base de Jekyll et Hugo, en soulignant la facilité d’installation, la gestion de contenu, les langages de gabarits de page, les workflows de développement, les fonctionnalités offertes et la performance.\nCes deux générateurs sont les leaders dans leur domaine, et il y a plein d’exemples de gros projets qui les utilisent comme healthcare.gov, développé avec Jekyll, et le nouveau site de Smashing Magazine développé avec Hugo.\nMaintenant c'est l’heure de faire votre choix ! Voici un petit récapitulatif pour vous aider :\n\nJekyll est un excellent choix, si vous êtes familier avec l’écosystème de Ruby ou si vous êtes débutant, grâce à son moteur de templating très simple et à ses nombreux plugins.\nHugo est génial pour les sites web avec beaucoup de contenus. Il comble son manque d’extensibilité par un lot de fonctionnalités embarquées et une vitesse inégalée par aucun autre générateur de site statique.\n\n\n\n\n\nHugo a été depuis principalement développé par Bjørn Erik Pedersen. ↩\n\n\nNdT: à l’heure actuelle comme ces extensions ne reposent pas sur des librairies natives en Go, vous perdrez donc le gain de performance apporté par Hugo. ↩\n\n\n", "content_html": "

\n

Choisir les bons outils pour bâtir un site web n'est pas chose aisée de nos jours. Il y a tellement d’options ! Générer un site statique est une de ces options, qui comporte son lot d’avantages comme une sécurité de premier plan, une performance de feu et une réduction des coûts d’hébergement.

\n

Quand il est question de générer des sites statiques, les deux solutions qui dominent actuellement le marché sont Jekyll et Hugo. La vraie question est de savoir quel est celui qui est le mieux pour vous ?

\n

Pour répondre à cette question, nous allons examiner ensemble les fonctionnalités, la rapidité et l’extensibilité de chacun d’entre eux, peser les avantages et les inconvénients de ces deux générateurs. Après avoir lu cet article, vous saurez clairement lequel des deux est le bon pour démarrer votre projet.

\n

Version courte : Jekyll est un générateur de site statique flexible et parfait pour débuter. Hugo a une courbe d’apprentissage un peu plus élevée, mais il est très rapide et intègre plein de fonctionnalités. Lisez la suite pour en apprendre plus sur les différences entre ces deux outils._

\n

Jekyll

\n

Créé par Tom Preston-Werner, le fondateur de GitHub, Jekyll est à l’origine de la mouvance des sites statiques à laquelle nous assistons actuellement.

\n

Commencé en 2008, Jekyll est présenté comme un \"générateur de site statique simple, prêt-à-bloguer\".

\n

C’est le GSS (générateur de site statique) le plus populaire à l’heure actuelle avec plus de 33 000 étoiles sur GitHub ce qui est largement dû à son intégration dans GitHub Pages.

\n

La valeur ajoutée de Jekyll c'est qu'il vous permet de prendre le HTML statique de n'importe quel site web et de le transformer rapidement en site statique fonctionnel grâce à Liquid, un langage simple utilisé pour définir les gabarits de page.

\n

Installation

\n

Installer Jekyll n'est pas une mince affaire, surtout sous Windows.

\n

Jekyll est développé en Ruby et demande donc d’avoir une version récente de Ruby installé sur votre machine.

\n

Ce n'est pas si terrible que ça, mais ce n'est pas aussi simple que de télécharger une application. Heureusement le procédé d’installation de Jekyll est bien documenté.

\n

Contenu

\n

Dans Jekyll, tout votre contenu est stocké dans des fichiers texte plutôt que dans une base de données. Vous pouvez donc manipuler votre modèle de contenu simplement en ouvrant des fichiers dans votre éditeur de texte favori.

\n

La forme de contenu la plus simple dans Jekyll est stocké à la racine de votre projet sous forme de fichiers au format Markdown ou HTML. Ces fichiers de contenus sont traités pendant l’étape de génération, durant laquelle un fichier HTML correspondant est généré à partir des gabarits de votre thème.

\n

Des champs Front Matter peuvent être ajoutés à ces fichiers, ils vous permettent de définir les données qui peuvent être utilisées dans vos gabarits.

\n
---\ntitle: Accueil\ndate: 2017-01-30\ntags: [bonjour, monde]\n---\n## Bonjour monde\nC’est le contenu de ma page !
\n

Jekyll supporte les contenus chronologiques (comme des articles de blog) qui sont stockés dans le dossier _posts et qui respectent la nomenclature yyyy-mm-dd-titre-de-l-article.md.

\n

Jekyll supporte aussi le chargement de données modelées à partir de fichiers YAML, JSON ou CSV situés dans le répertoire _data. Ces données sont accessibles dans vos gabarits à l’aide de {{ site.data }}.

\n

Thèmes et gabarits

\n

Jekyll possède une large communauté et un choix de thèmes gratuits ou payants prêts à l’emploi.

\n

Les thèmes s'installent facilement, soit en les téléchargeant et en les ajoutant à votre projet Jekyll, soit en les installant comme une gem Ruby.

\n

Les thèmes pour Jekyll sont développés à l’aide du moteur de templating Liquid de Shopify. Liquid est un moteur de templating sécurisé conçu pour faire tourner du code tiers sur leurs serveurs. Liquid est conçu pour vous aider à faire ce que vous voulez sans qu'il y ait besoin d’ajouter de code Ruby natif.

\n
<div class=“container”>\n{% for post in site.posts %}\n    <div class=\"article\">\n    <h2>{{ post.title }}</h2>\n    <p>{{ post.content }}</p>\n    {% for tag in post.tags %}\n        <span>{{ tag }}</span>\n    {% endfor %}\n    </div>\n{% endfor %}\n</div>
\n

C’est génial pour les débutants et les développeurs qui veulent créer des modèles fonctionnels, propres et simples.

\n

Toutefois, cela signifie que vous aurez à étendre les possibilités à l’aide d’extensions personnalisées en Liquid via des plugins Jekyll si vous souhaitez ajouter des fonctionnalités supplémentaires.

\n

Pour les développeurs issus du monde des CMS traditionnels comme WordPress, Liquid devrait être facile à prendre en main.

\n

Workflow de développement

\n

Développer avec Jekyll, c'est vraiment génial comparé au développement avec des CMS traditionnels propulsés par une base de données.

\n

Jekyll intègre un serveur de développement, qu'on peut lancer avec la commande bundle exec jekyll serve.

\n

Vous pouvez ainsi accéder à votre site statique généré sur une adresse IP locale et voir les changements apportés à votre contenu et à vos modèles.

\n

Gestion des assets

\n

Jekyll fournit aussi une gestion intégrée des assets très basique, elle compile les fichiers Sass et CoffeeScript.

\n

Tous les fichiers .scss, .sass ou .coffee qui possèdent des délimiteurs Front Matter seront traités par Jekyll et transformés en fichiers .css et .js.

\n
---\n---\nalert \"Hello world!\"
\n

Le fait de devoir ajouter du Front Matter à chaque fichier fait que beaucoup de sites importants qui tournent en production sous Jekyll, optent pour des outils de génération plus modernes comme Gulp ou Webpack.

\n

Ces outils vous donnent plus de contrôle sur vos fichiers CSS, JS, vos images et votre HTML et permettent la minification et l’optimisation. Ces outils vous donnent aussi accès à BrowerSync ou LiveReload, qui facilitent le développement[^livereload].

\n

Fonctionnalités utiles

\n

Le cœur de Jekyll propose des fonctionnalités minimales[^core] et n'intègre pas une bonne partie des choses qu'on pourrait attendre d’un site web moderne comme:

\n\n

Pour cela il faudra utiliser des plugins Jekyll tiers, qui sont de cinq types :

\n\n

Par exemple, Forestry a dévelopé le plugin jekyll-menus qui permet de gérer les menus dans le CMS Forestry.

\n

Une autre fonctionnalité bien pratique de Jekyll est l’import de contenus depuis WordPress. Avec 30% de l’Internet enfermé dans WordPress, il est bon de savoir que de migrer vers une stack moderne est aisé.

\n

Performance

\n

Forestry a déjà publié un comparatif des performances de Jekyll et Hugo.

\n

Les résultats des tests montrent que Jekyll est bien plus lent qu'Hugo, qui s'avère 35 fois plus rapide en moyenne. Pour les sites de taille modeste, la différence n'est pas gênante, mais à force cela peut faire une grande différence.

\n

Jekyll met dans la majorité de ces tests entre 1,4 et 6 secondes. Imaginez que vous ayez une équipe qui fasse une centaine de modifications par semaine sur votre site, votre blog ou votre documentation…

\n

Cela représente potentiellement plus de 10 heures de perdues lors de la génération chaque année !

\n

Jekyll en résumé

\n

Maintenant que nous avons passé en revue les fonctionnalités de base de Jekyll, prenons un peu de recul et examinons d’un œil externe ce générateur de site statique en pesant les pour et les contre.

\n

Pour :

\n\n

Contre :

\n\n\n

Hugo

\n

Hugo est le générateur de site statique créé1 par Steve Francia, un des principaux contributeurs au langage de programmation Go de Google. Hugo est bien entendu développé en Go !

\n

Apparu en 2013, Hugo est rapidement devenu le deuxième GSS le plus populaire derrière Jekyll et compte à ce jour plus de 24 000 étoiles sur GitHub.

\n

Hugo possède un avantage énorme sur tous les autres GSS. Il est rapide.

\n

Il possède aussi une des communautés les plus (si ce n'est la plus) actives pour un GSS.

\n

Installation

\n

Installer Hugo est plus simple que d’installer Jekyll, que vous utilisiez Windows ou un système basé sur UNIX.

\n

Vu qu'Hugo est développé un Go – un langage compilé – installer ou mettre à jour Hugo consiste simplement à télécharger un fichier binaire et dire à votre système de l’utiliser.

\n

Hugo propose une documentation détaillée pour faire cela.

\n

Contenu

\n

Tout comme Jekyll, tous les contenus de votre projet sont stockés dans des fichiers textes.

\n

Dans Hugo, dans les contenus destinés à être générés sont stockés dans le dossier content de votre projet. Vous pouvez utiliser différents formats : Markdown, Mark, et HTML sont supportés par défaut, et il existe des extensions tierces pour supporter Asciidoc and reStructuredText2.

\n

Hugo supporte aussi TOML, YAML, et JSON pour le Front Matter, alors que Jekyll ne supporte que le YAML.

\n
+++\ntitle = \"Accueil\"\ndate = \"2017-01-30\"\ntags = [\"bonjour\", \"monde\"]\n+++\n## Bonjour Monde\nCeci est un exemple de Front Matter en TOML
\n

Hugo supporte également les données externes, qui peuvent être stockées dans le répertoire /data de votre projet ou bien récupérées depuis des sources de tierce-partie comme des APIs REST. Les formats supportés pour les sources sont JSON et CSV.

\n

Thèmes & gabarits

\n

Même si Hugo n'a que 4 ans, de nombreux thèmes sont déjà disponibles pour ce GSS en forte croissance.

\n

Si vous utilisez la ligne de commande, installer des thèmes depuis le dépôt des thèmes d’Hugo est assez simple.

\n

Hugo utilise le package de template de Go par défaut. Tout comme avec Liquid, il est possible d’ajouter un peu logique dans vos gabarits.

\n
<div class=“container”>\n{{ range .Site.Pages}\n    <div class=\"article\">\n    <h2>{{ .Title }}</h2>\n    <p>{{ .Content }}</p>\n    {{ range .Tags }}\n        <span>{{ . }}</span>\n    {{ end }}\n    </div>\n{{ end }}\n</div>
\n

Une fois de plus, c'est très bien pour les débutants mais vous allez devoir étendre les possibilités du moteur de template à l’aide de shortcodes pour ajouter des fonctionnalités supplémentaires.

\n

Malheureusement la syntaxe du package de template de Go n'est pas aussi évidente pour les débutants que celle de Liquid et ne semblera pas aussi familière à première vue.

\n

Toutefois, Hugo propose aussi le support des deux moteurs de template Amber et Ace. Ces deux langages pourront sembler plus familiers aux développeurs issus des CMS traditionnels comme WordPress.

\n

Workflow de développement

\n

Il est plus agréable de développer avec Hugo qu'avec Jekyll, car la génération est quasi-instantanée et le serveur LiveReload est actif par défaut.

\n

Dans le dossier de votre projet, lancez la commande hugo serve pour lancer le serveur de développement.

\n

Cela vous permet d’accéder à votre site sur une adresse IP locale. Chaque changement effectué dans votre projet, déclenche une génération et recharge automatiquement le site dans votre navigateur.

\n

Gestion des assets

\n

Jusqu'à la version 0.43, Hugo ne procèdait à aucune transformation de vos assets (CSS, JS, SVG, etc.), il se contentait de recopier tous les fichiers qui se trouvent dans le répertoire /static de votre projet. Maintenant vous n'avez plus besoin d'externaliser votre processus de génération à Webpack ou Gulp pour compiler vos fichiers Sass ou minifier vos CSS et votre JS.

\n

Fonctionnalités utiles

\n

Hugo brille par la multitude de fonctionnalités puissantes qu'il intègre par défaut comparativement à Jekyll et à d’autres GSS.

\n

Avec le support par défaut des menus, des flux ou des sitemaps, la configuration d’un site web pour la production est un jeu d’enfant.

\n

Mais Hugo brille encore plus quand vous travaillez sur un site avec beaucoup de contenus, comme un journal, un site gouvernemental ou un site de documentation.

\n

Par exemple avec la fonctionnalité d’exports personnalisés, vous pouvez générer en même temps : votre site statique, sa version alternative pour Google AMP, ainsi que des fichiers JSON prêts à être consommés par une application mobile.

\n

Parmi les fonctionnalités bien pratiques d’Hugo on peut citer :

\n\n\n

Performance

\n

Hugo est extrêmement rapide. Forestry a publié un article sur la performance de Hugo et de Jekyll et a comparé les deux. Hugo est sorti vainqueur haut la main.

\n

Rendez-vous compte, lors de ces tests Hugo a généré les sites en moyenne 35 fois plus vite que Jekyll, la génération de la plupart de ces sites a pris moins d’une seconde.

\n

Lors d’un test, @darinpope un utilisateur d’Hugo a réussi à générer 600 000 pages en moins de 5 minutes !.

\n

Hugo en résumé

\n

Maintenant que nous avons passé en revue les fonctionnalités natives d’Hugo, prenons un peu de recul et jetons un regard externe sur ce générateur de site statique en pesant le pour et le contre.

\n

Pour :

\n\n

Contre :

\n\n\n

En résumé

\n

Nous avons passé en revue les fonctionnalités de base de Jekyll et Hugo, en soulignant la facilité d’installation, la gestion de contenu, les langages de gabarits de page, les workflows de développement, les fonctionnalités offertes et la performance.

\n

Ces deux générateurs sont les leaders dans leur domaine, et il y a plein d’exemples de gros projets qui les utilisent comme healthcare.gov, développé avec Jekyll, et le nouveau site de Smashing Magazine développé avec Hugo.

\n

Maintenant c'est l’heure de faire votre choix ! Voici un petit récapitulatif pour vous aider :

\n\n
\n
\n
    \n
  1. \n

    Hugo a été depuis principalement développé par Bjørn Erik Pedersen. ↩

    \n
    2. \n
  2. \n

    NdT: à l’heure actuelle comme ces extensions ne reposent pas sur des librairies natives en Go, vous perdrez donc le gain de performance apporté par Hugo. ↩

    \n
    3. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/04/04/contenus-relatifs-dans-hugo/", "url": "https://jamstatic.fr/2018/04/04/contenus-relatifs-dans-hugo/", "title": "Entretenir de bonnes relations avec Hugo", "summary": "Définissez des relations entre vos différents types de contenus dans Hugo de façon performante.", "date_published": "2018-04-04T20:25:16+00:00","content_text": "Même s'il est le plus rapide des générateurs de site statiques,\nHugo continue de s'améliorer et de proposer de nouvelles fonctionnalités pour\nnous simplifier la vie. Régis Philibert a testé\npour vous la gestion des contenus relatifs apparus dans la version 0.27.\nJe me suis enfin décidé à améliorer la façon dont je gère les relations entre\nles contenus dans mes projets en utilisant la fonctionnalité dédiée aux contenus\nrelatifs proposée par Hugo.[^1]\nEn faisant cela, j'ai diminué le temps de génération du site d’environ 70%\n⏱️ 👀!\nDans cet article, nous allons voir comme l’implémentation de relations entre vos\ncontenus est facile à ajouter sur un projet existant et comment cela va changer\nà jamais la façon dont nous définissons les relations dans Hugo !\n\nLe Projet\nJ'ai créé et commencé à maintenir un site web open source en français sur la\nsaga des Rougon-Macquart\nd’Émile Zola bien avant que je\ncommence à coder.\nCopier-coller la biographie de tous mes personnages dans WordPress m'a pris pas\nmal de temps, mais je me retrouve maintenant avec le projet idéal pour tester de\nnouveaux outils : l’API Rest de WordPress, AngularJS et plus récemment Hugo !\nAvec un millier d’entrées qui partagent des relations saines, c'est le projet\nparfait pour tester une nouvelle manière de gérer nos relations.\n\nChacun des quelque 1300 personnages apparaît dans quelques romans. La liste des romans où il apparaît est affichée sur la page de chaque personnage.\nDans chacun des 20 romans apparaissent de nombreux personnages. Sur la page de chaque roman figure tous les personnages qui y apparaissent.\n\nStatut des relations avant Related Content: c'est compliqué\nIl n'y avait pas de méthode claire pour connecter des pages entre elles et créer\ndes relations durables et efficaces. La première chose qui venait souvent à\nl’esprit était d’utiliser les taxonomies, mais ça ne marchait pas lorsqu'il\ns'agissait de connecter des pages entre elles.\nUne fois les taxonomies écartées, si vous deviez gérer des relations\nde plusieurs à un,\nvous avez peut-être utilisé les sections avec la plus grande prudence.\nMais quand il s'agit d’implémenter la plus commune des\nrelations de plusieurs à plusieurs,\nje trouve que la solution la plus sensée est de créer une relation via une\nentrée Front Matter dans les pages concernées. Pour les Rougon-Macquart de Zola,\nc'était indéniablement le cas.\nL'implementation dans le Front Matter\nDans ce projet, les romans peuvent compter jusqu'à 90 personnages. Ce qui\nsignifie qui si nous devions lister tous les personnages présents dans un roman,\nnous nous retrouverions avec un tableau de 90 entrées en entête de notre fichier\nMarkdown. C’est vraiment loin d’être idéal.\nDe plus nous n'avons pas vraiment besoin de référencer la connexion de notre\nrelation à la fois dans les pages de romans et dans les pages des personnages.\nLes personnages ne sont présents que dans 4 à 5 romans tout au plus, il vaut\ndonc mieux déclarer les quelques romans dans lesquels ils apparaissent\nplutôt que de lister les nombreux personnages pour chaque roman.\nPar exemple pour le personnage d’Eugène Rougon, qui figure dans 4 romans, cela\ndonne :\ntitle: Rougon (Eugène)\nnovel:\n - argent\n - curee\n - fortune\n - excellence\nMaintenant dans le Front Matter du roman, nous avons juste à ajouter une clef\nd’identifiant. Pour le roman « Son Excellence Eugène Rougon » dans lequel\napparaît ce bon vieil Eugène nous ajoutons :\ntitle: Son excellence Eugène Rougon\nid: excellence\nNous pourrions choisir un identifiant existant comme le nom de\nfichier, mais je préfère un identifiant unique, facile à lire et à écrire.\nLes relations dans nos gabarits de page\nSur\nla page d’Eugène\nnous voulons afficher les romans dans lesquels il apparaît. Nous pouvons\nutiliser intersect pour construire notre liste :\n{{ $characters := where .Site.Pages.ByTitle \".Params.novel\" \"intersect\" (slice .Params.id) }}\nPour afficher la liste des personnages du roman sur la page\nSon Excellence Eugène Rougon,\nnous utilisons l’opérateur in avec where:\n{{ $novels := where .Site.Pages.ByTitle \".Params.id\" \"in\" .Params.novel }}\nEt voilà, nous avons réussi à implémenter une relation de type plusieurs à\nplusieurs comme si nous étions en 2016 !\nCar cela a le mérite de fonctionner mais…\n\n\ninteresect ? where \"in\" ? N’en faisons-nous pas un peu trop ?\n\n\n🐌 Le temps de génération est 7 fois supérieur à la moyenne : ~7 secondes pour 1300 pages.\n\n\n💩 C’est moche.\n\n\nOK… mais que pouvons-nous y faire ? 🤷‍♂️\nRien… enfin jusqu'à la version 0.27 d’Hugo.\nLa fonctionnalité Related Content d’Hugo\nLes contenus relatifs natifs\nont fait leur apparition dans Hugo 0.27 en novembre 2017.\nIls ont été conçus pour aider à ajouter facilement une section « Vous aimerez\naussi : » dans les thèmes et les projets tout en gardant un maximum de\ncontrôle sur l’algorithme de pondération. Vous pouvez définir plusieurs facteurs\nou index en leur affectant leur propre niveau d’importance. Les tags, le mois de\npublication, les auteurs, tout ce qui peut vous aider à construire une liste de\ncontenus relatifs pertinente.\nC’est de loin de meilleur outil pour récupérer des pages relatives à une autre à\nl’aide de votre propre formule et si vous ne l’utilisez pas déjà pour générer\nvotre widget \"Articles\/Produits liés\", vous devriez aller de ce pas consulter\nla documentation pour commencer\nà jouer avec. C’est top !\nNéanmoins dans notre cas, nous n'avons pas besoin d’un module \"romans relatifs\",\nnous avons juste besoin d’établir une relation solide et consistante qui\nn’impacte pas le temps de génération du site. Et il se trouve que c'est\njustement ce que propose la fonctionnalité Related Content !\nNous n'avons même pas besoin de recourir à l’ingénieux facteur de poids d’index\npuisque novel est notre seul et unique index.\nÉtablir des relations avec Related Content\nDéclarer notre index\nEn premier nous devons déclarer la liste de nos index dans notre fichier de\nconfiguration config.yaml. Vu qu'ici nous n' avons que novel comme index…\nrelated:\n indices:\n - name: novel # Le nom de l’index, tel qu'il est défini la clef `.Param` du Front Matter.\n weight: 1 # Nous n'avons pas vraiment besoin, mais si nous l’omettons cela désactivera notre index.\n includeNewer: true # Ici notre relation est sans fin ! Cette option empêche Hugo d’ignorer les nouveaux articles.\nBien se connecter\nL'entête Front Matter de notre personnage est très bien comme elle est. Elle\nliste déjà les romans à l’aide d’une clef qui correspond au nom de notre index\nnovel.\nPar contre, nos romans utilisent id pour s'identifier, il faut changer ça car\nils doivent également utiliser le même nom d’index. Donc l’entête Front Matter\nde notre roman devient :\ntitle: Son Excellence Eugène Rougon\nnovel: excellence # 'id’ précédemment\nBien, nos romans et nos personnages partagent maintenant un .Page.Param commun\nqui utilise le nom de notre index nouvellement déclaré : novel.\nRelated Content dans les gabarits de page\nDans nos gabarits de page, Related offre différentes fonctions pour récupérer\nles pages relatives. Nous allons en voir deux succinctement, mais allez lire\nla documentation\nsi vous souhaitez en apprendre davantage.\n.Related permet de récupérer toutes les pages relatives d’une page donnée\nen fonction des index et du poids déclarés dans le fichier de configuration.\nElle prend un seul paramètre en argument : la page donnée.\n.RelatedIndices permet de récupérer toutes les pages qui comportent un ou\nplusieurs index donnés. Le premier paramètre est la page donnée, les autres\nparamètres sont les index utilisés.\nDans nos gabarits de page de détail, nous allons utiliser la fonction\n.RelatedIndices pour récuperer les romans ou les personnages reliés. Ceci afin\nde limiter les pages reliées à notre index novel et empêcher que de futures\nindex comme des tags ou un auteur viennent interférer dans notre relation\nexistante.\nDans le gabarit de page de détail d’un roman comme \"Son Excellence Eugène\nRougon\", nous pouvons lister tous ses « characters », en anglais dans le texte,\nde la façon suivante :\n{{ $characters := where (.Site.RegularPages.RelatedIndices . \"novel\" ) \"Type\" \"personnage\" }}\nLe premier paramètre c'est le contexte de notre page, le second c'est notre\nfameux index.\nEt pour la page de présentation d’un personnage comme Eugène, pour récupérer\ntoutes ses « novels » :\n{{ $novels := where (.Site.RegularPages.RelatedIndices . \"novel\" ) \"Type\" \"roman\" }}\nEt voilà ! Nous utilisons maintenant la fonction Related Content d’Hugo pour\ngérer nos relations de type plusieurs à plusieurs !\nEt qu'avons-nous gagné outre un code plus propre ?\n🚀 6 secondes de moins ! …sur les ~7s auparavant…\nLe temps de génération n'excède maintenant pas les 1.5s. Dans le mille Émile !\nSi vous êtes curieux, vous pouvez cloner le\nrepo et vous en donner à cœur joie\navec la commande hugo --templateMetrics. Vous pouvez même passer sur la\nbranche\noldRelationship\net comparer avec l’implémentation précédente des relations.\nConclusion\nEn ayant simplement recours à la fonction Related Content native dans Hugo\nplutôt qu'à un horrible patch fait maison, nous avons réduit le temps de\ngénération de plus de 70% et tout ça avec un minimum de changement dans\nnotre code.\nIl y a un énorme avantage à tirer profit des super pouvoirs des nouvelles\nfonctionnalités natives d’Hugo et ce modeste article a tenté de vous montrer à\nquel point il est simple de commencer à utiliser et à implémenter l’une d’entre\nelles dans vos projets existants.", "content_html": "\n

Je me suis enfin décidé à améliorer la façon dont je gère les relations entre\nles contenus dans mes projets en utilisant la fonctionnalité dédiée aux contenus\nrelatifs proposée par Hugo.[^1]

\n

En faisant cela, j'ai diminué le temps de génération du site d’environ 70%\n⏱️ 👀!

\n

Dans cet article, nous allons voir comme l’implémentation de relations entre vos\ncontenus est facile à ajouter sur un projet existant et comment cela va changer\nà jamais la façon dont nous définissons les relations dans Hugo !

\n\n

Le Projet

\n

J'ai créé et commencé à maintenir un site web open source en français sur la\nsaga des Rougon-Macquart\nd’Émile Zola bien avant que je\ncommence à coder.

\n

Copier-coller la biographie de tous mes personnages dans WordPress m'a pris pas\nmal de temps, mais je me retrouve maintenant avec le projet idéal pour tester de\nnouveaux outils : l’API Rest de WordPress, AngularJS et plus récemment Hugo !

\n

Avec un millier d’entrées qui partagent des relations saines, c'est le projet\nparfait pour tester une nouvelle manière de gérer nos relations.

\n\n

Statut des relations avant Related Content: c'est compliqué

\n

Il n'y avait pas de méthode claire pour connecter des pages entre elles et créer\ndes relations durables et efficaces. La première chose qui venait souvent à\nl’esprit était d’utiliser les taxonomies, mais ça ne marchait pas lorsqu'il\ns'agissait de connecter des pages entre elles.

\n

Une fois les taxonomies écartées, si vous deviez gérer des relations\nde plusieurs à un,\nvous avez peut-être utilisé les sections avec la plus grande prudence.

\n

Mais quand il s'agit d’implémenter la plus commune des\nrelations de plusieurs à plusieurs,\nje trouve que la solution la plus sensée est de créer une relation via une\nentrée Front Matter dans les pages concernées. Pour les Rougon-Macquart de Zola,\nc'était indéniablement le cas.

\n

L'implementation dans le Front Matter

\n

Dans ce projet, les romans peuvent compter jusqu'à 90 personnages. Ce qui\nsignifie qui si nous devions lister tous les personnages présents dans un roman,\nnous nous retrouverions avec un tableau de 90 entrées en entête de notre fichier\nMarkdown. C’est vraiment loin d’être idéal.

\n

De plus nous n'avons pas vraiment besoin de référencer la connexion de notre\nrelation à la fois dans les pages de romans et dans les pages des personnages.\nLes personnages ne sont présents que dans 4 à 5 romans tout au plus, il vaut\ndonc mieux déclarer les quelques romans dans lesquels ils apparaissent\nplutôt que de lister les nombreux personnages pour chaque roman.

\n

Par exemple pour le personnage d’Eugène Rougon, qui figure dans 4 romans, cela\ndonne :

\n
title: Rougon (Eugène)\nnovel:\n  - argent\n  - curee\n  - fortune\n  - excellence
\n

Maintenant dans le Front Matter du roman, nous avons juste à ajouter une clef\nd’identifiant. Pour le roman « Son Excellence Eugène Rougon » dans lequel\napparaît ce bon vieil Eugène nous ajoutons :

\n
title: Son excellence Eugène Rougon\nid: excellence
\n\n

Les relations dans nos gabarits de page

\n

Sur\nla page d’Eugène\nnous voulons afficher les romans dans lesquels il apparaît. Nous pouvons\nutiliser intersect pour construire notre liste :

\n
{{ $characters := where .Site.Pages.ByTitle \".Params.novel\" \"intersect\" (slice .Params.id) }}
\n

Pour afficher la liste des personnages du roman sur la page\nSon Excellence Eugène Rougon,\nnous utilisons l’opérateur in avec where:

\n
{{ $novels := where .Site.Pages.ByTitle \".Params.id\" \"in\" .Params.novel }}
\n

Et voilà, nous avons réussi à implémenter une relation de type plusieurs à\nplusieurs comme si nous étions en 2016 !

\n

Car cela a le mérite de fonctionner mais…

\n
    \n
  1. \n

    interesect ? where \"in\" ? N’en faisons-nous pas un peu trop ?

    \n
    2. \n
  2. \n

    🐌 Le temps de génération est 7 fois supérieur à la moyenne : ~7 secondes pour 1300 pages.

    \n
    3. \n
  3. \n

    💩 C’est moche.

    \n
    4. \n
\n

OK… mais que pouvons-nous y faire ? 🤷‍♂️

\n

Rien… enfin jusqu'à la version 0.27 d’Hugo.

\n

La fonctionnalité Related Content d’Hugo

\n

Les contenus relatifs natifs\nont fait leur apparition dans Hugo 0.27 en novembre 2017.

\n

Ils ont été conçus pour aider à ajouter facilement une section « Vous aimerez\naussi : » dans les thèmes et les projets tout en gardant un maximum de\ncontrôle sur l’algorithme de pondération. Vous pouvez définir plusieurs facteurs\nou index en leur affectant leur propre niveau d’importance. Les tags, le mois de\npublication, les auteurs, tout ce qui peut vous aider à construire une liste de\ncontenus relatifs pertinente.

\n

C’est de loin de meilleur outil pour récupérer des pages relatives à une autre à\nl’aide de votre propre formule et si vous ne l’utilisez pas déjà pour générer\nvotre widget \"Articles/Produits liés\", vous devriez aller de ce pas consulter\nla documentation pour commencer\nà jouer avec. C’est top !

\n

Néanmoins dans notre cas, nous n'avons pas besoin d’un module \"romans relatifs\",\nnous avons juste besoin d’établir une relation solide et consistante qui\nn’impacte pas le temps de génération du site. Et il se trouve que c'est\njustement ce que propose la fonctionnalité Related Content !

\n

Nous n'avons même pas besoin de recourir à l’ingénieux facteur de poids d’index\npuisque novel est notre seul et unique index.

\n\n

Déclarer notre index

\n

En premier nous devons déclarer la liste de nos index dans notre fichier de\nconfiguration config.yaml. Vu qu'ici nous n' avons que novel comme index…

\n
related:\n indices:\n   - name: novel # Le nom de l’index, tel qu'il est défini la clef `.Param` du Front Matter.\n     weight: 1 # Nous n'avons pas vraiment besoin, mais si nous l’omettons cela désactivera notre index.\n     includeNewer: true # Ici notre relation est sans fin ! Cette option empêche Hugo d’ignorer les nouveaux articles.
\n

Bien se connecter

\n

L'entête Front Matter de notre personnage est très bien comme elle est. Elle\nliste déjà les romans à l’aide d’une clef qui correspond au nom de notre index\nnovel.

\n

Par contre, nos romans utilisent id pour s'identifier, il faut changer ça car\nils doivent également utiliser le même nom d’index. Donc l’entête Front Matter\nde notre roman devient :

\n
title: Son Excellence Eugène Rougon\nnovel: excellence # 'id’ précédemment
\n

Bien, nos romans et nos personnages partagent maintenant un .Page.Param commun\nqui utilise le nom de notre index nouvellement déclaré : novel.

\n

Related Content dans les gabarits de page

\n

Dans nos gabarits de page, Related offre différentes fonctions pour récupérer\nles pages relatives. Nous allons en voir deux succinctement, mais allez lire\nla documentation\nsi vous souhaitez en apprendre davantage.

\n

.Related permet de récupérer toutes les pages relatives d’une page donnée\nen fonction des index et du poids déclarés dans le fichier de configuration.\nElle prend un seul paramètre en argument : la page donnée.

\n

.RelatedIndices permet de récupérer toutes les pages qui comportent un ou\nplusieurs index donnés. Le premier paramètre est la page donnée, les autres\nparamètres sont les index utilisés.

\n

Dans nos gabarits de page de détail, nous allons utiliser la fonction\n.RelatedIndices pour récuperer les romans ou les personnages reliés. Ceci afin\nde limiter les pages reliées à notre index novel et empêcher que de futures\nindex comme des tags ou un auteur viennent interférer dans notre relation\nexistante.

\n

Dans le gabarit de page de détail d’un roman comme \"Son Excellence Eugène\nRougon\", nous pouvons lister tous ses « characters », en anglais dans le texte,\nde la façon suivante :

\n
{{ $characters := where (.Site.RegularPages.RelatedIndices . \"novel\" ) \"Type\" \"personnage\" }}
\n

Le premier paramètre c'est le contexte de notre page, le second c'est notre\nfameux index.

\n

Et pour la page de présentation d’un personnage comme Eugène, pour récupérer\ntoutes ses « novels » :

\n
{{ $novels := where (.Site.RegularPages.RelatedIndices . \"novel\" ) \"Type\" \"roman\" }}
\n

Et voilà ! Nous utilisons maintenant la fonction Related Content d’Hugo pour\ngérer nos relations de type plusieurs à plusieurs !

\n

Et qu'avons-nous gagné outre un code plus propre ?

\n

🚀 6 secondes de moins ! …sur les ~7s auparavant…

\n

Le temps de génération n'excède maintenant pas les 1.5s. Dans le mille Émile !

\n\n

Conclusion

\n

En ayant simplement recours à la fonction Related Content native dans Hugo\nplutôt qu'à un horrible patch fait maison, nous avons réduit le temps de\ngénération de plus de 70% et tout ça avec un minimum de changement dans\nnotre code.

\n

Il y a un énorme avantage à tirer profit des super pouvoirs des nouvelles\nfonctionnalités natives d’Hugo et ce modeste article a tenté de vous montrer à\nquel point il est simple de commencer à utiliser et à implémenter l’une d’entre\nelles dans vos projets existants.

", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/03/19/demarrer-avec-algolia/", "url": "https://jamstatic.fr/2018/03/19/demarrer-avec-algolia/", "title": "Bien démarrer avec Algolia", "summary": "Jess West vous dit comment indexer et intégrer une recherche performante pour son site.", "date_published": "2018-03-19T20:13:46+00:00","content_text": "Algolia fait tout pour faciliter l’ajout d’une recherche performante sur votre site. Jessica West le prouve une fois de plus en nous décrivant pas-à-pas les étapes nécessaires pour y parvenir, ici en vanilla JS avec InstantSearch.\nSalut 👋 ! Ça vous est déjà arrivé de développer entièrement un moteur de recherche ? Avez-vous déjà redouté que votre Product Manager vous dise \"tu sais ce qui serait super ? Ce serait d’avoir une barre de recherche sur le site\" et là votre première réaction est de soupirer et de lever les yeux au ciel…\nÇa m'est arrivé malheureusement beaucoup trop souvent. Pour être franche, j'évitais ce genre de demande comme la peste car même quand j'arrivais à faire fonctionner la recherche, je voyais bien que c'est pas \"génial\" et de plus arrivée à la moitié de la documentation je me demandais, mais bon sang, où est-ce qu'est censé aller ce module ? Vraiment, c'est pas marrant à faire.\nMais maintenant, nous avons des outils et des services à notre disposition qui rendent tout cela bien plus simple. C’est fini le temps où on développait un moteur de recherche à la mano. Ah, que c'est beau le progrès. Ma vie est un peu plus simple chaque jour qui passe.\nC’est une des raisons pour lesquelles j'ai commencé à jouer avec Algolia et que j'ai fini par rejoindre leur équipe. Je n'ai vraiment pas envie que vous lisiez cet article en vous disant \"oh non, elle veut nous vendre le produit\". Non j'aimerais vraiment partager avec vous ce que j'ai appris pour bien démarrer avec Algolia et comment faire pour se mettre à coder avec. Regardons donc quelles sont les quelques étapes pour vous vous puissiez avoir une recherche fonctionnelle sur votre site.\nObtenir vos clefs d’API\n\n\n\n\n\n\nLes différentes clés d’API d’Algolia\n\nCommencez par créer un compte chez Algolia. Et récupérez ensuite vos identifiants dans votre dashboard. Vous aurez besoin de copier App Id, Search Only API Key et Admin API Key.\nUne fois que c'est fait, ajoutez-les dans ce que vous utilisez pour stocker vos variables d’environnement (un fichier .env par exemple) de manière à ce que votre application sache comment se connecter à votre application Algolia et à son index. Et voilà ! Le plus dur est fait !\nConnecter votre source de données\nSi vos données déjà sont accessibles en ligne, nous pouvons commencer par la création d’une fonction qui va appeler cette URL et venir alimenter l’index de votre application Algolia. Regardons comment faire ça en JavaScript.\nconst data_url = \"https:\/\/raw.githubusercontent.com\/algolia\/datasets\/master\/movies\/actors.json\";\n\nfunction indexData(data_url) {\n return axios\n .get(data_url, {})\n .then(function (response) {\n console.log(response.data[0]);\n return;\n })\n .catch(function (error) {\n console.warn(error);\n });\n}\nPour le moment cette fonction ne fait que récupérer l’url de données que nous lui passons en paramètre et affiche dans la console le premier enregistrement trouvé. Ici nous faisons appel à Axios pour effectuer des appels d’API. Axios est une librairie JavaScript utilisée pour faire des requêtes HTTP avec node.js ou depuis le navigateur et elle retourne une promesse, une API native en JavaScript depuis ECMAScript 6. L'avantage de cette librairie, c'est qu'elle peut transformer automatiquement des données JSON.\nPréparer les données pour Algolia\nMaintenant que nous avons fait un appel à nos données, commençons à utiliser le compte Algolia que nous venons de créer pour mettre à jour notre index avec nos données ! Nous allons faire ça en deux temps, d’abord nous allons parcourir les données retournées par notre appel axios.get et en faire un tableau d’objets. Cela va nous permettre de n'utiliser que les données que nous voulons dans notre index. Après, une fois que c'est fait nous pouvons envoyer ces données à notre index Algolia.\nPremière étape : Plutôt que de juste retourner une réponse positive, créons une fonction qui va gérer cet envoi des données en lui passant la réponse à notre appel axios.get.\nfunction indexData(data_url) {\n return axios\n .get(data_url, {})\n .then((response) => {\n return dataToAlgoliaObject(response.data);\n })\n .then(function (response) {\n return;\n })\n .catch(function (error) {\n console.warn(error);\n });\n}\nMaintenant dans notre fonction, nous allons vouloir parcourir toutes les entrées présentes dans nos données et en faire des objets Algolia, à l’aide d’une boucle qui devrait être assez facile à écrire.\nfunction dataToAlgoliaObject(data_points) {\n var algoliaObjects = [];\n for (var i = 0; i < data_points.length; i++) {\n var data_point = data_points[i];\n var algoliaObject = {\n objectID: data_point.objectID,\n name: data_point.name,\n rating: data_point.rating,\n image_path: data_point.image_path,\n alternative_name: data_point.alternative_name,\n };\n algoliaObjects.push(algoliaObject);\n }\n\n return algoliaObjects;\n}\nDeuxième étape : Maintenant que nous avons créé nos objets, ils sont prêts à être envoyés à Algolia !\nChangeons quelques trucs dans notre fonction indexData. Nous pouvons chaîner notre appel avec un .then grâce la structure de notre promesse axios et utiliser async et await pour nous assurer que tout se passe bien pendant l’envoi de nos données.\nfunction indexData(data_url) {\n return axios\n .get(data_url, {})\n .then((response) => {\n return dataToAlgoliaObject(response.data);\n })\n .then(async (response) => {\n await sendDataToAlgolia(response);\n return;\n })\n .then(function (response) {\n return;\n })\n .catch(function (error) {\n console.warn(error);\n });\n}\nEnvoi des données à Algolia\nÉcrivons maintenant la fonction sendDataToAlgolia. C’est le moment où nous allons avoir besoin des clés que nous avons stockées auparavant dans notre fichier .env. Nous allons également devoir nous assurer que nous avons quelque chose qui initialise notre index et nous permette de lui donner le nom de notre choix pour y stocker nos données. Vu que notre jeu de données contient des acteurs de cinéma, ça semble être un bon nom pour notre index.\nconst algoliaClient = algoliasearch(\n process.env.ALGOLIA_APP_ID,\n process.env.ALGOLIA_ADMIN_API_KEY\n);\nconst algoliaIndex = algoliaClient.initIndex(\"movie-actors\");\n\nfunction sendDataToAlgolia(algoliaObjects) {\n return new Promise((resolve, reject) => {\n algoliaIndex.addObjects(algoliaObjects, (err, content) => {\n if (err) reject(err);\n resolve();\n });\n });\n}\nConfiguration des paramètres\nNous avons des données dans notre index ! Maintenant, nous voulons dire à Algolia comment nous voulons que ces données soient utilisées. Nous pouvons faire cela dans l’interface d’administration ou avec du code. Je préfère la deuxième méthode, voyons ensemble comment faire cela. Nous avons beaucoup d’options mais tenons nous en pour le moment aux options de base :\n\nsearchableAttributes: listez ce que vous voulez pouvoir rechercher dans l’objet Algolia que vous avez crée\nattributesToHighlight: mettre en surbrillance le champ recherché\ncustomRanking: choisissez la façon donc vous voulez afficher vos données, desc() ou asc()\nattributesToRetrieve: les attributs à afficher dans les résultats de recherche\n\nasync function configureAlgoliaIndex() {\n algoliaIndex.setSettings({\n searchableAttributes: [\"name\"],\n attributesToHighlight: [\"name\"],\n customRanking: [\"desc(rating)\"],\n attributesToRetrieve: [\"name\", \"rating\", \"image_path\"],\n });\n}\nAjoutons maintenant cette fonction, une fois l’envoi de notre index correctement effectué.\nfunction indexData(data_url) {\n return axios\n .get(data_url, {})\n .then((response) => {\n return dataToAlgoliaObject(response.data);\n })\n .then(async (response) => {\n await sendDataToAlgolia(response);\n return;\n })\n .then(async () => {\n await configureAlgoliaIndex();\n return;\n })\n .then(function (response) {\n return;\n })\n .catch(function (error) {\n console.warn(error);\n });\n}\nWaouh, nous avons maintenant ajouté les données à notre index comme nous le souhaitions. Nous en avons donc terminé avec la partie serveur, passons maintenant à la partie où les gens peuvent voir et rechercher dans nos données, si chères à nos yeux.\nConnecter le front-end\nAlgolia a ce qu'on appelle des widgets, qui nous permettent d’ajouter rapidement des sections dans notre page HTML sans avoir à écrire beaucoup de code. Des éléments comme une barre de recherche, ou bien l’endroit où nos objets Algolia seront vus dans la page, peuvent être ajoutés à l’aide de quelques lignes de JavaScript. Ouvrons notre fichier pour le côté client.\nNous allons commencer par créer une instance d’instantsearch que nous pourrons utiliser dans notre application. Vous pouvez utiliser des cookies pour passer ces données du serveur au client ou bien vous pouvez utiliser les clefs. Pour faire au plus simple, nous allons utiliser les clefs ici.\n$(document).ready(function () {\n var instantsearch = window.instantsearch;\n\n \/\/ création d’une instance d’instantsearch\n \/\/ avec notre identifiant d’application et notre clef d’API\n var search = instantsearch({\n appId: Cookies.get(\"app_id\"),\n apiKey: Cookies.get(\"search_api_key\"),\n indexName: Cookies.get(\"index_name\"),\n urlSync: true,\n searchParameters: {\n hitsPerPage: 3,\n },\n });\n});\nConnectons maintenant notre input de recherche à notre code HTML pour que les gens aient une barre de recherche.\nsearch.addWidget(\n instantsearch.widgets.searchBox({\n container: \"#search-box\",\n placeholder: \"Rechercher vos acteurs préférés\",\n })\n);\nMaintenant, nous voulons ajouter les résultats provenant de nos données, et retourner ce que nous voulons afficher.\nsearch.addWidget(\n instantsearch.widgets.hits({\n container: \"#hits\",\n hitsPerPage: 12,\n templates: {\n empty: `<div class=\"col-md-12\" style=\"text-align: center;\"> Nous n'avons pas trouvé de résultats correspondants à votre recherche <em>\\\"{{query}}\\\"<\/em><\/div`,\n item: function (hit) {\n try {\n return `\n <div class=\"col-md-4\" style=\"text-align: center;\">\n <p>\n <h3 class=\"hit-text\">${hit._highlightResult.name.value}<\/h3>\n <img src=\"https:\/\/image.tmdb.org\/t\/p\/w45\/${hit.image_path}\" height=\"50\" width=\"50\">\n <\/p>\n <p>\n Rating: ⭐️ ${hit.rating}\n <\/p>\n <\/div>\n `;\n } catch (e) {\n console.warn(\"Couldn't render hit\", hit, e);\n return \"\";\n }\n },\n },\n })\n);\nUne bonne expérience de recherche ne devrait pas retourner trop de résultats à la fois, ajoutons donc une pagination aux résultats que nous renvoyons.\nsearch.addWidget(\n instantsearch.widgets.pagination({\n container: \"#pagination\",\n })\n);\nEt enfin pour terminer… lançons la recherche ! Cela va permettre de tout instancier dans votre page.\nsearch.start();\nNaturellement, si vous voulez vous épargner tout ce travail manuel, vous pouvez allez voir notre application pour démarrer rapidement sur Glitch, la remixer et vous aurez tout ce code et une application basique qui tourne en moins de 5 minutes.\n😉 J'espère que cette lecture vous a plu et vous aura été utile !", "content_html": "\n

Salut 👋 ! Ça vous est déjà arrivé de développer entièrement un moteur de recherche ? Avez-vous déjà redouté que votre Product Manager vous dise \"tu sais ce qui serait super ? Ce serait d’avoir une barre de recherche sur le site\" et là votre première réaction est de soupirer et de lever les yeux au ciel…

\n

Ça m'est arrivé malheureusement beaucoup trop souvent. Pour être franche, j'évitais ce genre de demande comme la peste car même quand j'arrivais à faire fonctionner la recherche, je voyais bien que c'est pas \"génial\" et de plus arrivée à la moitié de la documentation je me demandais, mais bon sang, où est-ce qu'est censé aller ce module ? Vraiment, c'est pas marrant à faire.

\n

Mais maintenant, nous avons des outils et des services à notre disposition qui rendent tout cela bien plus simple. C’est fini le temps où on développait un moteur de recherche à la mano. Ah, que c'est beau le progrès. Ma vie est un peu plus simple chaque jour qui passe.

\n

C’est une des raisons pour lesquelles j'ai commencé à jouer avec Algolia et que j'ai fini par rejoindre leur équipe. Je n'ai vraiment pas envie que vous lisiez cet article en vous disant \"oh non, elle veut nous vendre le produit\". Non j'aimerais vraiment partager avec vous ce que j'ai appris pour bien démarrer avec Algolia et comment faire pour se mettre à coder avec. Regardons donc quelles sont les quelques étapes pour vous vous puissiez avoir une recherche fonctionnelle sur votre site.

\n

Obtenir vos clefs d’API

\n
\n\n\n\n\"Les\n\n
Les différentes clés d’API d’Algolia
\n
\n

Commencez par créer un compte chez Algolia. Et récupérez ensuite vos identifiants dans votre dashboard. Vous aurez besoin de copier App Id, Search Only API Key et Admin API Key.

\n

Une fois que c'est fait, ajoutez-les dans ce que vous utilisez pour stocker vos variables d’environnement (un fichier .env par exemple) de manière à ce que votre application sache comment se connecter à votre application Algolia et à son index. Et voilà ! Le plus dur est fait !

\n

Connecter votre source de données

\n

Si vos données déjà sont accessibles en ligne, nous pouvons commencer par la création d’une fonction qui va appeler cette URL et venir alimenter l’index de votre application Algolia. Regardons comment faire ça en JavaScript.

\n
const data_url = \"https://raw.githubusercontent.com/algolia/datasets/master/movies/actors.json\";\n\nfunction indexData(data_url) {\n  return axios\n    .get(data_url, {})\n    .then(function (response) {\n      console.log(response.data[0]);\n      return;\n    })\n    .catch(function (error) {\n      console.warn(error);\n    });\n}
\n

Pour le moment cette fonction ne fait que récupérer l’url de données que nous lui passons en paramètre et affiche dans la console le premier enregistrement trouvé. Ici nous faisons appel à Axios pour effectuer des appels d’API. Axios est une librairie JavaScript utilisée pour faire des requêtes HTTP avec node.js ou depuis le navigateur et elle retourne une promesse, une API native en JavaScript depuis ECMAScript 6. L'avantage de cette librairie, c'est qu'elle peut transformer automatiquement des données JSON.

\n

Préparer les données pour Algolia

\n

Maintenant que nous avons fait un appel à nos données, commençons à utiliser le compte Algolia que nous venons de créer pour mettre à jour notre index avec nos données ! Nous allons faire ça en deux temps, d’abord nous allons parcourir les données retournées par notre appel axios.get et en faire un tableau d’objets. Cela va nous permettre de n'utiliser que les données que nous voulons dans notre index. Après, une fois que c'est fait nous pouvons envoyer ces données à notre index Algolia.

\n

Première étape : Plutôt que de juste retourner une réponse positive, créons une fonction qui va gérer cet envoi des données en lui passant la réponse à notre appel axios.get.

\n
function indexData(data_url) {\n  return axios\n    .get(data_url, {})\n    .then((response) => {\n      return dataToAlgoliaObject(response.data);\n    })\n    .then(function (response) {\n      return;\n    })\n    .catch(function (error) {\n      console.warn(error);\n    });\n}
\n

Maintenant dans notre fonction, nous allons vouloir parcourir toutes les entrées présentes dans nos données et en faire des objets Algolia, à l’aide d’une boucle qui devrait être assez facile à écrire.

\n
function dataToAlgoliaObject(data_points) {\n  var algoliaObjects = [];\n  for (var i = 0; i < data_points.length; i++) {\n    var data_point = data_points[i];\n    var algoliaObject = {\n      objectID: data_point.objectID,\n      name: data_point.name,\n      rating: data_point.rating,\n      image_path: data_point.image_path,\n      alternative_name: data_point.alternative_name,\n    };\n    algoliaObjects.push(algoliaObject);\n  }\n\n  return algoliaObjects;\n}
\n

Deuxième étape : Maintenant que nous avons créé nos objets, ils sont prêts à être envoyés à Algolia !

\n

Changeons quelques trucs dans notre fonction indexData. Nous pouvons chaîner notre appel avec un .then grâce la structure de notre promesse axios et utiliser async et await pour nous assurer que tout se passe bien pendant l’envoi de nos données.

\n
function indexData(data_url) {\n  return axios\n    .get(data_url, {})\n    .then((response) => {\n      return dataToAlgoliaObject(response.data);\n    })\n    .then(async (response) => {\n      await sendDataToAlgolia(response);\n      return;\n    })\n    .then(function (response) {\n      return;\n    })\n    .catch(function (error) {\n      console.warn(error);\n    });\n}
\n

Envoi des données à Algolia

\n

Écrivons maintenant la fonction sendDataToAlgolia. C’est le moment où nous allons avoir besoin des clés que nous avons stockées auparavant dans notre fichier .env. Nous allons également devoir nous assurer que nous avons quelque chose qui initialise notre index et nous permette de lui donner le nom de notre choix pour y stocker nos données. Vu que notre jeu de données contient des acteurs de cinéma, ça semble être un bon nom pour notre index.

\n
const algoliaClient = algoliasearch(\n  process.env.ALGOLIA_APP_ID,\n  process.env.ALGOLIA_ADMIN_API_KEY\n);\nconst algoliaIndex = algoliaClient.initIndex(\"movie-actors\");\n\nfunction sendDataToAlgolia(algoliaObjects) {\n  return new Promise((resolve, reject) => {\n    algoliaIndex.addObjects(algoliaObjects, (err, content) => {\n      if (err) reject(err);\n      resolve();\n    });\n  });\n}
\n

Configuration des paramètres

\n

Nous avons des données dans notre index ! Maintenant, nous voulons dire à Algolia comment nous voulons que ces données soient utilisées. Nous pouvons faire cela dans l’interface d’administration ou avec du code. Je préfère la deuxième méthode, voyons ensemble comment faire cela. Nous avons beaucoup d’options mais tenons nous en pour le moment aux options de base :

\n\n
async function configureAlgoliaIndex() {\n  algoliaIndex.setSettings({\n    searchableAttributes: [\"name\"],\n    attributesToHighlight: [\"name\"],\n    customRanking: [\"desc(rating)\"],\n    attributesToRetrieve: [\"name\", \"rating\", \"image_path\"],\n  });\n}
\n

Ajoutons maintenant cette fonction, une fois l’envoi de notre index correctement effectué.

\n
function indexData(data_url) {\n  return axios\n    .get(data_url, {})\n    .then((response) => {\n      return dataToAlgoliaObject(response.data);\n    })\n    .then(async (response) => {\n      await sendDataToAlgolia(response);\n      return;\n    })\n    .then(async () => {\n      await configureAlgoliaIndex();\n      return;\n    })\n    .then(function (response) {\n      return;\n    })\n    .catch(function (error) {\n      console.warn(error);\n    });\n}
\n

Waouh, nous avons maintenant ajouté les données à notre index comme nous le souhaitions. Nous en avons donc terminé avec la partie serveur, passons maintenant à la partie où les gens peuvent voir et rechercher dans nos données, si chères à nos yeux.

\n

Connecter le front-end

\n

Algolia a ce qu'on appelle des widgets, qui nous permettent d’ajouter rapidement des sections dans notre page HTML sans avoir à écrire beaucoup de code. Des éléments comme une barre de recherche, ou bien l’endroit où nos objets Algolia seront vus dans la page, peuvent être ajoutés à l’aide de quelques lignes de JavaScript. Ouvrons notre fichier pour le côté client.

\n

Nous allons commencer par créer une instance d’instantsearch que nous pourrons utiliser dans notre application. Vous pouvez utiliser des cookies pour passer ces données du serveur au client ou bien vous pouvez utiliser les clefs. Pour faire au plus simple, nous allons utiliser les clefs ici.

\n
$(document).ready(function () {\n  var instantsearch = window.instantsearch;\n\n  // création d’une instance d’instantsearch\n  // avec notre identifiant d’application et notre clef d’API\n  var search = instantsearch({\n    appId: Cookies.get(\"app_id\"),\n    apiKey: Cookies.get(\"search_api_key\"),\n    indexName: Cookies.get(\"index_name\"),\n    urlSync: true,\n    searchParameters: {\n      hitsPerPage: 3,\n    },\n  });\n});
\n

Connectons maintenant notre input de recherche à notre code HTML pour que les gens aient une barre de recherche.

\n
search.addWidget(\n  instantsearch.widgets.searchBox({\n    container: \"#search-box\",\n    placeholder: \"Rechercher vos acteurs préférés\",\n  })\n);
\n

Maintenant, nous voulons ajouter les résultats provenant de nos données, et retourner ce que nous voulons afficher.

\n
search.addWidget(\n  instantsearch.widgets.hits({\n    container: \"#hits\",\n    hitsPerPage: 12,\n    templates: {\n      empty: `<div class=\"col-md-12\" style=\"text-align: center;\"> Nous n'avons pas trouvé de résultats correspondants à votre recherche <em>\\\"{{query}}\\\"</em></div`,\n      item: function (hit) {\n        try {\n          return `\n              <div class=\"col-md-4\" style=\"text-align: center;\">\n                <p>\n                  <h3 class=\"hit-text\">${hit._highlightResult.name.value}</h3>\n                  <img src=\"https://image.tmdb.org/t/p/w45/${hit.image_path}\" height=\"50\" width=\"50\">\n                </p>\n                <p>\n                  Rating: ⭐️ ${hit.rating}\n                </p>\n              </div>\n            `;\n        } catch (e) {\n          console.warn(\"Couldn't render hit\", hit, e);\n          return \"\";\n        }\n      },\n    },\n  })\n);
\n

Une bonne expérience de recherche ne devrait pas retourner trop de résultats à la fois, ajoutons donc une pagination aux résultats que nous renvoyons.

\n
search.addWidget(\n  instantsearch.widgets.pagination({\n    container: \"#pagination\",\n  })\n);
\n

Et enfin pour terminer… lançons la recherche ! Cela va permettre de tout instancier dans votre page.

\n
search.start();
\n

Naturellement, si vous voulez vous épargner tout ce travail manuel, vous pouvez allez voir notre application pour démarrer rapidement sur Glitch, la remixer et vous aurez tout ce code et une application basique qui tourne en moins de 5 minutes.

\n

😉 J'espère que cette lecture vous a plu et vous aura été utile !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/03/17/premier-meetup-jamstack-toulouse/", "url": "https://jamstatic.fr/2018/03/17/premier-meetup-jamstack-toulouse/", "title": "Meetup Jamstack Toulouse", "summary": "Deux présentations de Netlify et Algolia lors premier meetup Jamstack en France.", "date_published": "2018-03-17T08:24:53+00:00","content_text": "Ce premier meetup Jamstack français a été l’occasion d’accueillir Netlify et Algolia, deux acteurs incontournables du mouvement. Les deux start-ups sont maintenant devenues des références dans leur domaine, l’une pour le déploiement d’applications web servies en statique, l’autre comme service de recherche embarquée. Au programme deux présentations de Phil Hawksworth et Martyn Davies toutes deux axées sur la developer experience et les bénéfices apportés par ces deux services de qualité.\n\n\n\n\n\n\nPhoto : Nicolas Manaud\n\nLors de l’introduction, j'ai rapidement rappelé comment nous en sommes arrivés à ces workflows de déploiement et comment ils permettent aux développeurs front-end de reprendre la main sur ce qui est produit en sortie, puisqu'ils sont libres de choisir la solution de templating qui va générer le HTML et qu'ils ne seront pas contraints par la structure de la base de données d’un CMS. Une vraie aubaine pour les artisans qui aiment faire les choses bien et se soucient de la qualité.\nMaking platforms promote performance\nLa présentation de Phil Hawksworth, developer relation chez Netlify, n'était pas aussi austère que le titre aurait pu le laisser penser. En effet Phil est revenu sur les mises en production stressantes de projets, où faute de workflow automatisé et prédictible, les équipes vont stresser jusqu'au bout, la prise de risque étant maximale et la sueur perlera sur le front de la personne chargée d’appuyer sur le bouton rouge. Personne ne souhaite vivre de telles expériences.\n\n\n\nPour s'éviter de tels tracas, autant commencer par s'assurer que le déploiement automatique fonctionne comme il faut en début de projet. Mieux encore, en versionnant correctement son projet avec Git, en le déployant régulièrement, on va permettre à tous les intervenants de s'investir et de faire des retours au plus tôt. C’est la garantie de plus de sérénité pour tout le monde lors du lancement officiel. Et cette façon de travailler est rendue très accessible par Netlify, nul besoin d’avoir une équipe de devops chevronnés pour vous aider à mettre en place un tel workflow. En quelques clics c'est réglé.\nPhil a pu observer comment Netlify utilisait Netlify pour développer et concevoir son application web, servie naturellement elle aussi en statique. Grâce à la mise en ligne du résultat de la génération du site pour chaque commit, il a pu remonter aux origines, voir les premiers prototypes et ainsi parcourir toute la timeline du projet. Si Git permet de faire ce genre de choses dans un terminal et de voir les différences, les ajouts et les suppressions de fichiers, Netlify propose la même chose mais sous forme visuelle, vous pouvez consulter n'importe quelle version du site sur une URL unique basée sur le hash du commit.\n\n\n\n\n\n\nLes premiers prototypes du site de Netlify sont encore accessibles en ligne.\n\nUn webdesigner pourra dès alors présenter une nouvelle itération sur le design du site en ouvrant une pull request sur GitHub et en retour toutes les parties prenantes pourront consulter une version utilisable du site en ligne. Il est même possible de comparer comment différentes versions d’un design performent grâce au split-testing.\nPour faire face à l’accélération et à l’exigeance technique croissante en termes de développement, il est bon de pouvoir déléguer des tâches aussi hardues que le déploiement continu à ceux dont c'est le métier.\nAjouter une recherche sur un site statique\n\n\n\nMartyn Davies, nouvellement arrivé chez Algolia, est venu nous montrer comment ajouter une recherche performante sur un site généré en statique. Pari réussi puisqu'à la fin de la présentation, son site généré avec Jekyll disposait d’un champ de recherche avec autocomplétion sur des attributs qu'il avait lui-même défini et affichait des résultats de manière quasi-immédiate à chaque touche tapée sur le clavier.\nC’est toujours bluffant de voir à quel point l’intégration de tels services a été pensée pour être la plus simple possible pour les développeurs. Dans cet exemple, Martyn a utilisé le plugin jekyll-algolia développé par Tim Carry, passé ingénieur open-source à plein temps chez Algolia.\nDans un premier temps, on va déclarer le plugin dans Jekyll, puis après avoir créé un compte sur le site d’Algolia ainsi qu'un premier projet, on va récupérer une clef d’API et un nom d’index de recherche qu'on va reporter dans les paramètres de configuration du plugin. On est sur du Copier-Coller driven development.\nUne fois que c'est fait, on va créer un modèle de page pour la recherche, qui fera appel à un script JS et à une feuille de style hébergés par Algolia sur un CDN. Puis on va ajouter des widgets de recherche et personnaliser leur configuration. Après quelques aller-retours entre les exemples documentés sur le site d’Algolia et le template de recherche pour Jekyll, ainsi que quelques ajustements des attributs à indexer et à retourner dans l’interface d’administration d’Algolia, le site d’exemple disposait d’une recherche instantanée. À tel point que Phil a demandé s’il y avait vraiment des appels à l’API d’Algolia pour retourner les résultats aussi vite ou si c'était un cache en local. Martyn a répondu par l’affirmative, en souriant devant l’incrédulité de son homologue.\nUne chouette soirée\nDeux présentations rondemment menées donc, qui ont été bien appréciées par les personnes présentes.\nMaxime Thirouin le développeur de Phenomic a bien envie de développer à son tour un plugin Algolia après la présentation de Martyn. Il pourra pour cela se baser sur le code source ouvert du paquet atomic-algolia développé par Chris Macrae de Forestry. C’est beau l’open source.\nNous espérons que ces deux présentations auront donné envie aux développeurs front-end d’utiliser des workflows et des outils matures et qu'ils auront bien compris qu'on peut faire des choses dynamiques avec des sites versionnés servis en statique en s'affranchissant de la gestion de serveur de base de données. Et si c'est toujours pas clair, nous ferons d’autres meetups. :)\nEt grâce au soutien de Front-Commerce, un front-end JS qui communique avec des APIS e-commerce, nous publierons les vidéos des deux présentations d’ici quelques semaines, merci à eux !", "content_html": "\n
\n\n\n\n\"The\n\n
Photo : Nicolas Manaud
\n
\n

Lors de l’introduction, j'ai rapidement rappelé comment nous en sommes arrivés à ces workflows de déploiement et comment ils permettent aux développeurs front-end de reprendre la main sur ce qui est produit en sortie, puisqu'ils sont libres de choisir la solution de templating qui va générer le HTML et qu'ils ne seront pas contraints par la structure de la base de données d’un CMS. Une vraie aubaine pour les artisans qui aiment faire les choses bien et se soucient de la qualité.

\n

Making platforms promote performance

\n

La présentation de Phil Hawksworth, developer relation chez Netlify, n'était pas aussi austère que le titre aurait pu le laisser penser. En effet Phil est revenu sur les mises en production stressantes de projets, où faute de workflow automatisé et prédictible, les équipes vont stresser jusqu'au bout, la prise de risque étant maximale et la sueur perlera sur le front de la personne chargée d’appuyer sur le bouton rouge. Personne ne souhaite vivre de telles expériences.

\n

\n\n

\n

Pour s'éviter de tels tracas, autant commencer par s'assurer que le déploiement automatique fonctionne comme il faut en début de projet. Mieux encore, en versionnant correctement son projet avec Git, en le déployant régulièrement, on va permettre à tous les intervenants de s'investir et de faire des retours au plus tôt. C’est la garantie de plus de sérénité pour tout le monde lors du lancement officiel. Et cette façon de travailler est rendue très accessible par Netlify, nul besoin d’avoir une équipe de devops chevronnés pour vous aider à mettre en place un tel workflow. En quelques clics c'est réglé.

\n

Phil a pu observer comment Netlify utilisait Netlify pour développer et concevoir son application web, servie naturellement elle aussi en statique. Grâce à la mise en ligne du résultat de la génération du site pour chaque commit, il a pu remonter aux origines, voir les premiers prototypes et ainsi parcourir toute la timeline du projet. Si Git permet de faire ce genre de choses dans un terminal et de voir les différences, les ajouts et les suppressions de fichiers, Netlify propose la même chose mais sous forme visuelle, vous pouvez consulter n'importe quelle version du site sur une URL unique basée sur le hash du commit.

\n
\n\n\n\n\"Les\n\n
Les premiers prototypes du site de Netlify sont encore accessibles en ligne.
\n
\n

Un webdesigner pourra dès alors présenter une nouvelle itération sur le design du site en ouvrant une pull request sur GitHub et en retour toutes les parties prenantes pourront consulter une version utilisable du site en ligne. Il est même possible de comparer comment différentes versions d’un design performent grâce au split-testing.

\n

Pour faire face à l’accélération et à l’exigeance technique croissante en termes de développement, il est bon de pouvoir déléguer des tâches aussi hardues que le déploiement continu à ceux dont c'est le métier.

\n

Ajouter une recherche sur un site statique

\n

\n\n

\n

Martyn Davies, nouvellement arrivé chez Algolia, est venu nous montrer comment ajouter une recherche performante sur un site généré en statique. Pari réussi puisqu'à la fin de la présentation, son site généré avec Jekyll disposait d’un champ de recherche avec autocomplétion sur des attributs qu'il avait lui-même défini et affichait des résultats de manière quasi-immédiate à chaque touche tapée sur le clavier.

\n

C’est toujours bluffant de voir à quel point l’intégration de tels services a été pensée pour être la plus simple possible pour les développeurs. Dans cet exemple, Martyn a utilisé le plugin jekyll-algolia développé par Tim Carry, passé ingénieur open-source à plein temps chez Algolia.

\n

Dans un premier temps, on va déclarer le plugin dans Jekyll, puis après avoir créé un compte sur le site d’Algolia ainsi qu'un premier projet, on va récupérer une clef d’API et un nom d’index de recherche qu'on va reporter dans les paramètres de configuration du plugin. On est sur du Copier-Coller driven development.

\n

Une fois que c'est fait, on va créer un modèle de page pour la recherche, qui fera appel à un script JS et à une feuille de style hébergés par Algolia sur un CDN. Puis on va ajouter des widgets de recherche et personnaliser leur configuration. Après quelques aller-retours entre les exemples documentés sur le site d’Algolia et le template de recherche pour Jekyll, ainsi que quelques ajustements des attributs à indexer et à retourner dans l’interface d’administration d’Algolia, le site d’exemple disposait d’une recherche instantanée. À tel point que Phil a demandé s’il y avait vraiment des appels à l’API d’Algolia pour retourner les résultats aussi vite ou si c'était un cache en local. Martyn a répondu par l’affirmative, en souriant devant l’incrédulité de son homologue.

\n

Une chouette soirée

\n

Deux présentations rondemment menées donc, qui ont été bien appréciées par les personnes présentes.

\n

Maxime Thirouin le développeur de Phenomic a bien envie de développer à son tour un plugin Algolia après la présentation de Martyn. Il pourra pour cela se baser sur le code source ouvert du paquet atomic-algolia développé par Chris Macrae de Forestry. C’est beau l’open source.

\n

Nous espérons que ces deux présentations auront donné envie aux développeurs front-end d’utiliser des workflows et des outils matures et qu'ils auront bien compris qu'on peut faire des choses dynamiques avec des sites versionnés servis en statique en s'affranchissant de la gestion de serveur de base de données. Et si c'est toujours pas clair, nous ferons d’autres meetups. :)

\n

Et grâce au soutien de Front-Commerce, un front-end JS qui communique avec des APIS e-commerce, nous publierons les vidéos des deux présentations d’ici quelques semaines, merci à eux !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/03/13/un-site-statique-avec-des-composants-grace-a-nunjucks/", "url": "https://jamstatic.fr/2018/03/13/un-site-statique-avec-des-composants-grace-a-nunjucks/", "title": "Un site statique avec des composants à l’aide de Nunjucks", "summary": "Apprenez à construire un site statique avec des composants à l’aide d’un préprocesseur HTML.", "date_published": "2018-03-13T19:21:48+00:00","content_text": "La philosophie de la génération de site statique à l’aide d’un langage de\ntemplating et d’un langage de balisage léger comme Markdown continue d’être\ndéclinée à l’envi. Le même principe est repris ici par Chris Coyier, le créateur\nde CodePen que les développeurs front connaissent bien, pour la création\nd’un site qui liste quelques-unes des possibilités offertes\npar ce que nous appelons plus globalement la Jamstack et\nqui est ici désigné sous le nom de serverless — une des nombreuses composantes\nde ces architectures découplées.\nUn cas d’étude très simple qui pourrait vous donner des idées. Aucune\nconfiguration puisque c'est un service en ligne payant qui est utilisé ici, mais\non pourrait tout aussi bien utiliser le générateur open source\nEleventy par exemple, qui utilise aussi\nNunjucks.\nIl est de plus en plus courant de nos jours de bâtir des sites avec des\ncomposants et c'est une très bonne idée. Plutôt que de construire les pages les\nunes après les autres, nous développons un système de composants (comme un\nformulaire de recherche, un carte d’article, un menu, un pied de page) et nous\nassemblons le site avec ces composants.\nDes frameworks JavaScript comme React ou Vue reposent en grande partie sur ce\nprincipe. Mais ce n'est pas parce que vous n'utilisez pas de JavaScript côté\nclient pour développer votre site que vous devez renoncer à l’idée d’utiliser\ndes composants. En utilisant un préprocesseur HTML, nous pouvons monter un site\nstatique et bénéficier également de le possibilité d’abstraire notre site et son\ncontenu sous forme de composants réutilisables.\nLes sites statiques font fureur actuellement, et à juste titre, car ils sont\nrapides, sécurisés et pas cher à héberger. Croyez-le ou pas mais même Smashing\nMagazine est un site statique !\nRegardons de plus près un site que j'ai monté récemment à l’aide de cette\ntechnique. J'ai utilisé CodePen Projects pour\nle développer qui supporte Nunjucks comme\npréprocesseur, ce qui est parfait pour faire le job.\nUn site de quatre pages avec un entête, une navigation et un pied de page consistants\nC’est un microsite. Nul besoin de passer\npar CMS capable de gérer des centaines de pages, ni de JavaScript pour ajouter\nde l’interaction. Par contre il faut qu'une poignée de pages partage la même\nmise en page.\n\n\n\n\n\nHTML n'apporte pas encore de réponse à ce problème. Nous avons besoin de pouvoir\nfaire des imports. Les langages comme PHP permettent cela avec\n<?php include \"header.php\"; ?>, mais PHP n'est pas disponible (à dessein) chez\nles hébergeurs de sites statiques et HTML ne peut encore rien pour nous.\nHeureusement nous pouvons préprocesser nos inclusions à l’aide d’un langage de\ntemplating comme Nunjucks.\n\n\n\n\n\nCela fait parfaitement sens ici de créer un gabarit de page, qui inclus des\nmorceaux de HTML pour le haut de page, la navigation et le pied de page. Le\nconcept de blocs de Nunjucks nous permet d’insérer du contenu à cet endroit\nlorsque nous utilisons le gabarit de page.\n<head>\n <meta charset=\"UTF-8\" \/>\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" \/>\n <title>The Power of Serverless<\/title>\n <link rel=\"stylesheet\" href=\"\/styles\/style.processed.css\" \/>\n<\/head>\n\n<body>\n {% include \".\/template-parts\/_header.njk\" %} {% include\n \".\/template-parts\/_nav.njk\" %} {% block content %} {% endblock %} {% include\n \".\/template-parts\/_footer.njk\" %}\n<\/body>\nVous remarquerez que les fichiers inclus sont commencent par un tiret bas et\npossèdent l’extension .njk. Ce n'est pas obligatoire, ils pourraient se nommer\nheader.html ou icons.svg mais ils sont nommés ainsi car premièrement c'est\nune convention de nommage qu'on rencontre souvent pour les fichiers partiels.\nDans CodePen, cela signifie qu'ils ne seront pas compilés tous seuls, et\ndeuxièmement utiliser l’extention .njk nous permettra de faire plus de choses\navec Nunjucks si besoin.\nRien de spécial dans ces morceaux de fichiers. Ce sont simplement des petits\nbouts de HTML destinés à être utilisés sur toutes nos pages.\n<footer>\n <p>Ceci est un simple pied de page, les gens. Circulez, y’a rien à voir.<\/p>\n<\/footer>\nDe cette manière, un simple changement dans ces fichiers et il sera appliqué sur\ntoutes nos pages.\nUtiliser un seul gabarit pour nos pages\nMaintenant nous pouvons créer un fichier pour chacune de nos pages. Commençons\nquand même par index.njk , qui sera automatiquement traité pour créer un\nfichier index.html dans CodePen project à chaque enregistrement.\n\n\n\n\n\nVoici ce que nous pourrions écrirer dans le fichier index.njk pour appliquer\nle gabarit de page et ajouter du contenu dans le bloc principal :\n{% extends \"_layout.njk\" %}\n\n{% block content %}\n<h1>Bonjour, monde!<\/h1>\n{% endblock %}\nÇa suffit pour avoir une page d’accueil fonctionnelle. Sympa ! On peut faire\npareil pour chacune des autres pages, le contenu du bloc sera simplement\ndifférent, et nous aurons un petit site de quatre pages facile à maintenir.\n\n\n\n\n\nEntre nous soit dit, je ne suis pas persuadé que ces petits morceaux\nréutilisables soient des composants à proprement parlé. Nous sommes simplement\nefficients et nous découpons notre gabarit en petits morceaux. Je pense qu'un\ncomposant est plutôt quelque chose qui accepte des données en entrée et génère\nune version unique de lui-même avec ces données. Nous allons y venir.\nRendre la navigation active\nMaintenant que nous avons des morceaux de HTML répétés à l’identique sur nos\npages, pouvons-nous appliquer un style CSS unique aux entrées indiviudelles de\nla navigation pour identifier la page courante ? Nous pourrions le faire avec\nJavaScript en regardant la valeur retournée par window.location par exemple,\nmais nous pouvons nous passer de JavaScript pour cela. Le truc c'est d’ajouter\nune class unique pour chaque page sur l’élément <body> et de la styler avec\nCSS.\nDans notre fichier _layout.njk nous allons générer un nom de classe à l’aide\nd’une variable :\n<body class=\"{{ body_class }}\"><\/body>\n\n\n\nEt avant d’appliquer le gabarit sur chaque page, nous définissons cette variable\n\n\n\n\n\n{% set body_class = \"home\" %} {% extends \"_layout.njk\" %}\nImaginons que notre navigation soit structurée de la sorte :\n<nav class=\"site-nav\">\n <ul>\n <li class=\"nav-home\">\n <a href=\"\/\"> Home <\/a>\n …\n <\/li>\n <\/ul>\n<\/nav>\nNous pouvons maintenant cibler ce lien et lui appliquer un style spécifique en\nécrivant :\nbody.home .nav-home a,\nbody.services .nav-services a {\n \/* continue matching classes for all pages… *\/\n \/* unique active state styling *\/\n}\n\nOh, c'est quoi ces icônes ? Ce sont simplement des fichiers .svg déposés\ndans un dossier et inclus de la sorte :\n{% include \"..\/icons\/cloud.svg\" %}\nCela me permet de les styler ainsi :\nsvg {\n fill: white;\n}\nEn partant du principe que les éléments SVG du fichier n'ont pas déjà un\nattribut fill de défini.\nRédiger du contenu en Markdown\nLa page d’accueil de mon site affiche un gros bloc de contenu. Je pourrais\nécrire et maintenir cela en HTML, mais il est parfois bon de\nlaisser ce genre de chose à Markdown.\nMarkdown est plus léger et un peu plus lisible lorsqu'il y a beaucoup de texte.\nRien de plus simple dans CodePen Projects. Je crée un fichier avec l’extension\n.md qui sera automatiquement transformé en HTML avant d’être inclus dans le\nfichier index.njk.\n\n{% block content %}\n<main class=\"centered-text-column\">{% include \"content\/about.html\" %}<\/main>\n{% endblock %}\nDévelopper de vrais composants\nPartons du principe que les composants sont des modules réutilisables à qui on\ninjecte des données lors de leur création. Dans des frameworks comme Vue, vous\nutiliseriez des\nfichiers uniques par composants,\nqui sont des morceaux isolés de HTML modelé, de CSS au périmètre limité et de\nJavaScript spécifique au composant. C’est super cool, mais notre microsite n'a\npas besoin de quelque chose d’aussi sophistiqué.\nNous avons besoin de créer des \"cartes\" qui utilisent un modèle simple, on peut\npar exemple faire quelque chose comme :\n\n\n\n\n\nPour créer un tel composant dans Nunjucks, il faut utilise ce qu'on appelle des\nMacros. Les Macros sont\nd’une simplicité exquise. C’est comme des fonctions pour HTML !\n{% macro card(title, content) %}\n<div class=\"card\">\n <h2>{{ title }}<\/h2>\n <p>{{ content }}<\/p>\n<\/div>\n{% endmacro %}\nPuis vous les appelez comme bon vous semble :\n{{ card('My Module', 'Lorem ipsum whatever.') }}\nL'idée générale est de séparer les données et le balisage. Cela nous donne\ndes bénéfices concrets et assez clairs :\n\nSi nous devons changer le HTML, nous pouvons le faire dans la macro et le changement sera reporté partout où la macro est utilisée.\nLa donnée n'est pas mélangée avec le balisage\nLa donnée pourrait venir de n'importe où ! Nous pouvons passer la donnée\ndirectement lors de l’appel comme nous l’avons fait ci-dessus. Ou bien nous\npouvons référencer des données en JSON et boucler dessus. Je suis sûr qu'on\npourrait mettre en place un système dans lequel des données JSON proviennent\nd’un CMS headless, d’un processus de\ngénération, d’une fonction serverless, d’une tâche cron ou de ce que vous\nvoulez.\n\nMaintenant que nous avons juste ce dont nous avons besoin, des cartes répétables\nqui combinent des données et du balisage :\n\n\n\n\n\nCréer autant de composants que vous voulez\nVous pouvez partir de ce principe et l’appliquer à l’envi. Imaginez par exemple\nque Bootstrap est essentiellement des bouts des CSS qui suivent des patrons en\nHTML qui définissent leur utilisation. Vous pourriez transformer tous les\npatrons du framework en macro et les appeler en fonction de vos besoins. L'idée\nest celle d’un\nframework de composants.\nVous pouvez imbriquer les composants si ça vous chante, et tendre vers quelque\nchose qui ressemble à la philosophie du\ndesign atomique.\nNunjucks offre également une couche de logique, qui fait que vous pouvez créer\ndes composants conditionnels et des variations en passant différents paramètres.\nDans le petit site que j'ai crée, j'ai\ncréé une autre macro pour la section idées du site car les données utilisées et\nle design de la carte sont légèrement différents.\n\n\n\n\n\nUn avis rapide sur les sites statiques\nSi la plupart des sites pourraient bénéficier d’une architecture à base de\ncomposants, tous les sites ne sont pas faits pour être statiques. Je travaille\nsur beaucoup de sites pour lesquels utiliser un langage côté serveur est\napproprié et utile.\nUn de mes sites, CSS-Tricks, propose des trucs comme\nun compte utilisateur avec un système de permissions complexe : forums,\ncommentaires, ecommerce. Bien que toutes ces fonctionnalités n'empêchent pas de\ntravailler en statique, je suis souvent bien content d’avoir une base de données\net des langages côté serveur pour travailler. Cela me permet de développer ce\nsont j'ai besoin et de tout avoir au même endroit.\nAllez de l’avant et passer au statique\nRappelez-vous qu'un des bénéfices de développer le site comme nous l’avons fait\ndans cet article est qu'au final nous obtenons quelques fichiers statiques.\nFaciles à héberger, performants et sécurisés. Pourtant, nous avons pu travailler\nde manière sympa et efficace. Ce site sera simple à mettre à jour par la suite…\n\nLe projet final est un microsite nommé Le pouvoir du Serverless pour les\ndéveloppeurs Front-End (https:\/\/thepowerofserverless.info\/).\nL'hébergement de fichier statique fait partie selon moi du mouvement\nserverless.\nTout le code est visible (et vous pouvez même en faire une copie pour vous)\ndirectement dans CodePen.\nIl est maintenu, généré et\nhébergé entièrement sur\nCodePen à l’aide de CodePen Projects.\nCodePen Projects s'occupe de toute la partie\nNunjucks dont nous avons parlé ici,\nainsi que de la compilation Sass et de l’hébergement des images, que j'ai\nutilisé pour le site. Vous pourriez faire la même chose avec par exemple un\nprocess de génération basé sur Gulp voire Grunt par exemple.\nVoici un modèle de départ pour un tel projet\nque vous pourriez utiliser.\n", "content_html": "\n

Il est de plus en plus courant de nos jours de bâtir des sites avec des\ncomposants et c'est une très bonne idée. Plutôt que de construire les pages les\nunes après les autres, nous développons un système de composants (comme un\nformulaire de recherche, un carte d’article, un menu, un pied de page) et nous\nassemblons le site avec ces composants.

\n

Des frameworks JavaScript comme React ou Vue reposent en grande partie sur ce\nprincipe. Mais ce n'est pas parce que vous n'utilisez pas de JavaScript côté\nclient pour développer votre site que vous devez renoncer à l’idée d’utiliser\ndes composants. En utilisant un préprocesseur HTML, nous pouvons monter un site\nstatique et bénéficier également de le possibilité d’abstraire notre site et son\ncontenu sous forme de composants réutilisables.

\n

Les sites statiques font fureur actuellement, et à juste titre, car ils sont\nrapides, sécurisés et pas cher à héberger. Croyez-le ou pas mais même Smashing\nMagazine est un site statique !

\n

Regardons de plus près un site que j'ai monté récemment à l’aide de cette\ntechnique. J'ai utilisé CodePen Projects pour\nle développer qui supporte Nunjucks comme\npréprocesseur, ce qui est parfait pour faire le job.

\n

Un site de quatre pages avec un entête, une navigation et un pied de page consistants

\n

C’est un microsite. Nul besoin de passer\npar CMS capable de gérer des centaines de pages, ni de JavaScript pour ajouter\nde l’interaction. Par contre il faut qu'une poignée de pages partage la même\nmise en page.

\n\n\n\n\"Un\n\n

HTML n'apporte pas encore de réponse à ce problème. Nous avons besoin de pouvoir\nfaire des imports. Les langages comme PHP permettent cela avec\n<?php include \"header.php\"; ?>, mais PHP n'est pas disponible (à dessein) chez\nles hébergeurs de sites statiques et HTML ne peut encore rien pour nous.\nHeureusement nous pouvons préprocesser nos inclusions à l’aide d’un langage de\ntemplating comme Nunjucks.

\n\n\n\n\"L'import\n\n

Cela fait parfaitement sens ici de créer un gabarit de page, qui inclus des\nmorceaux de HTML pour le haut de page, la navigation et le pied de page. Le\nconcept de blocs de Nunjucks nous permet d’insérer du contenu à cet endroit\nlorsque nous utilisons le gabarit de page.

\n
<head>\n  <meta charset=\"UTF-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n  <title>The Power of Serverless</title>\n  <link rel=\"stylesheet\" href=\"/styles/style.processed.css\" />\n</head>\n\n<body>\n  {% include \"./template-parts/_header.njk\" %} {% include\n  \"./template-parts/_nav.njk\" %} {% block content %} {% endblock %} {% include\n  \"./template-parts/_footer.njk\" %}\n</body>
\n

Vous remarquerez que les fichiers inclus sont commencent par un tiret bas et\npossèdent l’extension .njk. Ce n'est pas obligatoire, ils pourraient se nommer\nheader.html ou icons.svg mais ils sont nommés ainsi car premièrement c'est\nune convention de nommage qu'on rencontre souvent pour les fichiers partiels.\nDans CodePen, cela signifie qu'ils ne seront pas compilés tous seuls, et\ndeuxièmement utiliser l’extention .njk nous permettra de faire plus de choses\navec Nunjucks si besoin.

\n

Rien de spécial dans ces morceaux de fichiers. Ce sont simplement des petits\nbouts de HTML destinés à être utilisés sur toutes nos pages.

\n
<footer>\n  <p>Ceci est un simple pied de page, les gens. Circulez, y’a rien à voir.</p>\n</footer>
\n

De cette manière, un simple changement dans ces fichiers et il sera appliqué sur\ntoutes nos pages.

\n

Utiliser un seul gabarit pour nos pages

\n

Maintenant nous pouvons créer un fichier pour chacune de nos pages. Commençons\nquand même par index.njk , qui sera automatiquement traité pour créer un\nfichier index.html dans CodePen project à chaque enregistrement.

\n\n\n\n\"Démarrer\n\n

Voici ce que nous pourrions écrirer dans le fichier index.njk pour appliquer\nle gabarit de page et ajouter du contenu dans le bloc principal :

\n
{% extends \"_layout.njk\" %}\n\n{% block content %}\n<h1>Bonjour, monde!</h1>\n{% endblock %}
\n

Ça suffit pour avoir une page d’accueil fonctionnelle. Sympa ! On peut faire\npareil pour chacune des autres pages, le contenu du bloc sera simplement\ndifférent, et nous aurons un petit site de quatre pages facile à maintenir.

\n\n\n\n\"Le\n\n

Entre nous soit dit, je ne suis pas persuadé que ces petits morceaux\nréutilisables soient des composants à proprement parlé. Nous sommes simplement\nefficients et nous découpons notre gabarit en petits morceaux. Je pense qu'un\ncomposant est plutôt quelque chose qui accepte des données en entrée et génère\nune version unique de lui-même avec ces données. Nous allons y venir.

\n

Rendre la navigation active

\n

Maintenant que nous avons des morceaux de HTML répétés à l’identique sur nos\npages, pouvons-nous appliquer un style CSS unique aux entrées indiviudelles de\nla navigation pour identifier la page courante ? Nous pourrions le faire avec\nJavaScript en regardant la valeur retournée par window.location par exemple,\nmais nous pouvons nous passer de JavaScript pour cela. Le truc c'est d’ajouter\nune class unique pour chaque page sur l’élément <body> et de la styler avec\nCSS.

\n

Dans notre fichier _layout.njk nous allons générer un nom de classe à l’aide\nd’une variable :

\n
<body class=\"{{ body_class }}\"></body>
\n\n\n\n\n\n\n\n\n
Et avant d’appliquer le gabarit sur chaque page, nous définissons cette variable
\n
{% set body_class = \"home\" %} {% extends \"_layout.njk\" %}
\n

Imaginons que notre navigation soit structurée de la sorte :

\n
<nav class=\"site-nav\">\n  <ul>\n    <li class=\"nav-home\">\n      <a href=\"/\"> Home </a>\n      …\n    </li>\n  </ul>\n</nav>
\n

Nous pouvons maintenant cibler ce lien et lui appliquer un style spécifique en\nécrivant :

\n
body.home .nav-home a,\nbody.services .nav-services a {\n  /* continue matching classes for all pages… */\n  /* unique active state styling */\n}
\n\"Styler\n

Oh, c'est quoi ces icônes ? Ce sont simplement des fichiers .svg déposés\ndans un dossier et inclus de la sorte :

\n
{% include \"../icons/cloud.svg\" %}
\n

Cela me permet de les styler ainsi :

\n
svg {\n  fill: white;\n}
\n

En partant du principe que les éléments SVG du fichier n'ont pas déjà un\nattribut fill de défini.

\n

Rédiger du contenu en Markdown

\n

La page d’accueil de mon site affiche un gros bloc de contenu. Je pourrais\nécrire et maintenir cela en HTML, mais il est parfois bon de\nlaisser ce genre de chose à Markdown.\nMarkdown est plus léger et un peu plus lisible lorsqu'il y a beaucoup de texte.

\n

Rien de plus simple dans CodePen Projects. Je crée un fichier avec l’extension\n.md qui sera automatiquement transformé en HTML avant d’être inclus dans le\nfichier index.njk.

\n\"Les\n
{% block content %}\n<main class=\"centered-text-column\">{% include \"content/about.html\" %}</main>\n{% endblock %}
\n

Développer de vrais composants

\n

Partons du principe que les composants sont des modules réutilisables à qui on\ninjecte des données lors de leur création. Dans des frameworks comme Vue, vous\nutiliseriez des\nfichiers uniques par composants,\nqui sont des morceaux isolés de HTML modelé, de CSS au périmètre limité et de\nJavaScript spécifique au composant. C’est super cool, mais notre microsite n'a\npas besoin de quelque chose d’aussi sophistiqué.

\n

Nous avons besoin de créer des \"cartes\" qui utilisent un modèle simple, on peut\npar exemple faire quelque chose comme :

\n\n\n\n\"Créer\n\n

Pour créer un tel composant dans Nunjucks, il faut utilise ce qu'on appelle des\nMacros. Les Macros sont\nd’une simplicité exquise. C’est comme des fonctions pour HTML !

\n
{% macro card(title, content) %}\n<div class=\"card\">\n  <h2>{{ title }}</h2>\n  <p>{{ content }}</p>\n</div>\n{% endmacro %}
\n

Puis vous les appelez comme bon vous semble :

\n
{{ card('My Module', 'Lorem ipsum whatever.') }}
\n

L'idée générale est de séparer les données et le balisage. Cela nous donne\ndes bénéfices concrets et assez clairs :

\n
    \n
  1. Si nous devons changer le HTML, nous pouvons le faire dans la macro et le changement sera reporté partout où la macro est utilisée.
    2. \n
  2. La donnée n'est pas mélangée avec le balisage
    3. \n
  3. La donnée pourrait venir de n'importe où ! Nous pouvons passer la donnée\ndirectement lors de l’appel comme nous l’avons fait ci-dessus. Ou bien nous\npouvons référencer des données en JSON et boucler dessus. Je suis sûr qu'on\npourrait mettre en place un système dans lequel des données JSON proviennent\nd’un CMS headless, d’un processus de\ngénération, d’une fonction serverless, d’une tâche cron ou de ce que vous\nvoulez.
    4. \n
\n

Maintenant que nous avons juste ce dont nous avons besoin, des cartes répétables\nqui combinent des données et du balisage :

\n\n\n\n\"Le\n\n

Créer autant de composants que vous voulez

\n

Vous pouvez partir de ce principe et l’appliquer à l’envi. Imaginez par exemple\nque Bootstrap est essentiellement des bouts des CSS qui suivent des patrons en\nHTML qui définissent leur utilisation. Vous pourriez transformer tous les\npatrons du framework en macro et les appeler en fonction de vos besoins. L'idée\nest celle d’un\nframework de composants.

\n

Vous pouvez imbriquer les composants si ça vous chante, et tendre vers quelque\nchose qui ressemble à la philosophie du\ndesign atomique.

\n

Nunjucks offre également une couche de logique, qui fait que vous pouvez créer\ndes composants conditionnels et des variations en passant différents paramètres.

\n

Dans le petit site que j'ai crée, j'ai\ncréé une autre macro pour la section idées du site car les données utilisées et\nle design de la carte sont légèrement différents.

\n\n\n\n\"Vous\n\n

Un avis rapide sur les sites statiques

\n

Si la plupart des sites pourraient bénéficier d’une architecture à base de\ncomposants, tous les sites ne sont pas faits pour être statiques. Je travaille\nsur beaucoup de sites pour lesquels utiliser un langage côté serveur est\napproprié et utile.

\n

Un de mes sites, CSS-Tricks, propose des trucs comme\nun compte utilisateur avec un système de permissions complexe : forums,\ncommentaires, ecommerce. Bien que toutes ces fonctionnalités n'empêchent pas de\ntravailler en statique, je suis souvent bien content d’avoir une base de données\net des langages côté serveur pour travailler. Cela me permet de développer ce\nsont j'ai besoin et de tout avoir au même endroit.

\n

Allez de l’avant et passer au statique

\n

Rappelez-vous qu'un des bénéfices de développer le site comme nous l’avons fait\ndans cet article est qu'au final nous obtenons quelques fichiers statiques.\nFaciles à héberger, performants et sécurisés. Pourtant, nous avons pu travailler\nde manière sympa et efficace. Ce site sera simple à mettre à jour par la suite…

\n", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/03/10/mettre-en-place-son-premier-site-sous-hugo/", "url": "https://jamstatic.fr/2018/03/10/mettre-en-place-son-premier-site-sous-hugo/", "title": "Mettre en place son premier site sous Hugo", "summary": "Créer un site statique fonctionnel sous Hugo en moins de 30 minutes", "date_published": "2018-03-10T13:57:51+00:00","content_text": "Pour créer un nouveau projet avec Hugo, Forestry propose\nun kit de démarrage en libre téléchargement. Que vous ayez déjà utilisé le\ngénérateur de site statique Hugo ou pas, ce kit est intéressant, car il propose\nune configuration complète et un workflow de développement moderne basé sur les\noutils de l’écosystème de npm.\nChris Macrae nous montre comment s'en servir\npour créer votre premier site en moins de 30 minutes.\nHugo, le générateur de site statique écrit en Go, a pris la\ncommunauté de vitesse. Il présente tous les avantages d’un générateur de site\nstatique — 100% flexible, sécurisé et rapide — mais il vole également la vedette\nquand on\ncompare ses performances avec celles de Jekyll.\nLe site de Forestry.io est d’ailleurs développé avec\nHugo.\nNous allons voir comment configurer Hugo sur votre ordinateur, comment installer\net personnaliser un thème, en ajoutant nos propres fichiers CSS et JavaScript.\nQuelle différence avec le guide de démarrage rapide de la documentation d’Hugo ?\nNous allons utiliser\nnotre kit de démarrage\nrégulièrement mis à jour qui ajoute un workflow de développement moderne à Hugo.\nSommaire\n\n1. Configurer Hugo\n2. Configurer votre site\nMettre à jour un article\nCréer un nouvel article\nUtiliser un thème\n\n\n3. Personnaliser votre site\n4. Personnaliser votre thème\nCSS & Javascript personnalisé\n\n\n5. Prochaine étape\n\n1. Configurer Hugo\nPou commencer, clonez ou\ntéléchargez notre kit de démarrage pour Hugo,\net décompressez l’archive quelque part sur votre ordinateur. Vous avez aussi\nbesoin de Node.js et d’NPM, il\nvous suffit de suivre les indications sur la\npage de téléchargement de Node si vous ne les\navez pas déjà installés.\nVous bénéficiez ainsi automatiquement d’une structure de départ pour Hugo. Dans\nnotre kit, elle est stockée dans le dossier hugo. À l’intérieur se trouvent\ndivers dossiers qui abritent le contenu de votre site, les gabarits de page et\nles fichiers CSS, JS, images, etc. L'arborescence de la structure de base\nressemble à ceci — j'ai laissé quelques fichiers et dossiers de côté de façon à\nce que ce soit plus clair :\n.\n├── hugo\/ \/\/ Le site Hugo, avec les fichiers de contenu, de données, statiques.\n| ├── .forestry\/ \/\/ rassemble les fichiers de configuration pour Forestry.io\n| ├── content\/ \/\/ Tout le contenu du site est stocké ici\n| ├── data\/ \/\/ Les fichiers de données du site au format TOML, YAML ou JSON\n| ├── layouts\/ \/\/ Vos modèles de page\n| | ├── partials\/ \/\/ Les fichiers partiels réutilisables de votre site\n| | ├── shortcodes\/ \/\/ Les fichiers shortcodes de votre site\n| ├── static\/ \/\/ Les fichiers statiques de votre site\n| | ├── css\/ \/\/ Les fichiers CSS compilés\n| | ├── img\/ \/\/ Les images du site.\n| | ├── js\/ \/\/ Les fichiers JS compilés\n| | └── svg\/ \/\/ Les fichiers SVG vont ici\n| └── config.toml \/\/ Le fichier de configuration d’Hugo\n└─── src\/\n ├── css \/\/ Les fichiers source CSS\/SCSS à compiler vers \/css\/\n └── js \/\/ Les fichiers source JS à compiler vers \/js\/\nPour démarrer le projet, ouvrez une fenêtre de terminal et positionnez-vous dans\nle dossier qui contient la structure de départ (hugo-boilerplate par défaut) :\ncd chemin\/vers\/hugo-boilerplate\/\nInstallez ensuite toutes les dépendances du projet en lançant :\nnpm install\nPour lancer le serveur de développement et ouvrir le site dans votre navigateur,\nlancez simplement :\nnpm start\n2. Configurer votre site\nNous allons commencer par ajouter de nouveaux contenus au site. Pour ce faire,\nnous allons devoir mettre à jour le contenu présent dans le dossier\nhugo\/content.\nMettre à jour un article\nCommencer par mettre à jour l’exemple d’article fourni dans notre structure de\ndépart. Ouvrez le fichier hugo\/content\/posts\/example.md dans votre éditeur de\ntexte. Il est composé d’un en-tête front matter avec un champ titre et d’un\ntexte d’exemple au format markdown.\n---\ntitle: \"Bienvenue dans Hugo !\"\n---\n\nVous trouverez la source de cet article dans le répertoire `content\/posts`.\n\nPour ajouter un nouvel article, placez un nouveau fichier dans le dossier\n`content\/posts` en respectant la nomenclature `titre-de-l-article.md` et\najoutez les métadonnées nécessaires dans l’en-tête de page Front Matter.\nJetez un œil au fichier source de cet article pour voir comment ça marche.\n\n<!--more-->\n\nHugo also offers powerful support for code snippets:\n\n ```go\n package main\n import \"fmt\"\n func print_hi(name string) {\n fmt.Println(\"Hi, \", name)\n }\n\n func main() {\n print_hi(\"Tom\")\n }\n \/\/=> prints 'Hi, Tom' to STDOUT.\n ```\n\nCheck out the [Hugo docs][hugo-docs] for more info on how to get the most\nout of Hugo. File all bugs\/feature requests at [Hugo’s GitHub\nrepo][hugo-gh]. If you have questions, you can ask them on [Hugo\nCommunity][hugo-community].\n\n[hugo-docs]: https:\/\/gohugo.io\/documentation\/\n[hugo-gh]: https:\/\/github.com\/gohugoio\/hugo\n[hugo-community]: https:\/\/discourse.gohugo.io\/\nCet article n'a pas de date ! Essayez d’en définir une en ajoutant l’entrée\nsuivante dans l’en-tête Front Matter de l’article:\ndate: \"YYYY-MM-DDTHH:MM:SS-00:00\"\nRemplacez YYYY-MM-DDTHH:MM:SS-00:00 avec une date valide, comme…\n2018-01-01T12:42:00-00:00. Si votre date se situe dans le futur, Hugo ne\ngénérera pas cet article en production.\nSauvegardez vos changements puis affichez l’article mis à jour dans votre\nnavigateur à l’adresse http:\/\/localhost:3000\/. La date\naffichée devant le titre de l’article devrait avoir été mise à jour.\nCréer un nouvel article\nMaintenant essayons de créer un nouvel article. Nous utiliserons pour cela la\ncommande fournie avec Hugo pour générer un nouvel article. Dans notre projet,\nHugo est déclaré comme une dépendance NPM, nous pouvons donc l’utiliser avec la\ncommande :\nnpm run hugo -- <command> --<param>\nCréez votre premier article en lançant :\nnpm run hugo -- new posts\/mon-premier-article.md\nCela va créer un nouvel article au format markdown dans\nhugo\/content\/posts\/mon-premier-article.md. Ouvrez ce fichier dans votre\néditeur de texte favori.\n---\ntitle: \"Mon Premier Article\"\ndate: \"2018-03-09T14:24:17-04:00\"\ndraft: true\n---\n\nCe fichier comporte un en-tête Front Matter (des métadonnées structurées\nrelatives à la page) dont on peut tirer parti dans les gabarits de page. Sous le\nfront matter, nous pouvons ajouter du contenu au format markdown :\nAjoutez par exemple le contenu suivant dans le fichier et sauvegardez vos\nchangements :\n## Bienvenue\n\nPratique ce modèle de projet _Hugo_. j'espère que vous appréciez ce guide !\nVous pouvez voir l’article mis à jour dans votre navigateur à l’adresse\nhttp:\/\/localhost:3000\/posts\/mon-premier-article\/.\nUtiliser un thème\nPour le moment votre nouveau site n'est pas très beau. Remédions à cela en\najoutant un thème issu de\nla galerie de thèmes de Hugo, développé par un des\nmeilleurs contributeurs de la communauté.\n\n\n\n\n\n\nLe thème Casper de @vjeantet\n\nNous allons utiliser le thème\nCasper de\n@vjeantet. Pour ce faire nous allons ajouter le\nthème dans le dossier hugo\/themes, plus exactement dans le dossier\nhugo\/themes\/hugo-theme-casper\/.\nClonez ou\ntéléchargez le thème\net décompressez l’archive dans hugo\/themes\/hugo-theme-casper\/.\nEnsuite, mettez à jour la configuration du site aves les options de\nconfiguration spécifiques au thème.\nOuvrez le fichier hugo\/config.toml dans votre éditeur de texte favori et\nremplacer son contenu par celui-ci :\nbaseURL= \"\/\"\nlanguageCode= \"fr\"\ntitle= \"Hugo Boilerplate\"\npaginate = 5\ncopyright = \"Tous droits réservés - 2018\"\ntheme = \"hugo-theme-casper\"\ndisableKinds = [\"taxonomy\", \"taxonomyTerm\"]\n\n[params]\n description = \"Bien démarrrer avec Hugo\"\n metadescription = \"Utilisé dans la balise meta 'description' pour l’accueil et les pages d’index, faute de quoi c'est l’entrée 'description' du front matter de la page qui sera utilisé.\"\n cover = \"\"\n author = \"VOTRE_NOM\"\n authorlocation = \"Terre, Galaxie de la Voie Lactée\"\n authorwebsite = \"\"\n authorbio= \"\"\n logo = \"\"\n hjsStyle = \"default\"\n paginatedsections = [\"posts\"]\nReportez-vous à la\ndocumentation du thème\npour prendre connaissance de toutes les options de configuration disponibles.\nPour finir, supprimez les exemples de gabarits de page fournis avec notre modèle\nde départ. Pour cela lancez la commande :\nrm -r hugo\/layouts\/\nRegardez maintenant dans votre navigateur et vérifiez que votre site a bien été\nmis à jour !\n3. Personnaliser votre site\nMaintenant que nous avons mis en place un site fonctionnel avec un thème, vous\navez probablement envie de le personnaliser.\nNous allons commencer par éditer les paramètres du site dans le fichier\nhugo\/config.toml. Mettez à jour les valeurs suivantes comme bon vous semble :\n\ntitle = \"Hugo Boilerplate\"\ndescription = \"Bien démarrer avec Hugo\nmetadescription = \"Utilisé dans la balise meta 'description' pour l’accueil et les pages d’index, faute de quoi c'est l’entrée 'description' du front matter de la page qui sera utilisé\"\nauthor = \"VOTRE_NOM\"\n\n\n\n\n\n\n\nLe thème Casper avec du contenu et les styles par défaut\n\nBien, ajoutons maintenant une image de fond pour la bannière d’en-tête. Dans le\nfichier hugo\/config.toml, vous trouverez une section [params]. Modifiez le\nparamètre cover pour qu'il ait la valeur \/img\/darius-soodmand-116253.jpg,\nsauvegardez vos changements.\n\n\n\n\n\n\nAjout d’une image de fond\n\nRetournons maintenant voir notre site dans le navigateur. C’est déjà mieux, mais\nil y a encore du travail.\n4. Personnaliser votre thème\nMaintenant que vous avez adapté le site pour le personnaliser en peu, nous\nallons nous attarder sur l’aspect le plus puissant d’Hugo et de ce kit de\ndémarrage: un templating simple et puissant.\nNous venons d’ajouter le thème Casper au site, ce qui permet à Hugo d’utiliser\ntous les gabarits HTML présents dans le dossier\nhugo\/themes\/hugo-theme-casper\/layouts\/ lors de la génération du site.\nNous allons maintenant étendre le thème grâce à l’héritage de gabarits\nd’Hugo.\nTous les fichiers de gabarits présents dans le dossier hugo\/layouts\/\nsurchargeront n'importe quel gabarit du même nom présent dans le répertoire des\ngabarits du thème, nous permettant ainsi de personnaliser notre site sans\ntoucher au thème d’origine.\nCSS & Javascript personnalisé\nÀ côté d’Hugo, ce kit de démarrage fourni un serveur de développement qui va\npost-traiter automatiquement les fichiers CSS et JS pour le navigateur. Tous les\nfichiers CSS, JS, images présents dans le dossier src\/ seront traités\nautomatiquement et déplacés dans le dossier hugo\/static\/.\nAjoutons-les à notre thème de manière à pouvoir le personnaliser comme nous\nvoulons. Nous allons copier des fichiers de gabarits du thème et ajouter les\nfichiers CSS et JS personnalisés de notre kit dans ces gabarits.\nPremièrement, nous allons copier le fichier partiel header.html du thème dans\nle dossier hugo\/layouts\/partials\/ :\nmkdir -p hugo\/layouts\/partials\/\ncp hugo\/themes\/hugo-theme-casper\/layouts\/partials\/header.html hugo\/layouts\/partials\/header.html\nOuvrez le fichier hugo\/layouts\/partials\/header.html dans votre éditeur de\ntexte et repérez les lignes suivantes :\n<link rel=\"stylesheet\" type=\"text\/css\" href=\"{{ \"css\/screen.css\" | relURL}}\" \/>\n<link rel=\"stylesheet\" type=\"text\/css\" href=\"{{ \"css\/nav.css\" | relURL}}\" \/>\nAjoutez en dessous la ligne suivante :\n<link rel=\"stylesheet\" type=\"text\/css\" href=\"{{ \"css\/styles.min.css\" | relURL}}\"\n\/>\nEnsuite, recopions le fichier partiel footer.html dans le dossier\nhugo\/layouts\/partials\/ de manière à pouvoir ajouter notre fichier JS\npersonnalisé :\ncp hugo\/themes\/hugo-theme-casper\/layouts\/partials\/footer.html hugo\/layouts\/partials\/footer.html\nOuvrez maintenant le fichier hugo\/layouts\/partials\/footer.html et repérez les\nlignes suivantes :\n<script type=\"text\/javascript\" src=\"{{\"js\/jquery.js\" | relURL}}\"><\/script>\n<script type=\"text\/javascript\" src=\"{{\"js\/jquery.fitvids.js\" | relURL}}\"><\/script>\n<script type=\"text\/javascript\" src=\"{{\"js\/index.js\" | relURL}}\"><\/script>\nAjoutez juste en dessous:\n<script type=\"text\/javascript\" src=\"{{\"js\/scripts.min.js\" | relURL}}\"><\/script>\nMaintenant tout notre code CSS et JS personnalisé sera utilisé sur le site.\nFaisons un essai en augmentant la hauteur de l’en-tête principal. Ouvrez le\nfichier src\/css\/styles.css et ajoutez le code suivant à la fin du fichier :\n.tag-head.main-header {\n height: 80vh;\n}\n\n\n\n\n\n\nLe résultat final\n\nAdmirez le résultat final dans votre navigateur !\n5. Prochaine étape\nVous êtes maintenant prêt·e à commencer à créer un site statique avec Hugo !\nVous pouvez continuer à utiliser le thème Casper ou repartir du début en\nutilisant les modèles du répertoire hugo\/layouts\/.\nLes fichiers des modèles de gabarits de page se trouvent dans le\ndépôt de notre kit de démarrage\nsi vous souhaitez repartir de zéro.\nPour en apprendre un peu plus sur Hugo, reportez-vous aux sections suivantes de\nla documentation officielle :\n\nL'organisation des contenus dans Hugo\nIntroduction au langage de templating d’Hugo\nLes options de configuration d’Hugo\n\nNous verrons dans un prochain article comment configurer le versionnement avec\nGit pour faciliter l’intégration continue et le déploiement chez différents\nhébergeurs avec Forestry, un CMS pour les sites statiques générés avec Hugo ou\nJekyll.", "content_html": "\n

Hugo, le générateur de site statique écrit en Go, a pris la\ncommunauté de vitesse. Il présente tous les avantages d’un générateur de site\nstatique — 100% flexible, sécurisé et rapide — mais il vole également la vedette\nquand on\ncompare ses performances avec celles de Jekyll.\nLe site de Forestry.io est d’ailleurs développé avec\nHugo.

\n

Nous allons voir comment configurer Hugo sur votre ordinateur, comment installer\net personnaliser un thème, en ajoutant nos propres fichiers CSS et JavaScript.

\n

Quelle différence avec le guide de démarrage rapide de la documentation d’Hugo ?\nNous allons utiliser\nnotre kit de démarrage\nrégulièrement mis à jour qui ajoute un workflow de développement moderne à Hugo.

\n

Sommaire

\n
\n

1. Configurer Hugo

\n

Pou commencer, clonez ou\ntéléchargez notre kit de démarrage pour Hugo,\net décompressez l’archive quelque part sur votre ordinateur. Vous avez aussi\nbesoin de Node.js et d’NPM, il\nvous suffit de suivre les indications sur la\npage de téléchargement de Node si vous ne les\navez pas déjà installés.

\n

Vous bénéficiez ainsi automatiquement d’une structure de départ pour Hugo. Dans\nnotre kit, elle est stockée dans le dossier hugo. À l’intérieur se trouvent\ndivers dossiers qui abritent le contenu de votre site, les gabarits de page et\nles fichiers CSS, JS, images, etc. L'arborescence de la structure de base\nressemble à ceci — j'ai laissé quelques fichiers et dossiers de côté de façon à\nce que ce soit plus clair :

\n
.\n├── hugo/                  // Le site Hugo, avec les fichiers de contenu, de données, statiques.\n|   ├── .forestry/         // rassemble les fichiers de configuration pour Forestry.io\n|   ├── content/           // Tout le contenu du site est stocké ici\n|   ├── data/              // Les fichiers de données du site au format TOML, YAML ou JSON\n|   ├── layouts/           // Vos modèles de page\n|   |   ├── partials/      // Les fichiers partiels réutilisables de votre site\n|   |   ├── shortcodes/    // Les fichiers shortcodes de votre site\n|   ├── static/            // Les fichiers statiques de votre site\n|   |   ├── css/           // Les fichiers CSS compilés\n|   |   ├── img/           // Les images du site.\n|   |   ├── js/            // Les fichiers JS compilés\n|   |   └── svg/           // Les fichiers SVG vont ici\n|   └── config.toml        // Le fichier de configuration d’Hugo\n└─── src/\n     ├── css               // Les fichiers source CSS/SCSS à compiler vers /css/\n     └── js                // Les fichiers source JS à compiler vers /js/
\n

Pour démarrer le projet, ouvrez une fenêtre de terminal et positionnez-vous dans\nle dossier qui contient la structure de départ (hugo-boilerplate par défaut) :

\n

cd chemin/vers/hugo-boilerplate/

\n

Installez ensuite toutes les dépendances du projet en lançant :

\n

npm install

\n

Pour lancer le serveur de développement et ouvrir le site dans votre navigateur,\nlancez simplement :

\n

npm start

\n

2. Configurer votre site

\n

Nous allons commencer par ajouter de nouveaux contenus au site. Pour ce faire,\nnous allons devoir mettre à jour le contenu présent dans le dossier\nhugo/content.

\n

Mettre à jour un article

\n

Commencer par mettre à jour l’exemple d’article fourni dans notre structure de\ndépart. Ouvrez le fichier hugo/content/posts/example.md dans votre éditeur de\ntexte. Il est composé d’un en-tête front matter avec un champ titre et d’un\ntexte d’exemple au format markdown.

\n
---\ntitle: \"Bienvenue dans Hugo !\"\n---\n\nVous trouverez la source de cet article dans le répertoire `content/posts`.\n\nPour ajouter un nouvel article, placez un nouveau fichier dans le dossier\n`content/posts` en respectant la nomenclature `titre-de-l-article.md` et\najoutez les métadonnées nécessaires dans l’en-tête de page Front Matter.\nJetez un œil au fichier source de cet article pour voir comment ça marche.\n\n<!--more-->\n\nHugo also offers powerful support for code snippets:\n\n    ```go\n    package main\n    import \"fmt\"\n    func print_hi(name string) {\n      fmt.Println(\"Hi, \", name)\n    }\n\n    func main() {\n      print_hi(\"Tom\")\n    }\n    //=> prints 'Hi, Tom' to STDOUT.\n    ```\n\nCheck out the [Hugo docs][hugo-docs] for more info on how to get the most\nout of Hugo. File all bugs/feature requests at [Hugo’s GitHub\nrepo][hugo-gh]. If you have questions, you can ask them on [Hugo\nCommunity][hugo-community].\n\n[hugo-docs]: https://gohugo.io/documentation/\n[hugo-gh]: https://github.com/gohugoio/hugo\n[hugo-community]: https://discourse.gohugo.io/
\n

Cet article n'a pas de date ! Essayez d’en définir une en ajoutant l’entrée\nsuivante dans l’en-tête Front Matter de l’article:

\n

date: \"YYYY-MM-DDTHH:MM:SS-00:00\"

\n\n

Sauvegardez vos changements puis affichez l’article mis à jour dans votre\nnavigateur à l’adresse http://localhost:3000/. La date\naffichée devant le titre de l’article devrait avoir été mise à jour.

\n

Créer un nouvel article

\n

Maintenant essayons de créer un nouvel article. Nous utiliserons pour cela la\ncommande fournie avec Hugo pour générer un nouvel article. Dans notre projet,\nHugo est déclaré comme une dépendance NPM, nous pouvons donc l’utiliser avec la\ncommande :

\n

npm run hugo -- <command> --<param>

\n

Créez votre premier article en lançant :

\n

npm run hugo -- new posts/mon-premier-article.md

\n

Cela va créer un nouvel article au format markdown dans\nhugo/content/posts/mon-premier-article.md. Ouvrez ce fichier dans votre\néditeur de texte favori.

\n
---\ntitle: \"Mon Premier Article\"\ndate: \"2018-03-09T14:24:17-04:00\"\ndraft: true\n---\n
\n

Ce fichier comporte un en-tête Front Matter (des métadonnées structurées\nrelatives à la page) dont on peut tirer parti dans les gabarits de page. Sous le\nfront matter, nous pouvons ajouter du contenu au format markdown :

\n

Ajoutez par exemple le contenu suivant dans le fichier et sauvegardez vos\nchangements :

\n
## Bienvenue\n\nPratique ce modèle de projet _Hugo_. j'espère que vous appréciez ce guide !
\n

Vous pouvez voir l’article mis à jour dans votre navigateur à l’adresse\nhttp://localhost:3000/posts/mon-premier-article/.

\n

Utiliser un thème

\n

Pour le moment votre nouveau site n'est pas très beau. Remédions à cela en\najoutant un thème issu de\nla galerie de thèmes de Hugo, développé par un des\nmeilleurs contributeurs de la communauté.

\n
\n\n\n\n\"Le\n\n
Le thème Casper de @vjeantet
\n
\n

Nous allons utiliser le thème\nCasper de\n@vjeantet. Pour ce faire nous allons ajouter le\nthème dans le dossier hugo/themes, plus exactement dans le dossier\nhugo/themes/hugo-theme-casper/.

\n

Clonez ou\ntéléchargez le thème\net décompressez l’archive dans hugo/themes/hugo-theme-casper/.

\n

Ensuite, mettez à jour la configuration du site aves les options de\nconfiguration spécifiques au thème.

\n

Ouvrez le fichier hugo/config.toml dans votre éditeur de texte favori et\nremplacer son contenu par celui-ci :

\n
baseURL= \"/\"\nlanguageCode= \"fr\"\ntitle= \"Hugo Boilerplate\"\npaginate = 5\ncopyright = \"Tous droits réservés - 2018\"\ntheme = \"hugo-theme-casper\"\ndisableKinds = [\"taxonomy\", \"taxonomyTerm\"]\n\n[params]\n  description = \"Bien démarrrer avec Hugo\"\n  metadescription = \"Utilisé dans la balise meta 'description' pour l’accueil et les pages d’index, faute de quoi c'est l’entrée 'description' du front matter de la page qui sera utilisé.\"\n  cover = \"\"\n  author = \"VOTRE_NOM\"\n  authorlocation = \"Terre, Galaxie de la Voie Lactée\"\n  authorwebsite = \"\"\n  authorbio= \"\"\n  logo = \"\"\n  hjsStyle = \"default\"\n  paginatedsections = [\"posts\"]
\n

Reportez-vous à la\ndocumentation du thème\npour prendre connaissance de toutes les options de configuration disponibles.

\n

Pour finir, supprimez les exemples de gabarits de page fournis avec notre modèle\nde départ. Pour cela lancez la commande :

\n
rm -r hugo/layouts/
\n

Regardez maintenant dans votre navigateur et vérifiez que votre site a bien été\nmis à jour !

\n

3. Personnaliser votre site

\n

Maintenant que nous avons mis en place un site fonctionnel avec un thème, vous\navez probablement envie de le personnaliser.

\n

Nous allons commencer par éditer les paramètres du site dans le fichier\nhugo/config.toml. Mettez à jour les valeurs suivantes comme bon vous semble :

\n\n
\n\n\n\n\"Le\n\n
Le thème Casper avec du contenu et les styles par défaut
\n
\n

Bien, ajoutons maintenant une image de fond pour la bannière d’en-tête. Dans le\nfichier hugo/config.toml, vous trouverez une section [params]. Modifiez le\nparamètre cover pour qu'il ait la valeur /img/darius-soodmand-116253.jpg,\nsauvegardez vos changements.

\n
\n\n\n\n\"Ajout\n\n
Ajout d’une image de fond
\n
\n

Retournons maintenant voir notre site dans le navigateur. C’est déjà mieux, mais\nil y a encore du travail.

\n

4. Personnaliser votre thème

\n

Maintenant que vous avez adapté le site pour le personnaliser en peu, nous\nallons nous attarder sur l’aspect le plus puissant d’Hugo et de ce kit de\ndémarrage: un templating simple et puissant.

\n

Nous venons d’ajouter le thème Casper au site, ce qui permet à Hugo d’utiliser\ntous les gabarits HTML présents dans le dossier\nhugo/themes/hugo-theme-casper/layouts/ lors de la génération du site.

\n

Nous allons maintenant étendre le thème grâce à l’héritage de gabarits\nd’Hugo.

\n

Tous les fichiers de gabarits présents dans le dossier hugo/layouts/\nsurchargeront n'importe quel gabarit du même nom présent dans le répertoire des\ngabarits du thème, nous permettant ainsi de personnaliser notre site sans\ntoucher au thème d’origine.

\n

CSS & Javascript personnalisé

\n

À côté d’Hugo, ce kit de démarrage fourni un serveur de développement qui va\npost-traiter automatiquement les fichiers CSS et JS pour le navigateur. Tous les\nfichiers CSS, JS, images présents dans le dossier src/ seront traités\nautomatiquement et déplacés dans le dossier hugo/static/.

\n

Ajoutons-les à notre thème de manière à pouvoir le personnaliser comme nous\nvoulons. Nous allons copier des fichiers de gabarits du thème et ajouter les\nfichiers CSS et JS personnalisés de notre kit dans ces gabarits.

\n

Premièrement, nous allons copier le fichier partiel header.html du thème dans\nle dossier hugo/layouts/partials/ :

\n
mkdir -p hugo/layouts/partials/\ncp hugo/themes/hugo-theme-casper/layouts/partials/header.html hugo/layouts/partials/header.html
\n

Ouvrez le fichier hugo/layouts/partials/header.html dans votre éditeur de\ntexte et repérez les lignes suivantes :

\n
<link rel=\"stylesheet\" type=\"text/css\" href=\"{{ \"css/screen.css\" | relURL}}\" />\n<link rel=\"stylesheet\" type=\"text/css\" href=\"{{ \"css/nav.css\" | relURL}}\" />
\n

Ajoutez en dessous la ligne suivante :

\n
<link rel=\"stylesheet\" type=\"text/css\" href=\"{{ \"css/styles.min.css\" | relURL}}\"\n/>
\n

Ensuite, recopions le fichier partiel footer.html dans le dossier\nhugo/layouts/partials/ de manière à pouvoir ajouter notre fichier JS\npersonnalisé :

\n
cp hugo/themes/hugo-theme-casper/layouts/partials/footer.html hugo/layouts/partials/footer.html
\n

Ouvrez maintenant le fichier hugo/layouts/partials/footer.html et repérez les\nlignes suivantes :

\n
<script type=\"text/javascript\" src=\"{{\"js/jquery.js\" | relURL}}\"></script>\n<script type=\"text/javascript\" src=\"{{\"js/jquery.fitvids.js\" | relURL}}\"></script>\n<script type=\"text/javascript\" src=\"{{\"js/index.js\" | relURL}}\"></script>
\n

Ajoutez juste en dessous:

\n
<script type=\"text/javascript\" src=\"{{\"js/scripts.min.js\" | relURL}}\"></script>
\n

Maintenant tout notre code CSS et JS personnalisé sera utilisé sur le site.

\n

Faisons un essai en augmentant la hauteur de l’en-tête principal. Ouvrez le\nfichier src/css/styles.css et ajoutez le code suivant à la fin du fichier :

\n
.tag-head.main-header {\n  height: 80vh;\n}
\n
\n\n\n\n\"Le\n\n
Le résultat final
\n
\n

Admirez le résultat final dans votre navigateur !

\n

5. Prochaine étape

\n

Vous êtes maintenant prêt·e à commencer à créer un site statique avec Hugo !

\n

Vous pouvez continuer à utiliser le thème Casper ou repartir du début en\nutilisant les modèles du répertoire hugo/layouts/.

\n\n

Pour en apprendre un peu plus sur Hugo, reportez-vous aux sections suivantes de\nla documentation officielle :

\n\n

Nous verrons dans un prochain article comment configurer le versionnement avec\nGit pour faciliter l’intégration continue et le déploiement chez différents\nhébergeurs avec Forestry, un CMS pour les sites statiques générés avec Hugo ou\nJekyll.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/02/18/presentation-eleventy/", "url": "https://jamstatic.fr/2018/02/18/presentation-eleventy/", "title": "Présentation d’Eleventy, un nouveau générateur de site statique", "summary": "Zach Leatherman explique pourquoi il a développé Eleventy, un générateur de site statique basé sur JavaScript, particulièrement flexible et qui sait se faire oublier.", "date_published": "2018-02-18T09:23:07+00:00","content_text": "L'auteur d’Eleventy, le talentueux Zach Leatherman, développeur front-end particulièrement attentif à la performance explique pourquoi il a décidé de développer à son tour un générateur de site statique. Eleventy se pose d’emblée comme une alternative intéressante à Jekyll ou aux générateurs qui reposent sur des bibliothèques JavaScript, tout en en s'affranchissant de leurs contraintes.\nEleventy est un nouveau générateur de site statique.\nSi n'êtes pas encore au fait de ce que sont les générateurs de sites statiques et des avantages qu'ils procurent, lisez ce très bon article paru dans Smashing Magazine écrit par Matt Biilmann.\nEncore un générateur de site statique ? Oui. Mais pourquoi ? Bonne question.\nEleventy a été créé pour trois raisons :\n\nFlexibilité\nParier sur JavaScript\nCe n'est pas un framework JavaScript\n\nFlexibilité\nFlexibilité du moteur de template\nEleventy vous permet d’utiliser différents moteurs de template et de migrer ainsi facilement vos contenus existants. Vos fichiers de contenu peuvent utiliser un moteur de templating différent de celui de vos gabarits de page !\nLinda fait du développement web pour ses clients. Linda maintient un ensemble de documentation transversale pour l’ensemble de ses projets qu'elle fournit en même temps que les composants front-end et les templates. Linda a codé ses documentations à l’aide du langage de templating Liquid avec Jekyll. Linda a maintenant un client qui souhaite qu'elle livre les composants sous forme de fichiers de gabarit Mustache. Facile, Linda passe de Jekyll à Eleventy car Eleventy sait gérer les deux côte-à-côte. Bien joué Linda.\n\n\n\nGénérateur de site\nClassement staticgen.com\nMoteur de templates\n\n\n\n\nJekyll\n#1\nLiquid\n\n\nHugo\n#2\nGo Template\n\n\nHexo\n#3\nEJS, Pug\n\n\nGatsby\n#4\nReact.js\n\n\n\nEleventy supporte actuellement :\n\nHTML\nMarkdown\nLiquid (used by Jekyll)\nNunjucks\nHandlebars\nMustache\nEJS\nHaml\nPug\nJavaScript Template Literals (ES2015)\n\nFlexibilité de l’arborescence de répertoires\nEleventy tient à ce que vous puissiez continuer à travailler avec l’arborescence existante de votre projet. Il n'y a aucune obligation de mettre tous vos fichiers de contenu dans un répertoire source, content ou _posts (sauf si vous le désirez). Vous dites à Eleventy où sont vos fichiers et il se débrouillera avec.\nUn simple eleventy en ligne de commande va traiter les fichiers présents dans le répertoire courant et générer un site dans un dossier _site. Vous pouvez préciser votre choix à l’aide des options --input et --output.\nTraite les fichiers du répertoire courant et génère un dossier _site\neleventy\nTraite les fichiers du dossier src et génère un dossier _gh_pages\neleventy --input=src --output=_gh_pages\nTraite les fichiers du répertoire courant et génère les fichiers au même endroit\neleventy --input=. --output=.\nTransformer un fichier à la fois\nEleventy fonctionne aussi comme un petit utilitaire permettant de traiter un seul fichier. Pour transformer le fichier README.md en README.html.\neleventy --input=README.md --output=.\nPariez sur JavaScript\nPariez toujours sur JavaScript. JavaScript vous donne accès à npm. L'écosystème d’npm est immense. Follement immense. Et il continue de gagner en popularité. Selon modulecounts.com, npm propose déjà trois fois plus de modules que son deuxième concurrent, Maven Central (Java). Quand vous souhaitez ajouter une fonctionnalité, il y a de grandes chances qu'il existe déjà un module npm pour ça.\n\n\n\nGénérateur de site\nLangage\nNombre de modules\n\n\n\n\nJekyll\nRuby\n~140,000 sur rubygems.org\n\n\nHugo\nGo\n~20,000 sur Gopm\n\n\nHexo\nJavaScript\n~580,000 sur npm\n\n\nGatsby\nJavaScript\n~580,000 sur npm\n\n\n\nEleventy n'est pas un framework JavaScript\nBien qu'Eleventy utilise JavaScript à travers node.js pour transformer les fichiers de gabarit en fichiers de contenu, il est important de savoir que (par défaut) le HTML généré n'inclut aucun fichier JavaScript client spécifique à Eleventy côté client. C’est une des facettes fondamentales des intentions et des objectifs du projet. Ce n'est pas un framework JavaScript. Nous voulons que notre contenu soit découplé autant que possible d’Eleventy, et parce Eleventy utilise des moteurs de templates indépendants d’Eleventy, cela nous permet de nous rapprocher de cet objectif.\nIl se peut que par la suite nous insérions un peu de JavaScript pour la partie client spécifique à Eleventy, mais ce ne sera pas une option activée par défaut. Bien entendu, libre à vous d’ajouter votre propre code JavaScript pour la partie client, en fonction de votre projet et de vos besoins.\nLa moindre des choses à faire est de toujours analyser ce qui est produit en sortie par les générateurs de site statique, surtout ceux qui sont très liés à des frameworks JavaScript. La majorité des frameworks JavaScript incluent du code JavaScript assez dogmatique côté client, même lorsque qu'ils utilisent le rendu côté serveur.\nCes bibliothèques peuvent être lourdes et parfois bloquer le rendu du contenu critique ou encore causer des congestions au niveau réseau dans le rendu de contenu critique avec preload.\nLa performance c'est critique. Les fichiers statiques peuvent présenter un gain de performance formidable. Pour maintenir ce niveau de performance, Eleventy vous laisse le contrôle complet sur l’inclusion de code JavaScript dans vos pages.\nTestez Eleventy !\nJ'espère que vous donnerez sa chance à Eleventy ! Installez-le !\nnpm install -g @11ty\/eleventy\nVous trouverez des tutoriels sur 11ty.dev. Dites à Zach ce que vous aimez ou que vous n'aimez pas ! il adorerait avoir vos retours.\nUne chose sympa et facile à faire que vous pouvez faire pour soutenir le projet est de le marquer d’une étoile sur GitHub. Comme la liste gigantesque des générateurs de site statique de staticgen.com est classée en fonction du nombre d’étoiles sur GitHub, ça aiderait le projet à gagner pas mal de places au classement. Merci !", "content_html": "\n

Eleventy est un nouveau générateur de site statique.

\n\n

Encore un générateur de site statique ? Oui. Mais pourquoi ? Bonne question.

\n

Eleventy a été créé pour trois raisons :

\n\n

Flexibilité

\n

Flexibilité du moteur de template

\n

Eleventy vous permet d’utiliser différents moteurs de template et de migrer ainsi facilement vos contenus existants. Vos fichiers de contenu peuvent utiliser un moteur de templating différent de celui de vos gabarits de page !

\n

Linda fait du développement web pour ses clients. Linda maintient un ensemble de documentation transversale pour l’ensemble de ses projets qu'elle fournit en même temps que les composants front-end et les templates. Linda a codé ses documentations à l’aide du langage de templating Liquid avec Jekyll. Linda a maintenant un client qui souhaite qu'elle livre les composants sous forme de fichiers de gabarit Mustache. Facile, Linda passe de Jekyll à Eleventy car Eleventy sait gérer les deux côte-à-côte. Bien joué Linda.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Générateur de siteClassement staticgen.comMoteur de templates
Jekyll#1Liquid
Hugo#2Go Template
Hexo#3EJS, Pug
Gatsby#4React.js
\n

Eleventy supporte actuellement :

\n\n

Flexibilité de l’arborescence de répertoires

\n

Eleventy tient à ce que vous puissiez continuer à travailler avec l’arborescence existante de votre projet. Il n'y a aucune obligation de mettre tous vos fichiers de contenu dans un répertoire source, content ou _posts (sauf si vous le désirez). Vous dites à Eleventy où sont vos fichiers et il se débrouillera avec.

\n

Un simple eleventy en ligne de commande va traiter les fichiers présents dans le répertoire courant et générer un site dans un dossier _site. Vous pouvez préciser votre choix à l’aide des options --input et --output.

\n

Traite les fichiers du répertoire courant et génère un dossier _site

\n
eleventy
\n

Traite les fichiers du dossier src et génère un dossier _gh_pages

\n
eleventy --input=src --output=_gh_pages
\n

Traite les fichiers du répertoire courant et génère les fichiers au même endroit

\n
eleventy --input=. --output=.
\n

Transformer un fichier à la fois

\n

Eleventy fonctionne aussi comme un petit utilitaire permettant de traiter un seul fichier. Pour transformer le fichier README.md en README.html.

\n
eleventy --input=README.md --output=.
\n

Pariez sur JavaScript

\n

Pariez toujours sur JavaScript. JavaScript vous donne accès à npm. L'écosystème d’npm est immense. Follement immense. Et il continue de gagner en popularité. Selon modulecounts.com, npm propose déjà trois fois plus de modules que son deuxième concurrent, Maven Central (Java). Quand vous souhaitez ajouter une fonctionnalité, il y a de grandes chances qu'il existe déjà un module npm pour ça.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Générateur de siteLangageNombre de modules
JekyllRuby~140,000 sur rubygems.org
HugoGo~20,000 sur Gopm
HexoJavaScript~580,000 sur npm
GatsbyJavaScript~580,000 sur npm
\n

Eleventy n'est pas un framework JavaScript

\n

Bien qu'Eleventy utilise JavaScript à travers node.js pour transformer les fichiers de gabarit en fichiers de contenu, il est important de savoir que (par défaut) le HTML généré n'inclut aucun fichier JavaScript client spécifique à Eleventy côté client. C’est une des facettes fondamentales des intentions et des objectifs du projet. Ce n'est pas un framework JavaScript. Nous voulons que notre contenu soit découplé autant que possible d’Eleventy, et parce Eleventy utilise des moteurs de templates indépendants d’Eleventy, cela nous permet de nous rapprocher de cet objectif.

\n

Il se peut que par la suite nous insérions un peu de JavaScript pour la partie client spécifique à Eleventy, mais ce ne sera pas une option activée par défaut. Bien entendu, libre à vous d’ajouter votre propre code JavaScript pour la partie client, en fonction de votre projet et de vos besoins.

\n

La moindre des choses à faire est de toujours analyser ce qui est produit en sortie par les générateurs de site statique, surtout ceux qui sont très liés à des frameworks JavaScript. La majorité des frameworks JavaScript incluent du code JavaScript assez dogmatique côté client, même lorsque qu'ils utilisent le rendu côté serveur.

\n

Ces bibliothèques peuvent être lourdes et parfois bloquer le rendu du contenu critique ou encore causer des congestions au niveau réseau dans le rendu de contenu critique avec preload.

\n

La performance c'est critique. Les fichiers statiques peuvent présenter un gain de performance formidable. Pour maintenir ce niveau de performance, Eleventy vous laisse le contrôle complet sur l’inclusion de code JavaScript dans vos pages.

\n

Testez Eleventy !

\n

J'espère que vous donnerez sa chance à Eleventy ! Installez-le !

\n
npm install -g @11ty/eleventy
\n

Vous trouverez des tutoriels sur 11ty.dev. Dites à Zach ce que vous aimez ou que vous n'aimez pas ! il adorerait avoir vos retours.

\n

Une chose sympa et facile à faire que vous pouvez faire pour soutenir le projet est de le marquer d’une étoile sur GitHub. Comme la liste gigantesque des générateurs de site statique de staticgen.com est classée en fonction du nombre d’étoiles sur GitHub, ça aiderait le projet à gagner pas mal de places au classement. Merci !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/02/09/scratch-hugo/", "url": "https://jamstatic.fr/2018/02/09/scratch-hugo/", "title": "La fonction .Scratch d’Hugo", "summary": "Pendant longtemps, la fonction Scratch a été le seul moyen d'écraser des variables en Go Templating. Elle reste toujours le meilleur moyen d'enrichir votre contexte de page ou de shortcode dans Hugo.", "date_published": "2018-02-09T19:50:50+00:00", "date_modified": "2018-08-29T15:09:47+00:00","content_text": "Vous êtes ici pour apprendre à écraser une variable dans un gabarit de page ? Bonne nouvelle, vous n'avez plus besoin de la fonction .Scratch pour cela depuis la version 0.48 d'Hugo. Malgré cela, .Scratch reste encore utile pour plein d'autres choses !\nLe contexte de Page d'Hugo n'est pas seulement la source d'information la plus importante pour vos pages, c'est aussi la source de données principale de tous vos templates. Plus souvent qu'il n'y paraît, vous aurez à ajouter vos propres variables personnalisées en plus de celles définies par défaut.\nAvec la fonction .Scratch d'Hugo, n'importe quelle Page ou Shortcode peut être enrichie avec autant de variables que nécessaire en plus de celles par défaut.\nC'est quoi Scratch ?\nScratch a été ajouté à l'origine pour contourner une limitation du langage de templating de Go, qui empêchait d'écraser des variables. Elle s'est rapidement enrichie d'autres méthodes et constitue désormais une fonctionnalité d'Hugo à part entière.\nÀ des fins de lisibilité, les extraits de code qui suivent ont des commentaires incompatibles avec le langage de template de Go. Reportez vous à la doc pour comment commenter dans Hugo.\n.Scratch.Set\nSet est utilisé pour mémoriser une valeur voire pour pouvoir surcharger simplement une valeur par la suite.\n{{ .Scratch.Set \"salutations\" \"Bonjour\" }}\n{{ if eq $ciel \"sombre\" }}\n {{ .Scratch.Set \"salutations\" \"Bonsoir\" }}\n{{ end }}\n\n{{ .Scratch.Get \"salutations\"}}\n.Scratch.Add\nCette méthode s'occupe d’ajouter ou de pousser des valeurs multiples dans une\nvariable ou une clef.\n\/\/ Pour les chaînes de caractères\n{{ .Scratch.Add \"salutations\" \"Bonjour\" }}\n{{ .Scratch.Add \"salutations\" \"Bonsoir\" }}\n\n{{ .Scratch.Get \"salutations\" }}\n\/\/ Affichera : BonjourBonsoir\nUtilisée avec slice, elle permet d’ajouter une ou plusieurs valeurs à un\ntableau.\n{{ .Scratch.Add \"salutations\" (slice \"Bonjour\") }}\n{{ .Scratch.Add \"salutations\" (slice \"Bonsoir\") }}\n{{ .Scratch.Add \"salutations\" (slice \"Aloha\" \"Buenos dias\") }}\n.Scratch.Get\nMaintenant récupérons tout ça.\n\/\/ Avec la fonction range\n{{ range where .Scratch.Get \"salutations\" }}\n<ol>\n <li>\n {{ . }}\n <\/li>\n<\/ol>\n{{ end }}\n\/\/ ☝️ Affichera une liste ordonnée avec nos 4 salutations.\n\n\/\/ Ou avec la fonction delimit\n{{ delimit (.Scratch.Get \"salutations\"), \", \" }}\n\/\/ ☝️ Affichera Bonjour, Bonsoir, Aloha, Buenos dias\n.Scratch.Delete1\nSupprime la paire clé\/valeur du contexte.\nLors de l'utilisation de .Scratch.Add dans une boucle, .Scratch.Delete est pratique pour réinitialiser une valeur.\n{{ .Scratch.Delete \"salutations\" }}\nnewScratch2\nCe n'est pas une méthode issue de Scratch, mais une fonction qui permet la création d'une instance locale de Scratch dans un template.\n{{ $headerScratch := newScratch }}\n{{ $headerScratch.Add \"brand_image\" .Params.image }}\nManipuler des tableaux et des maps\n.Scratch.SetInMap\nCette fonction-là permet de cibler la clef d’un tableau et de lui assigner une\nnouvelle valeur.\nElle prend comme premier paramètre votre clef .Scratch, comme second paramètre\nla clef issue du tableau ou de la map, le troisième étant la valeur que vous\ndéfinissez.\nSi vous ne connaissez pas dict je\nvous explique tout ça\ndans cet article\n{{ .Scratch.Add \"salutations\" (dict \"english\" \"Hello\" \"french\" \"Bonjour\") }}\n\n{{ .Scratch.SetInMap \"salutations\" \"english\" \"Howdy 🤠\" }}\n\n\/\/ Nous avons modifié la valeur de la clef en anglais de Hello à Howdy 🤠 !\nAttention au périmètre et au contexte…\n.Scratch n'est disponible que pour l’objet page ou l’objet shortcode. Vous ne\npouvez pas l’utiliser sur un autre élément.\nSouvenez-vous que si vous vous trouvez à l’intérieur d’une boucle range dans\nvotre page d’index, alors le .Scratch de votre page d’index sera $.Scratch\nalors que la page courante que vous traitez dans votre boucle sera .Scratch.\nRetenez également que vous pouvez affecter une paire clef-valeur à .Scratch\ndepuis n'importe où, même dans un fichier partiel du moment que vous lui passez\nle contexte. Heeeeein? Prenons un exemple concret pour illustrer les dangers qui\nvous guettent avec l’utilisation de .Scratch et du contexte.\nUn exemple classe avec .Scratch\nJe trouve ça bien pratique d’affecter des classes à mon élément body (comme le\nfait WordPress) pour pouvoir faire des ajustements CSS\/JavaScript en fonction\nde la page sur laquelle on se trouve.\nJe trouvais ça très fastidieux à faire avec Hugo, jusqu'à ce que je comprenne\ncomment utiliser .Scratch.\nJe veux ajouter une classe CSS rp-body à toutes mes pages ainsi que la valeur\nde .Section à mes classes.\nEt seule la page d’accueil devrait hériter de la classe rp-home.\nJe pourrais écrire ça une bonne foi pour toute, dans un fichier partiel ou un\nfichier de gabarit de page qui comprend l’ouverture de la balise body mais… je\npourrais avoir besoin de cette liste de classes ailleurs dans mon code pour\nréaliser des tours de magie avec ajax. Disons sous forme d’objet JavaScript.\nComme faire pour créer cette liste, la modifier si je suis sur la page d’accueil\net la stocker dans mon objet .Page pour pouvoir la réutiliser par la suite ?\nPour bien faire, nous allons stocker nos classes dans un tableau.\n\/\/ Avant la balise body, je peux stocker mon unique et première classe universelle.\n{{ .Scratch.Add \"classes\" (slice \"rp-body\") }}\n\n\/\/ Puis ma section. Ce printf me permet d’ajouter la valeur de .Section avec mon préfixe personnalisé.\n{{ .Scratch.Add \"classes\" (slice (printf \"rp-%s\" .Section))) }}\n\n\/\/ Et maintenant sommes nous sur la page d’accueil ?\n{{ if .IsHome }}\n {{ .Scratch.Add \"classes\" (slice \"rp-home\") }}\n{{end}}\n\/\/ Est-ce que ce sont les vacances ? 🎄\n{{ if isset .Site.Params \"season\" }}\n {{ .Scratch.Add \"classes\" (slice (printf \"rp-body--%s\" .Site.Params.season))) }}\n{{ end }}\nNous pourrions faire bien plus de vérifications et de contorsions, mais en fin\nde compte, nous n'avons plus qu'à écrire dans notre fichier de gabarit ce joli :\n<body class='{{ delimit (.Scratch.Get \"classes\") \" \" }}'>\nEt pour JavaScript, nous pouvons créer notre objet à l’endroit où nous en avons\nbesoin.\n<script>\n let bodyClasses = [{{ range .Scratch.Get \"classes\" }}\"{{ . }}\", {{end}}];\n<\/script>\nTrès bon cas de figure, continuons notre chemin.\n.Scratch dans un fichier partiel\nComme je l’expliquais plus tôt, comme .Scratch fait partie de l’objet page\ngénéralement passé en tant que contexte (le fameux point) à l’appel de la fonction\npartial.Déplaçons le bout de code qui stocke nos classes dans un fichier\npartiel pour gagner en lisibilité :\n\/\/ partials\/scratching\/body_classes.html\n{{ .Scratch.Add \"classes\" (slice \"rp-body\") }}\n[… ici le code vu précédemment …]\nDans mon fichier de gabarit, je peux maintenant écrire :\n{{ partial \"scratching\/body_classes.html\" . }}\n<body class='{{ delimit (.Scratch.Get \"classes\") \" \" }}'>\n[…]\nLe retour de la fonction .Scratch de la page a été transmis au fichier partiel\nvia le contexte, de manière à pouvoir continuer de le modifier sans avoir à\ntoucher au code ailleurs. En plus ça permet d’avoir des fichiers de gabarits de\npage plus propres !\n.Scratch dans un fichier partiel dans une boucle range 🤯\nQuand vous utilisez la fonction range pour boucler sur des éléments, vous ne\npouvez pas lui passer le contexte en paramètre comme on peut le faire avec la\nfonction partial, le contexte que vous manipulez est celui de la boucle, c'est\nbien ce que vous souhaitez.\n{{ .Scratch.Set \"section_color\" }}\n{{ range where .Data.Pages}}\n <h2>{{ .Title }}<\/h2>\n <div class=\"Child Child--{{ $.Scratch.Get section_color}}\">\n […]\n <div>\n{{ end }}\n\/\/ Affichera le contenu de section_color.\n\n\/\/ Alors que…\n{{ range where .Data.Pages }}\n {{ partial \"enfant.html\" . }}\n{{ end }}\n\n\/\/ Le fichier partiel enfant.html ne saura pas récupérer le contenu de la fonction .Scratch de la page, même si nous lui passons le contexte en paramètre…\nC’est parce que le contexte que nous passons en paramètre de la fonction\npartial est celui de l’élément en cours parcouru grâce à la fonction range,\npas celui de la page dont vous êtes en train de coder le gabarit.\nTrès bien me direz-vous, mais comment faire pour accéder au .Scratch de la\npage parente depuis notre fichier partiel ?\nEh bien, vous pouvez toujours stocker ce qui est retourné par la fonction\n.Scratch de la page dans une variable, pour la passer ensuite en paramètre de\nvotre fichier partiel :\n{{ $indexScratch := .Scratch }}\n {{ range where .Data.Pages }}\n {{ partial \"child.html\" $indexScratch }}\n {{ end }}\nDans le fichier partiel on écrira alors :\n<div class=\"Child Child--{{ .Get \"section_color\" }}\">\n[…]\n<div>\nSi vous avez également besoin de l’ensemble du contexte de la page que vous êtes\nen train de parcourir dans la boucle, utilisez alors la fonction dict :\n{{ $indexScratch := .Scratch }}\n {{ range where .Data.Pages }}\n {{ partial \"child.html\" (dict \"indexScratch\" $indexScratch \"page\" . }}\n {{ end }}\nDans le fichier partiel vous pourrez alors écrire :\n<div class=\"Child Child--{{ .indexScratch.Get section_color}}\">\n {{ .page.Content }}\n<div>\n.Scratch dans un fichier partiel sans contexte de page\nTout ce qui figure ci-dessus est important si vous devez accéder à une instance Scratch liée à votre contexte de page, mais avec l'ajout de newScratch2, vous pouvez utiliser désormais utiliser Scratch n'importe où, y compris dans un fichier partiel sans contexte de Page.\nAppelons un fichier partiel. Notez que nous ne passons aucun contexte de Page, juste une map issue du Front Matter qui contient class, alt et une potentielle image_src pour remplacer celle par défaut.\n{{ partial \"brand\" .Params.brand }}\nDans notre fichier partiel nous pouvons toujours faire appel à Scratch :\n{{ $brandScratch := newScratch }}\n{{ $brandScratch.Set \"brand_image\" \"default.jpg\" }}\n{{ with .image_src }}\n {{ $brandScratch.Set \"brand_image\" \".\" }}\n{{ end }}\n<div class=\"brand {{ .class }}\">\n <img src=\"{{ $brandScratch.Get \"brand_image\" }}\" alt=\"{{ .alt }}\" \/>\n<\/div>\n.Scratch après Go 1.11\nOui, avec la version 11 de Golang nous pouvons maintenant nativement écraser les variables dans les templates Go mais …\nDans beaucoup de cas, je trouve que stocker une valeur dans le contexte de Page plus utile qu'autre chose. Par exemple, si un fichier partiel a besoin d'accéder à des variables de Page et à d'autres informations, si vous vous passiez de Scratch, vous vous retrouveriez avec un contexte sous la forme d'un long dict…\n{{ $humeur := \"Joyeux\" }}\n{{ if $pluie }}\n {{ $humeur = \"Grincheux\" }}\n{{ end }}\n{{ partial \"blancheneige\/nain.html\" (dict \"humeur\" $humeur \"page\" . ) }}\nUtiliser Scratch pour stocker vos variables dans l'objet de Page vous garantit un code propre et réutilisable.\nAvec .Scratch\n{{ .Scratch.Set \"humeur\" \"Joyeux\" }}\n{{ if $pluie }}\n {{ .Scratch.Set \"humeur\" \"Grincheux\" }}\n{{ end }}\n{{ partial \"blancheneige\/nain.html\" . }}\nEn plus, je ne pense pas que s'amuser à dénouer des maps complexes soit aussi\npratique que ce que nous permet de faire actuellement .Scratch.SetInMap !\n\n\n\n\nDepuis Hugo 0.38 ↩\n\n\nDepuis Hugo 0.43 ↩ ↩\n\n\n", "content_html": "\n

Le contexte de Page d'Hugo n'est pas seulement la source d'information la plus importante pour vos pages, c'est aussi la source de données principale de tous vos templates. Plus souvent qu'il n'y paraît, vous aurez à ajouter vos propres variables personnalisées en plus de celles définies par défaut.

\n

Avec la fonction .Scratch d'Hugo, n'importe quelle Page ou Shortcode peut être enrichie avec autant de variables que nécessaire en plus de celles par défaut.

\n

C'est quoi Scratch ?

\n

Scratch a été ajouté à l'origine pour contourner une limitation du langage de templating de Go, qui empêchait d'écraser des variables. Elle s'est rapidement enrichie d'autres méthodes et constitue désormais une fonctionnalité d'Hugo à part entière.

\n\n

.Scratch.Set

\n

Set est utilisé pour mémoriser une valeur voire pour pouvoir surcharger simplement une valeur par la suite.

\n
{{ .Scratch.Set \"salutations\" \"Bonjour\" }}\n{{ if eq $ciel \"sombre\" }}\n    {{ .Scratch.Set \"salutations\" \"Bonsoir\" }}\n{{ end }}\n\n{{ .Scratch.Get \"salutations\"}}
\n

.Scratch.Add

\n

Cette méthode s'occupe d’ajouter ou de pousser des valeurs multiples dans une\nvariable ou une clef.

\n
// Pour les chaînes de caractères\n{{ .Scratch.Add \"salutations\" \"Bonjour\" }}\n{{ .Scratch.Add \"salutations\" \"Bonsoir\" }}\n\n{{ .Scratch.Get \"salutations\" }}\n// Affichera : BonjourBonsoir
\n

Utilisée avec slice, elle permet d’ajouter une ou plusieurs valeurs à un\ntableau.

\n
{{ .Scratch.Add \"salutations\" (slice \"Bonjour\") }}\n{{ .Scratch.Add \"salutations\" (slice \"Bonsoir\") }}\n{{ .Scratch.Add \"salutations\" (slice \"Aloha\" \"Buenos dias\") }}
\n

.Scratch.Get

\n

Maintenant récupérons tout ça.

\n
// Avec la fonction range\n{{ range where .Scratch.Get \"salutations\" }}\n<ol>\n    <li>\n        {{ . }}\n    </li>\n</ol>\n{{ end }}\n// ☝️ Affichera une liste ordonnée avec nos 4 salutations.\n\n// Ou avec la fonction delimit\n{{ delimit (.Scratch.Get \"salutations\"), \", \" }}\n// ☝️ Affichera Bonjour, Bonsoir, Aloha, Buenos dias
\n

.Scratch.Delete1

\n

Supprime la paire clé/valeur du contexte.\nLors de l'utilisation de .Scratch.Add dans une boucle, .Scratch.Delete est pratique pour réinitialiser une valeur.

\n
{{ .Scratch.Delete \"salutations\" }}
\n

newScratch2

\n

Ce n'est pas une méthode issue de Scratch, mais une fonction qui permet la création d'une instance locale de Scratch dans un template.

\n
{{ $headerScratch := newScratch }}\n{{ $headerScratch.Add \"brand_image\" .Params.image }}
\n

Manipuler des tableaux et des maps

\n

.Scratch.SetInMap

\n

Cette fonction-là permet de cibler la clef d’un tableau et de lui assigner une\nnouvelle valeur.

\n

Elle prend comme premier paramètre votre clef .Scratch, comme second paramètre\nla clef issue du tableau ou de la map, le troisième étant la valeur que vous\ndéfinissez.

\n

Si vous ne connaissez pas dict je\nvous explique tout ça\ndans cet article

\n
{{ .Scratch.Add \"salutations\" (dict \"english\" \"Hello\" \"french\" \"Bonjour\") }}\n\n{{ .Scratch.SetInMap \"salutations\" \"english\" \"Howdy 🤠\" }}\n\n// Nous avons modifié la valeur de la clef en anglais de Hello à Howdy 🤠 !
\n

Attention au périmètre et au contexte…

\n

.Scratch n'est disponible que pour l’objet page ou l’objet shortcode. Vous ne\npouvez pas l’utiliser sur un autre élément.

\n

Souvenez-vous que si vous vous trouvez à l’intérieur d’une boucle range dans\nvotre page d’index, alors le .Scratch de votre page d’index sera $.Scratch\nalors que la page courante que vous traitez dans votre boucle sera .Scratch.

\n

Retenez également que vous pouvez affecter une paire clef-valeur à .Scratch\ndepuis n'importe où, même dans un fichier partiel du moment que vous lui passez\nle contexte. Heeeeein? Prenons un exemple concret pour illustrer les dangers qui\nvous guettent avec l’utilisation de .Scratch et du contexte.

\n

Un exemple classe avec .Scratch

\n

Je trouve ça bien pratique d’affecter des classes à mon élément body (comme le\nfait WordPress) pour pouvoir faire des ajustements CSS/JavaScript en fonction\nde la page sur laquelle on se trouve.

\n

Je trouvais ça très fastidieux à faire avec Hugo, jusqu'à ce que je comprenne\ncomment utiliser .Scratch.

\n

Je veux ajouter une classe CSS rp-body à toutes mes pages ainsi que la valeur\nde .Section à mes classes.

\n

Et seule la page d’accueil devrait hériter de la classe rp-home.

\n

Je pourrais écrire ça une bonne foi pour toute, dans un fichier partiel ou un\nfichier de gabarit de page qui comprend l’ouverture de la balise body mais… je\npourrais avoir besoin de cette liste de classes ailleurs dans mon code pour\nréaliser des tours de magie avec ajax. Disons sous forme d’objet JavaScript.

\n

Comme faire pour créer cette liste, la modifier si je suis sur la page d’accueil\net la stocker dans mon objet .Page pour pouvoir la réutiliser par la suite ?\nPour bien faire, nous allons stocker nos classes dans un tableau.

\n
// Avant la balise body, je peux stocker mon unique et première classe universelle.\n{{ .Scratch.Add \"classes\" (slice \"rp-body\") }}\n\n// Puis ma section. Ce printf me permet d’ajouter la valeur de .Section avec mon préfixe personnalisé.\n{{ .Scratch.Add \"classes\" (slice (printf \"rp-%s\" .Section))) }}\n\n// Et maintenant sommes nous sur la page d’accueil ?\n{{ if .IsHome }}\n    {{ .Scratch.Add \"classes\" (slice \"rp-home\") }}\n{{end}}\n// Est-ce que ce sont les vacances ? 🎄\n{{ if isset .Site.Params \"season\" }}\n    {{ .Scratch.Add \"classes\" (slice (printf \"rp-body--%s\" .Site.Params.season))) }}\n{{ end }}
\n

Nous pourrions faire bien plus de vérifications et de contorsions, mais en fin\nde compte, nous n'avons plus qu'à écrire dans notre fichier de gabarit ce joli :

\n
<body class='{{ delimit (.Scratch.Get \"classes\") \" \" }}'>
\n

Et pour JavaScript, nous pouvons créer notre objet à l’endroit où nous en avons\nbesoin.

\n
<script>\n    let bodyClasses = [{{ range .Scratch.Get \"classes\" }}\"{{ . }}\", {{end}}];\n</script>
\n

Très bon cas de figure, continuons notre chemin.

\n

.Scratch dans un fichier partiel

\n

Comme je l’expliquais plus tôt, comme .Scratch fait partie de l’objet page\ngénéralement passé en tant que contexte (le fameux point) à l’appel de la fonction\npartial.Déplaçons le bout de code qui stocke nos classes dans un fichier\npartiel pour gagner en lisibilité :

\n
// partials/scratching/body_classes.html\n{{ .Scratch.Add \"classes\" (slice \"rp-body\") }}\n[… ici le code vu précédemment  …]
\n

Dans mon fichier de gabarit, je peux maintenant écrire :

\n
{{ partial \"scratching/body_classes.html\" . }}\n<body class='{{ delimit (.Scratch.Get \"classes\") \" \" }}'>\n[…]
\n

Le retour de la fonction .Scratch de la page a été transmis au fichier partiel\nvia le contexte, de manière à pouvoir continuer de le modifier sans avoir à\ntoucher au code ailleurs. En plus ça permet d’avoir des fichiers de gabarits de\npage plus propres !

\n

.Scratch dans un fichier partiel dans une boucle range 🤯

\n

Quand vous utilisez la fonction range pour boucler sur des éléments, vous ne\npouvez pas lui passer le contexte en paramètre comme on peut le faire avec la\nfonction partial, le contexte que vous manipulez est celui de la boucle, c'est\nbien ce que vous souhaitez.

\n
{{ .Scratch.Set \"section_color\" }}\n{{ range where .Data.Pages}}\n   <h2>{{ .Title }}</h2>\n     <div class=\"Child Child--{{ $.Scratch.Get section_color}}\">\n     […]\n     <div>\n{{ end }}\n// Affichera le contenu de section_color.\n\n// Alors que…\n{{ range where .Data.Pages }}\n      {{ partial \"enfant.html\" . }}\n{{ end }}\n\n// Le fichier partiel enfant.html ne saura pas récupérer le contenu de la fonction .Scratch de la page, même si nous lui passons le contexte en paramètre…
\n

C’est parce que le contexte que nous passons en paramètre de la fonction\npartial est celui de l’élément en cours parcouru grâce à la fonction range,\npas celui de la page dont vous êtes en train de coder le gabarit.

\n

Très bien me direz-vous, mais comment faire pour accéder au .Scratch de la\npage parente depuis notre fichier partiel ?

\n

Eh bien, vous pouvez toujours stocker ce qui est retourné par la fonction\n.Scratch de la page dans une variable, pour la passer ensuite en paramètre de\nvotre fichier partiel :

\n
{{ $indexScratch := .Scratch }}\n  {{ range where .Data.Pages }}\n      {{ partial \"child.html\" $indexScratch }}\n  {{ end }}
\n

Dans le fichier partiel on écrira alors :

\n
<div class=\"Child Child--{{ .Get \"section_color\" }}\">\n[…]\n<div>
\n

Si vous avez également besoin de l’ensemble du contexte de la page que vous êtes\nen train de parcourir dans la boucle, utilisez alors la fonction dict :

\n
{{ $indexScratch := .Scratch }}\n  {{ range where .Data.Pages }}\n      {{ partial \"child.html\" (dict \"indexScratch\" $indexScratch \"page\" . }}\n  {{ end }}
\n

Dans le fichier partiel vous pourrez alors écrire :

\n
<div class=\"Child Child--{{ .indexScratch.Get section_color}}\">\n    {{ .page.Content }}\n<div>
\n

.Scratch dans un fichier partiel sans contexte de page

\n

Tout ce qui figure ci-dessus est important si vous devez accéder à une instance Scratch liée à votre contexte de page, mais avec l'ajout de newScratch2, vous pouvez utiliser désormais utiliser Scratch n'importe où, y compris dans un fichier partiel sans contexte de Page.

\n

Appelons un fichier partiel. Notez que nous ne passons aucun contexte de Page, juste une map issue du Front Matter qui contient class, alt et une potentielle image_src pour remplacer celle par défaut.

\n
{{ partial \"brand\" .Params.brand }}
\n

Dans notre fichier partiel nous pouvons toujours faire appel à Scratch :

\n
{{ $brandScratch := newScratch }}\n{{ $brandScratch.Set \"brand_image\" \"default.jpg\" }}\n{{ with .image_src }}\n  {{ $brandScratch.Set \"brand_image\" \".\" }}\n{{ end }}\n<div class=\"brand {{ .class }}\">\n  <img src=\"{{ $brandScratch.Get \"brand_image\" }}\" alt=\"{{ .alt }}\" />\n</div>
\n

.Scratch après Go 1.11

\n

Oui, avec la version 11 de Golang nous pouvons maintenant nativement écraser les variables dans les templates Go mais …

\n

Dans beaucoup de cas, je trouve que stocker une valeur dans le contexte de Page plus utile qu'autre chose. Par exemple, si un fichier partiel a besoin d'accéder à des variables de Page et à d'autres informations, si vous vous passiez de Scratch, vous vous retrouveriez avec un contexte sous la forme d'un long dict…

\n
{{ $humeur := \"Joyeux\" }}\n{{ if $pluie }}\n    {{ $humeur = \"Grincheux\" }}\n{{ end }}\n{{ partial \"blancheneige/nain.html\" (dict \"humeur\" $humeur \"page\" . ) }}
\n

Utiliser Scratch pour stocker vos variables dans l'objet de Page vous garantit un code propre et réutilisable.

\n

Avec .Scratch

\n
{{ .Scratch.Set \"humeur\" \"Joyeux\" }}\n{{ if $pluie }}\n    {{ .Scratch.Set \"humeur\" \"Grincheux\" }}\n{{ end }}\n{{ partial \"blancheneige/nain.html\" . }}
\n

En plus, je ne pense pas que s'amuser à dénouer des maps complexes soit aussi\npratique que ce que nous permet de faire actuellement .Scratch.SetInMap !

\n
\n
\n
    \n
  1. \n

    Depuis Hugo 0.38 ↩

    \n
    2. \n
  2. \n

    Depuis Hugo 0.43 ↩ ↩

    \n
    3. \n
\n
", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/02/08/hugo-le-point-sur-le-contexte/", "url": "https://jamstatic.fr/2018/02/08/hugo-le-point-sur-le-contexte/", "title": "Hugo, le point sur le contexte", "summary": "Exemples de gestion du contexte et signification du point dans les templates Hugo.", "date_published": "2018-02-08T16:27:39+00:00","content_text": "Le contexte,\nc'est un concept assez perturbant quand on commence à vouloir développer des\nmodèles de page pour Hugo. Il est facile de s'emmêler les pinceaux pour accéder à\nses variables. Au travers\nde quelques exemples très simples, Régis\nPhilibert se propose de nous aider à y\nvoir plus clair.\nMais pourquoi ma variable n'est pas accessible ici et ici ? 🙄\nQuand est un habitué des bons vieux langages de templates où le périmètre\nfonctionnel est rarement un problème, bien comprendre les contraintes de\npérimètre en Go Template n'est pas\ntoujours aisé.\nDans cet article, nous essaierons de comprendre l’impact du périmètre et du\ncontexte à l’intérieur de nos gabarits et de nos fichiers partiels, et comment jongler avec le point 🤹.\nLe contexte et le point\nJ'utilise ici le mot périmètre dans le titre, car c'est la première chose qui\nvient à l’esprit quand on fait face à cette problématique et j'imagine que c'est\nle terme que les gens vont utiliser pour rechercher de l’aide. Mais en\ndéfinitive c'est plutôt du contexte dont nous allons parler ici.\nLe périmètre c'est ce qui est disponible dans une situation donnée dans votre\ncode. À l’intérieur d’une classe ou d’une fonction par exemple.\nMais dans les gabarits d’Hugo, la plupart du temps, vous n'avez accès qu'à un\nseul objet : le contexte. Et il est stocké dans un point.\nOui, ce point-là. {{.}}\nEt vous finissez donc par utiliser les propriétés de cet objet comme ça : \\\n.Title, .Permalink, .IsHome\nLe point de la page\nLe contexte d’origine, celui disponible dans votre fichier de gabarit racine\nbaseof.html et dans les autres fichiers de gabarits sera toujours le contexte\nde la page. En fait, tout ce que vous avez besoin d’afficher dans cette page est\ncontenu dans ce point.\\\n.Title, .Permalink, .Resources et tout ce qui vous chante.\nMême les informations de votre site sont stockées dans le contexte de page à\nl’aide de .Site qui est prêt à l’emploi.\nMais en Go Template dès que vous utilisez une fonction, vous perdez ce\ncontexte, et votre précieux point, votre contexte est remplacé par celui de la\nfonction, qui a son propre… point.\nSi par exemple dans mon gabarit de page j'ai :\nWith\n{{ with .Title }}\n {{\/* Maintenant le point c’est .Title *\/}}\n <h1>{{ . }}<\/h1>\n{{ end }}\nÀ l’intérieur de ce with vous n'êtes plus dans le contexte de page. Le\ncontexte, le point, c'est maintenant le titre de votre page. Ici, c'est\nexactement ce que nous voulons !\nRange\nMême chose ici, une fois que vous avez commencé à itérer avec range, le\ncontexte est l’élément actuellement parcouru. Vous perdez le contexte de page au\nprofit du contexte de la fonction range.\n{{ range .Data.Pages }}\n {{\/* Ici le point est celui de la page 'en cours'. *\/}}\n {{ .Permalink }}\n{{ end }}\n{{ range .Resources.Match \"gallery\/*\" }}\n {{\/* Ici le point designe une des images. *\/}}\n {{ .Permalink }}\n\/\/ {{ end }}\n{{ range (slice \"Hello\" \"Bonjour\" \"Gutten Tag\") }}\n {{\/* Ici le point désigne cette chaîne de caractères. *\/}}\n {{ . }}\n{{ end }}\nLe contexte du plus haut niveau de la page 💲\nHeureusement pour nous, Hugo stocke le contexte de page dans un $ donc cela ne\nfait rien si vous vous trouvez au fin fond d’un with ou d’un range, vous\npouvez toujours récupérer le contexte du plus haut niveau de la page.\nUn niveau d’imbrication\n{{ with .Title }}\n {{\/* Le point désigne .Title *\/}}\n <h1>{{ . }}<\/h1>\n {{\/* $ désigne le plus haut niveau de la page *\/}}\n <h3>From {{ $.Title }}<\/h3>\n{{ end }}\nTrois niveaux d’imbrication\n{{\/* 1. Le point désigne le plus haut niveau de la page (de liste) *\/}}\n<h1>{{ .Title }}<\/h1>\n{{ range .Data.Pages }}\n <article>\n {{\/* 2. Le point désigne la page en cours *\/}}\n <h3>{{ .Title }}<\/h3>\n <hr>\n {{ range .Resources.Match \"images\/.*\" }}\n <figure>\n {{\/* 3. Le point désigne une de ces ressources *\/}}\n <img src=\"{{ .Permalink }}\">\n {{\/* $ désigne le contexte de haut niveau de la page *\/}}\n <caption>{{ .Title }} de l’article {{ $.Title }}<\/caption>\n <\/figure>\n {{ end }}\n <\/article>\n{{ end }}\nLes fichiers partiels\nPar défaut, les fichiers partiels ne passent aucun contexte.\\\nMais il suffit d’un seul paramètre pour y remédier. Cet objet sera alors disponible\nà l’intérieur du fichier partiel et sera référencé à l’aide, vous l’aviez deviné,\ndu point.\nDonc pour des fichiers partiels simples, vous n'aurez besoin que du contexte de\npage. Le point de votre page.\n {{ partial \"page\/head\" . }}\nIci la fonction partial a pour paramètre votre contexte, à priori celui de\nvotre page si vous n'êtes pas dans une boucle range ou dans une condition\nwith ou bien dans un autre fichier partiel.\n <h1>\n {{ .Title }}\n <\/h1>\n <h3><time datetime=\"{{ .Date }}\">{{ dateFormat \"Écrit le 2 January 2006\" .Date }}<\/time><\/h3>\nMaintenant, imaginons que vous écriviez un fichier partiel pour le rendu de\nvotre image fantaisiste encadrée, vous n'avez besoin que de son chemin, qui\ndevient donc votre contexte.\n{{ partial \"img\" $path }}\nDans le fichier partials\/img.html, on aura donc :\n<figure class=\"Figure Figure--framed\">\n <img src=\"{{ . }}\" alt=\"\">\n<\/figure>\nLe point ici c'est la valeur de $path.\nC’est un exemple tout simple. La plupart du temps, vous aurez besoin de beaucoup\nplus de valeurs.\nPas de souci, nous pouvons utiliser la fonction dict pour passer un ensemble\nd’éléments en paramètre (entier, chaine de caractère, objet)\ndict va créer une map, souvent désignée également comme un tableau\nassociatif.\\\nReportez-vous à la documentation de cette fonction\nou à mon propre article sur le sujet.\n{{ partial \"img\" dict(\"path\" $path \"alt\" \"Nice blue sky\") }}\nLe point va contenir cet objet à l’intérieur du fichier partiel, donc nous\npouvons préfixer nos clefs avec .\n<figure class=\"Figure Figure--framed\">\n <img src=\"{{ .path }}\" alt=\"{{ .alt }}\">\n<\/figure>\nVous pouvez mettre une lettre majuscule à vos clefs pour qu'elles fassent plus\n\"Hugo\" mais j'aime bien mettre tout en minuscules. De cette manière dans un\nfichier partiel j'identifie immédiatement les clefs issues d’un contexte\npersonnalisé de celles issues de celui de la page.\nAccéder au plus haut niveau \\$ depuis un fichier partiel\nContrairement à range et with le contexte de page n'est pas disponible dans\n$.\nPas de problème, nous allons ajouter le contexte de la page à notre dict.\nVous pouvez appeler cette clef importante comme vous voulez, beaucoup de gens\nutilisent \"Page\" pour pouvoir écrire Page.Title. Comme ça vous chante, du\nmoment que vous êtes consistent dans votre nomenclature.\n{{ partial \"img\" dict(\"Page\" . \"path\" $path \"alt\" \"Nice blue sky\") }}\n<figure class=\"Figure Figure--framed\">\n <img src=\"{{ .path }}\" alt=\"{{ .alt }} from {{ .Page.Title }}\" \/>\n<\/figure>\nConclusion\nCe point peut vite devenir votre meilleur ami et s'avère bien pratique une fois\nqu'on a appris à jongler avec. Il permet d’écrire du code très lisible même si\nparfois on ne sait plus très bien à quel niveau on se situe.\nIl y a d’autres fonctions qui prennent le contexte, regardez notamment du côté\nde block et template.\nBonne mise au point !", "content_html": "\n

Mais pourquoi ma variable n'est pas accessible ici et ici ? 🙄

\n

Quand est un habitué des bons vieux langages de templates où le périmètre\nfonctionnel est rarement un problème, bien comprendre les contraintes de\npérimètre en Go Template n'est pas\ntoujours aisé.

\n

Dans cet article, nous essaierons de comprendre l’impact du périmètre et du\ncontexte à l’intérieur de nos gabarits et de nos fichiers partiels, et comment jongler avec le point 🤹.

\n

Le contexte et le point

\n

J'utilise ici le mot périmètre dans le titre, car c'est la première chose qui\nvient à l’esprit quand on fait face à cette problématique et j'imagine que c'est\nle terme que les gens vont utiliser pour rechercher de l’aide. Mais en\ndéfinitive c'est plutôt du contexte dont nous allons parler ici.

\n

Le périmètre c'est ce qui est disponible dans une situation donnée dans votre\ncode. À l’intérieur d’une classe ou d’une fonction par exemple.

\n

Mais dans les gabarits d’Hugo, la plupart du temps, vous n'avez accès qu'à un\nseul objet : le contexte. Et il est stocké dans un point.

\n

Oui, ce point-là. {{.}}

\n

Et vous finissez donc par utiliser les propriétés de cet objet comme ça : \\\n.Title, .Permalink, .IsHome

\n

Le point de la page

\n

Le contexte d’origine, celui disponible dans votre fichier de gabarit racine\nbaseof.html et dans les autres fichiers de gabarits sera toujours le contexte\nde la page. En fait, tout ce que vous avez besoin d’afficher dans cette page est\ncontenu dans ce point.\\\n.Title, .Permalink, .Resources et tout ce qui vous chante.

\n

Même les informations de votre site sont stockées dans le contexte de page à\nl’aide de .Site qui est prêt à l’emploi.

\n

Mais en Go Template dès que vous utilisez une fonction, vous perdez ce\ncontexte, et votre précieux point, votre contexte est remplacé par celui de la\nfonction, qui a son propre… point.

\n

Si par exemple dans mon gabarit de page j'ai :

\n

With

\n
{{ with .Title }}\n    {{/* Maintenant le point c’est .Title */}}\n    <h1>{{ . }}</h1>\n{{ end }}
\n

À l’intérieur de ce with vous n'êtes plus dans le contexte de page. Le\ncontexte, le point, c'est maintenant le titre de votre page. Ici, c'est\nexactement ce que nous voulons !

\n

Range

\n

Même chose ici, une fois que vous avez commencé à itérer avec range, le\ncontexte est l’élément actuellement parcouru. Vous perdez le contexte de page au\nprofit du contexte de la fonction range.

\n
{{ range .Data.Pages }}\n    {{/* Ici le point est celui de la page 'en cours'. */}}\n    {{ .Permalink }}\n{{ end }}
\n
{{ range .Resources.Match \"gallery/*\" }}\n    {{/* Ici le point designe une des images. */}}\n    {{ .Permalink }}\n// {{ end }}
\n
{{ range (slice \"Hello\" \"Bonjour\" \"Gutten Tag\") }}\n    {{/* Ici le point désigne cette chaîne de caractères. */}}\n    {{ . }}\n{{ end }}
\n

Le contexte du plus haut niveau de la page 💲

\n

Heureusement pour nous, Hugo stocke le contexte de page dans un $ donc cela ne\nfait rien si vous vous trouvez au fin fond d’un with ou d’un range, vous\npouvez toujours récupérer le contexte du plus haut niveau de la page.

\n

Un niveau d’imbrication

\n
{{ with .Title }}\n    {{/* Le point désigne .Title */}}\n    <h1>{{ . }}</h1>\n    {{/* $ désigne le plus haut niveau de la page */}}\n    <h3>From {{ $.Title }}</h3>\n{{ end }}
\n

Trois niveaux d’imbrication

\n
{{/* 1. Le point désigne le plus haut niveau de la page (de liste) */}}\n<h1>{{ .Title }}</h1>\n{{ range .Data.Pages }}\n    <article>\n        {{/* 2. Le point désigne la page en cours */}}\n        <h3>{{ .Title }}</h3>\n        <hr>\n        {{ range .Resources.Match \"images/.*\" }}\n            <figure>\n                {{/* 3. Le point désigne une de ces ressources */}}\n                <img src=\"{{ .Permalink }}\">\n                {{/* $ désigne le contexte de haut niveau de la page */}}\n                <caption>{{ .Title }} de l’article {{ $.Title }}</caption>\n            </figure>\n        {{ end }}\n    </article>\n{{ end }}
\n

Les fichiers partiels

\n

Par défaut, les fichiers partiels ne passent aucun contexte.\\\nMais il suffit d’un seul paramètre pour y remédier. Cet objet sera alors disponible\nà l’intérieur du fichier partiel et sera référencé à l’aide, vous l’aviez deviné,\ndu point.

\n

Donc pour des fichiers partiels simples, vous n'aurez besoin que du contexte de\npage. Le point de votre page.

\n
    {{ partial \"page/head\" . }}
\n

Ici la fonction partial a pour paramètre votre contexte, à priori celui de\nvotre page si vous n'êtes pas dans une boucle range ou dans une condition\nwith ou bien dans un autre fichier partiel.

\n
    <h1>\n        {{ .Title }}\n    </h1>\n    <h3><time datetime=\"{{ .Date }}\">{{ dateFormat \"Écrit le 2 January 2006\" .Date }}</time></h3>
\n

Maintenant, imaginons que vous écriviez un fichier partiel pour le rendu de\nvotre image fantaisiste encadrée, vous n'avez besoin que de son chemin, qui\ndevient donc votre contexte.

\n
{{ partial \"img\" $path }}
\n

Dans le fichier partials/img.html, on aura donc :

\n
<figure class=\"Figure Figure--framed\">\n    <img src=\"{{ . }}\" alt=\"\">\n</figure>
\n

Le point ici c'est la valeur de $path.

\n

C’est un exemple tout simple. La plupart du temps, vous aurez besoin de beaucoup\nplus de valeurs.

\n

Pas de souci, nous pouvons utiliser la fonction dict pour passer un ensemble\nd’éléments en paramètre (entier, chaine de caractère, objet)

\n

dict va créer une map, souvent désignée également comme un tableau\nassociatif.\\\nReportez-vous à la documentation de cette fonction\nou à mon propre article sur le sujet.

\n
{{ partial \"img\" dict(\"path\" $path \"alt\" \"Nice blue sky\") }}
\n

Le point va contenir cet objet à l’intérieur du fichier partiel, donc nous\npouvons préfixer nos clefs avec .

\n
<figure class=\"Figure Figure--framed\">\n    <img src=\"{{ .path }}\" alt=\"{{ .alt }}\">\n</figure>
\n

Vous pouvez mettre une lettre majuscule à vos clefs pour qu'elles fassent plus\n\"Hugo\" mais j'aime bien mettre tout en minuscules. De cette manière dans un\nfichier partiel j'identifie immédiatement les clefs issues d’un contexte\npersonnalisé de celles issues de celui de la page.

\n

Accéder au plus haut niveau \\$ depuis un fichier partiel

\n

Contrairement à range et with le contexte de page n'est pas disponible dans\n$.

\n

Pas de problème, nous allons ajouter le contexte de la page à notre dict.

\n

Vous pouvez appeler cette clef importante comme vous voulez, beaucoup de gens\nutilisent \"Page\" pour pouvoir écrire Page.Title. Comme ça vous chante, du\nmoment que vous êtes consistent dans votre nomenclature.

\n
{{ partial \"img\" dict(\"Page\" . \"path\" $path \"alt\" \"Nice blue sky\") }}
\n
<figure class=\"Figure Figure--framed\">\n  <img src=\"{{ .path }}\" alt=\"{{ .alt }} from {{ .Page.Title }}\" />\n</figure>
\n

Conclusion

\n

Ce point peut vite devenir votre meilleur ami et s'avère bien pratique une fois\nqu'on a appris à jongler avec. Il permet d’écrire du code très lisible même si\nparfois on ne sait plus très bien à quel niveau on se situe.

\n

Il y a d’autres fonctions qui prennent le contexte, regardez notamment du côté\nde block et template.

\n

Bonne mise au point !

", "authors": [ { "name": "regis" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/01/24/eleventy-generateur-statique-simple/", "url": "https://jamstatic.fr/2018/01/24/eleventy-generateur-statique-simple/", "title": "Un site web simple avec le plus simple des générateurs de site statique", "summary": "Présentation d’Eleventy, le générateur de site statique le plus simple et le plus intuitif.", "date_published": "2018-01-24T19:40:44+00:00","content_text": "Il existe des centaines de générateurs de site statique et il en arrive toujours de nouveaux. Après avoir longtemps utilisé Jekyll, Zach Leat, développeur front-end chez Filament Group, a décidé de s'inspirer des principes de Jekyll pour les porter et les étendre grâce à l’écosystème de npm qu'il manipule au quotidien. Ce nouveau générateur vise donc les développeurs front end et leur donne le choix du langage de templating (Liquid par défaut comme dans Jekyll et aussi tout plein d’autres qu'on peut mélanger à loisir bien connus des développeurs JS) tout en leur offrant la puissance de npm. Zach nous propose un premier aperçu de son fonctionnement.\n\n\n\n\n\n\nPhoto de Jeremy Bishop\n\nVoici Eleventy, le générateur de site statique le plus simple et le plus intuitif. Avec Eleventy, vous pouvez générer des sites à partir de données de manière simple et rapide — et vous concentrer sur un contenu facile à maintenir, conçu pour durer longtemps. Faites en sorte que votre site dure 10 ans, pas 10 mois.\nInstallation\n\n\nSi ce n'est pas déjà fait, installez node.js et npm (ils sont dispos sous la forme d’un seul et unique paquet). Eleventy ne fonctionne qu’à partir de node --version 8.0.0 ou plus.\n\n\nEnsuite, installez l’utilitaire en ligne de commande, disponible sur npm : npm install -g @11ty\/eleventy\n\n\nEn avant\nFaisons un site web pour notre collection d’images GIF. Une interface pour notre propre domaine bukk.it. Appelons ça Giffleball.\nLe code source de la première partie de ce tutoriel est disponible sur GitHub.\nCréation des fichiers\nCréons un dossier pour notre tout nouveau site web.\nmkdir giffleball\nAjoutons quelques images à notre site. Voici une sélection d’images d’oiseaux tirée de l’honorable site bukk.it.\n\n\n\n\n\n\n\n\n\n\n\nSauvegardez ces images dans un dossier img à l’intérieur de notre répertoire giffleball.\ngiffleball\/\n img\/???.jpg (nouveau)\n img\/….jpg (nouveau)\n img\/parrot.gif (nouveau)\nCréation d’un gabarit de page\nFaisons un gabarit de page ! Créez un fichier nommé index.html dans le répertoire giffleball.\ngiffleball\/\n index.html (nouveau)\n img\/???.jpg\n img\/….jpg\n img\/parrot.gif\nCréons une liste avec des liens vers nos images GIF dans le fichier index.html :\n<!DOCTYPE html>\n<html lang=\"en\">\n <head>\n <meta charset=\"utf-8\" \/>\n <title>Giffleball<\/title>\n <\/head>\n <body>\n <h1>Giffleball<\/h1>\n <ul>\n <li><a href=\"img\/???.jpg\">???.jpg<\/a><\/li>\n <li><a href=\"img\/….jpg\">….jpg<\/a><\/li>\n <li><a href=\"img\/parrot.gif\">parrot.gif<\/a><\/li>\n <\/ul>\n <\/body>\n<\/html>\nJusqu'ici, rien d’extraordinaire. Mais nous pouvons déjà lancer eleventy et générer notre site. Nous passerons en option les extensions de fichier que nous voulons voir eleventy traiter :\n~ cd giffleball\n~\/giffleball $ eleventy --formats=html,gif,jpg\nWriting _site\/index.html from .\/index.html.\nWrote 1 file in 0.07 seconds\nCela a pour effet de créer un nouveau site web dans le répertoire _site. Si vous souhaitez que le site soit généré dans un autre dossier, précisez le nom du répertoire en argument avec l’option --output :\n~\/giffleball $ eleventy --output=ailleurs\nWriting ailleurs\/index.html from .\/index.html.\nWrote 1 file in 0.07 seconds\nBasons-nous sur des données\nOK, jusqu'ici nous aurions simplement pu charger notre fichier index.html dans le navigateur et le résultat aurait été le même. Il n'y a aucune différence en entrée et en sortie. Ajoutons donc une petite touche eleventy. Déplaçons certaines données de la page dans notre front matter :\n---\nsiteTitle: Giffleball\nimages:\n - ???.jpg\n - ….jpg\n - parrot.gif\n---\n\n<!doctype html>\n\n<html lang=\"en\">\n <head>\n <meta charset=\"utf-8\">\n <title>{{ siteTitle }}<\/title>\n <\/head>\n <body>\n <h1>{{ siteTitle }}<\/h1>\n <ul>\n {% for filename in images %}\n <li><a href=\"img\/{{ filename }}\">{{ filename }}<\/a><\/li>\n {% endfor %}\n <\/ul>\n <\/body>\n<\/html>\nNous avons ajouté le titre du site (utilisé à deux endroits) ainsi que la liste des images dans notre front matter.\nPar défaut dans Eleventy, le moteur du rendu liquid est disponible pour les fichiers HTML et les fichiers Markdown. Eleventy supporte une large gamme de moteurs de rendu (jetez un œil sur la liste complète) qui sont disponibles lorsque vous utilisez une extension de fichier spécifique. Par exemple notre fichier index.html aurait pu s'appeler index.liquid et le fonctionnement aurait été le même :\n~\/giffleball $ mv index.html index.liquid\n~\/giffleball $ eleventy --formats=liquid,html,jpg,gif\nWriting _site\/index.html from .\/index.liquid.\nWrote 1 file in 0.07 seconds\nBien sûr vous pouvez modifier les paramètres par défaut, nous verrons ça plus tard (ou vous pouvez dès à présent jeter un œil au fichier README).\nL'utilisation d’un moteur de rendu présente plusieurs avantages :\n\n\nModifier vos données au même endroit. Pour changer le titre du site, nous n'avons besoin de le modifier qu'à un seul endroit (le front matter) au lieu de deux. Pour ajouter ou supprimer des images nous n'avons pas à toucher au modèle de code HTML.\n\n\nModifier le balisage des liens vers nos images en une fois. Admettons que nous souhaitions modifier le code HTML de notre liste d’images. Comme nous nous basons sur des données, nous pouvons modifier le modèle de code HTML dans notre boucle plutôt que de devoir modifier chaque <li> individuellement. Trois passent encore mais vous imaginez si notre site listait 300 images ?\n\n\nLes caractères spéciaux contenus dans les noms de fichier. Quand je regarde dans mon navigateur, on dirait que mon serveur web n'aime pas trop des noms tels que ???.jpg. Le fichier ne s'affiche pas correctement. Que se passerait-il si nos noms de fichiers comportaient des caractères bizarres que notre serveur web ou notre navigateur ne sait pas traiter ? Nous devons les échapper ! La syntaxe du moteur de template Liquid a juste ce qu'il nous faut : un filtre url_encode. Mettons notre gabarit à jour pour en bénéficier :\n\n\n{% for filename in images %}\n<li><a href=\"img\/{{ filename | url_encode }}\">{{ filename }}<\/a><\/li>\n{% endfor %}\nAh c'est bien mieux. Ça marche nickel.\nJ'espère que vous vous rendez compte de l’avantage d’utiliser des moteurs de rendu et un générateur de site statique pour vos sites web.\nLe code source de la deuxième partie de ce tutoriel est disponible sur GitHub.\nAjoutons un filtre\nFaisons un truc plus compliqué. Affichons la taille de chacune des images GIF à côté de leur lien. Nous pouvons faire ça à l’aide d’un filtre. Les filtres s'ajoutent dans le fichier de configuration — un fichier .eleventy.js — créons en un. Il devrait ressembler à ça :\nmodule.exports = function (eleventyConfig) {};\nSi vous ne le nommez pas .eleventy.js, chaque fois que vous allez lancer la commande eleventy il faudra lui passer le nom du fichier de configuration en option à l’aide de --config=maConfig.js. C’est bien plus simple de s'en tenir au nom par défaut.\nAjoutons notre filtre à l’aide de la méthode .addFilter. Appelons-le filesize et commençons par lui faire retourner un texte tout bête :\nmodule.exports = function (eleventyConfig) {\n eleventyConfig.addFilter(\"filesize\", function (path) {\n return \"0 KB\";\n });\n};\nBien entendu, notre filtre n'est pas bon, car nous nous contentons de retourner \"0 KB\" à chaque fois. Mais vérifions d’abord qu'il marche.\nOuvrons notre modèle index.html et regardons à quoi ressemble notre boucle pour le moment :\n<ul>\n {% for filename in images %}\n <li><a href=\"img\/{{ filename | url_encode }}\">{{ filename }}<\/a><\/li>\n {% endfor %}\n<\/ul>\nVous avez fait attention à la façon dont nous avons utilisé le filtre natif url_encode fourni par le moteur de rendu Liquid ? Maintenant que nous avons créé le nôtre, ajoutons un appel à notre petit filtre maison, comme ceci :\n<ul>\n {% for filename in images %} {% capture path %}img\/{{ filename }}{% endcapture\n %}\n <li>\n <a href=\"img\/{{ filename | url_encode }}\">{{ filename }}<\/a> {{ path |\n filesize }}\n <\/li>\n {% endfor %}\n<\/ul>\nBien entendu, la magie a lieu dans {{ path | filesize }}. Mais notez comment nous utilisons la balise {% capture %} de Liquid pour créer une nouvelle variable path avec Liquid, que nous passons ensuite à notre filtre.\nMaintenant, lançons eleventy pour générer les fichiers.\n~\/giffleball $ eleventy --formats=html,gif,jpg\nWriting _site\/index.html from .\/index.html.\nWrote 1 file in 0.07 seconds\nCela va générer le code suivant dans le fichier _site\/index.html (ici nous ne montrons que le rendu de la liste et pas le fichier HTML entier pour faire court) :\n<ul>\n <li><a href=\"img\/%3F%3F%3F.jpg\">???.jpg<\/a> 0 KB<\/li>\n <li><a href=\"img\/%E2%80%A6.jpg\">….jpg<\/a> 0 KB<\/li>\n <li><a href=\"img\/parrot.gif\">parrot.gif<\/a> 0 KB<\/li>\n<\/ul>\nOK, c'est presque ça — mais c'est quoi tous ces espacements ? (Notez que c'est une question purement rhétorique à laquelle je vais m'empresser de répondre tout de suite.) Lors du traitement des modèles, Liquid ne supprime pas les retours à la ligne et les espaces autours des balises Liquid. Heureusement pour nous, Liquid fournit un outil pour contrôler ces espacements. Il faut utiliser {%- à la place de {% pour supprimer l’espacement avant la balise Liquid. Et indépendamment on peut aussi utiliser -%} à la place de %} à la fin pour supprimer l’espace après la balise Liquid. L'un ou l’autre. Les deux. Personnellement je trouve que ça rend mieux avec juste {%- au début. Il est important pour moi d’avoir une vue du code source qui soit propre, alors nettoyons tout ça :\n<ul>\n {%- for filename in images %}\n {%- capture path %}img\/{{ filename }}{% endcapture %}\n <li><a href=\"img\/{{ filename | url_encode }}\">{{ filename }}<\/a> {{ path | filesize }}<\/li>\n {%- endfor %}\n<\/ul>\nCe qui produit :\n<ul>\n <li><a href=\"img\/%3F%3F%3F.jpg\">???.jpg<\/a> 0 KB<\/li>\n <li><a href=\"img\/%E2%80%A6.jpg\">….jpg<\/a> 0 KB<\/li>\n <li><a href=\"img\/parrot.gif\">parrot.gif<\/a> 0 KB<\/li>\n<\/ul>\nMagnifique.\nC’est encore un peu tôt pour nous réjouir, notre filtre n'est pas fini\nOK, faisons en sorte que notre filtre serve à quelque chose plutôt que de simplement retourner systématiquement \"0 KB\". Modifiez votre fichier .eleventy.js comme ceci :\nconst fs = require(\"fs\");\n\nmodule.exports = function (eleventyConfig) {\n eleventyConfig.addFilter(\"filesize\", function (path) {\n let stat = fs.statSync(path);\n if (stat) {\n return (stat.size \/ 1024).toFixed(2) + \" KB\";\n }\n return;\n (\"\");\n });\n};\nC’est la manière la plus simple de le faire marcher, ça n'ajoute aucune nouvelle dépendance lors d’un npm install.\nAllons plus loin à l’aide de NPM\nUn des gros avantages d’Eleventy sur d’autres générateurs de site statique comme Jekyll ou Hugo, c'est l’accès à tout l’écosystème de NPM. Il y a tellement d’excellents modules. Si vous êtes assez courageux pour jouer avec npm, lancez cette commande pour générer un fichier package.json pour notre projet :\n~\/giffleball $ npm init -f\nNous pouvons maintenant installer des modules cools à notre projet, comme file-size pour des tailles de fichiers plus lisibles.\n~\/giffleball $ npm install --save file-size\n+ file-size@1.0.0\nadded 1 package in 1.491s\nUtilisons-le pour coder notre filtrer dans le fichier .eleventy.js:\nconst fs = require(\"fs\");\nconst filesize = require(\"file-size\");\n\nmodule.exports = function (eleventyConfig) {\n eleventyConfig.addFilter(\"filesize\", function (path) {\n let stat = fs.statSync(path);\n if (stat) {\n return filesize(stat.size).human();\n }\n return \"\";\n });\n};\nCe qui nous donne :\n<ul>\n <li><a href=\"img\/%3F%3F%3F.jpg\">???.jpg<\/a> 44.52 KiB<\/li>\n <li><a href=\"img\/%E2%80%A6.jpg\">….jpg<\/a> 55.39 KiB<\/li>\n <li><a href=\"img\/parrot.gif\">parrot.gif<\/a> 2.05 KiB<\/li>\n<\/ul>\nFélicitations ! Vous avez ajouté un filtre et tiré profit du vaste et immense écosystème NPM.\nJ'espère que vous appréciez la puissance offerte par l’utilisation de filtres dans nos fichiers de gabarits. Ils peuvent transformer des contenus simples à l’aide de la puissance de l’écosystème NPM.\nÀ suivre\nDans la prochaine partie nous verrons comment faire marcher ensemble plusieurs fichiers de gabarits avec des fichiers de mise en page et des fichiers de données externes.", "content_html": "\n
\n\n\n\n\"Photo\n\n
Photo de Jeremy Bishop
\n
\n

Voici Eleventy, le générateur de site statique le plus simple et le plus intuitif. Avec Eleventy, vous pouvez générer des sites à partir de données de manière simple et rapide — et vous concentrer sur un contenu facile à maintenir, conçu pour durer longtemps. Faites en sorte que votre site dure 10 ans, pas 10 mois.

\n

Installation

\n
    \n
  1. \n

    Si ce n'est pas déjà fait, installez node.js et npm (ils sont dispos sous la forme d’un seul et unique paquet). Eleventy ne fonctionne qu’à partir de node --version 8.0.0 ou plus.

    \n
    2. \n
  2. \n

    Ensuite, installez l’utilitaire en ligne de commande, disponible sur npm : npm install -g @11ty/eleventy

    \n
    3. \n
\n

En avant

\n

Faisons un site web pour notre collection d’images GIF. Une interface pour notre propre domaine bukk.it. Appelons ça Giffleball.

\n\n

Création des fichiers

\n

Créons un dossier pour notre tout nouveau site web.

\n
mkdir giffleball
\n

Ajoutons quelques images à notre site. Voici une sélection d’images d’oiseaux tirée de l’honorable site bukk.it.

\n\n\n\n\"img\"\n\n\n\n\n\"img\"\n\n\"img\"\n

Sauvegardez ces images dans un dossier img à l’intérieur de notre répertoire giffleball.

\n
giffleball/\n  img/???.jpg      (nouveau)\n  img/….jpg        (nouveau)\n  img/parrot.gif   (nouveau)
\n

Création d’un gabarit de page

\n

Faisons un gabarit de page ! Créez un fichier nommé index.html dans le répertoire giffleball.

\n
giffleball/\n  index.html       (nouveau)\n  img/???.jpg\n  img/….jpg\n  img/parrot.gif
\n

Créons une liste avec des liens vers nos images GIF dans le fichier index.html :

\n
<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <title>Giffleball</title>\n  </head>\n  <body>\n    <h1>Giffleball</h1>\n    <ul>\n      <li><a href=\"img/???.jpg\">???.jpg</a></li>\n      <li><a href=\"img/….jpg\">….jpg</a></li>\n      <li><a href=\"img/parrot.gif\">parrot.gif</a></li>\n    </ul>\n  </body>\n</html>
\n

Jusqu'ici, rien d’extraordinaire. Mais nous pouvons déjà lancer eleventy et générer notre site. Nous passerons en option les extensions de fichier que nous voulons voir eleventy traiter :

\n
~ cd giffleball\n~/giffleball $ eleventy --formats=html,gif,jpg\nWriting _site/index.html from ./index.html.\nWrote 1 file in 0.07 seconds
\n

Cela a pour effet de créer un nouveau site web dans le répertoire _site. Si vous souhaitez que le site soit généré dans un autre dossier, précisez le nom du répertoire en argument avec l’option --output :

\n
~/giffleball $ eleventy --output=ailleurs\nWriting ailleurs/index.html from ./index.html.\nWrote 1 file in 0.07 seconds
\n

Basons-nous sur des données

\n

OK, jusqu'ici nous aurions simplement pu charger notre fichier index.html dans le navigateur et le résultat aurait été le même. Il n'y a aucune différence en entrée et en sortie. Ajoutons donc une petite touche eleventy. Déplaçons certaines données de la page dans notre front matter :

\n
---\nsiteTitle: Giffleball\nimages:\n  - ???.jpg\n  - ….jpg\n  - parrot.gif\n---\n\n<!doctype html>\n\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n    <title>{{ siteTitle }}</title>\n  </head>\n  <body>\n    <h1>{{ siteTitle }}</h1>\n    <ul>\n    {% for filename in images %}\n      <li><a href=\"img/{{ filename }}\">{{ filename }}</a></li>\n    {% endfor %}\n    </ul>\n  </body>\n</html>
\n

Nous avons ajouté le titre du site (utilisé à deux endroits) ainsi que la liste des images dans notre front matter.

\n

Par défaut dans Eleventy, le moteur du rendu liquid est disponible pour les fichiers HTML et les fichiers Markdown. Eleventy supporte une large gamme de moteurs de rendu (jetez un œil sur la liste complète) qui sont disponibles lorsque vous utilisez une extension de fichier spécifique. Par exemple notre fichier index.html aurait pu s'appeler index.liquid et le fonctionnement aurait été le même :

\n
~/giffleball $ mv index.html index.liquid\n~/giffleball $ eleventy --formats=liquid,html,jpg,gif\nWriting _site/index.html from ./index.liquid.\nWrote 1 file in 0.07 seconds
\n

Bien sûr vous pouvez modifier les paramètres par défaut, nous verrons ça plus tard (ou vous pouvez dès à présent jeter un œil au fichier README).

\n

L'utilisation d’un moteur de rendu présente plusieurs avantages :

\n
    \n
  1. \n

    Modifier vos données au même endroit. Pour changer le titre du site, nous n'avons besoin de le modifier qu'à un seul endroit (le front matter) au lieu de deux. Pour ajouter ou supprimer des images nous n'avons pas à toucher au modèle de code HTML.

    \n
    2. \n
  2. \n

    Modifier le balisage des liens vers nos images en une fois. Admettons que nous souhaitions modifier le code HTML de notre liste d’images. Comme nous nous basons sur des données, nous pouvons modifier le modèle de code HTML dans notre boucle plutôt que de devoir modifier chaque <li> individuellement. Trois passent encore mais vous imaginez si notre site listait 300 images ?

    \n
    3. \n
  3. \n

    Les caractères spéciaux contenus dans les noms de fichier. Quand je regarde dans mon navigateur, on dirait que mon serveur web n'aime pas trop des noms tels que ???.jpg. Le fichier ne s'affiche pas correctement. Que se passerait-il si nos noms de fichiers comportaient des caractères bizarres que notre serveur web ou notre navigateur ne sait pas traiter ? Nous devons les échapper ! La syntaxe du moteur de template Liquid a juste ce qu'il nous faut : un filtre url_encode. Mettons notre gabarit à jour pour en bénéficier :

    \n
    4. \n
\n
{% for filename in images %}\n<li><a href=\"img/{{ filename | url_encode }}\">{{ filename }}</a></li>\n{% endfor %}
\n

Ah c'est bien mieux. Ça marche nickel.

\n

J'espère que vous vous rendez compte de l’avantage d’utiliser des moteurs de rendu et un générateur de site statique pour vos sites web.

\n\n

Ajoutons un filtre

\n

Faisons un truc plus compliqué. Affichons la taille de chacune des images GIF à côté de leur lien. Nous pouvons faire ça à l’aide d’un filtre. Les filtres s'ajoutent dans le fichier de configuration — un fichier .eleventy.js — créons en un. Il devrait ressembler à ça :

\n
module.exports = function (eleventyConfig) {};
\n

Si vous ne le nommez pas .eleventy.js, chaque fois que vous allez lancer la commande eleventy il faudra lui passer le nom du fichier de configuration en option à l’aide de --config=maConfig.js. C’est bien plus simple de s'en tenir au nom par défaut.

\n

Ajoutons notre filtre à l’aide de la méthode .addFilter. Appelons-le filesize et commençons par lui faire retourner un texte tout bête :

\n
module.exports = function (eleventyConfig) {\n  eleventyConfig.addFilter(\"filesize\", function (path) {\n    return \"0 KB\";\n  });\n};
\n

Bien entendu, notre filtre n'est pas bon, car nous nous contentons de retourner \"0 KB\" à chaque fois. Mais vérifions d’abord qu'il marche.

\n

Ouvrons notre modèle index.html et regardons à quoi ressemble notre boucle pour le moment :

\n
<ul>\n  {% for filename in images %}\n  <li><a href=\"img/{{ filename | url_encode }}\">{{ filename }}</a></li>\n  {% endfor %}\n</ul>
\n

Vous avez fait attention à la façon dont nous avons utilisé le filtre natif url_encode fourni par le moteur de rendu Liquid ? Maintenant que nous avons créé le nôtre, ajoutons un appel à notre petit filtre maison, comme ceci :

\n
<ul>\n  {% for filename in images %} {% capture path %}img/{{ filename }}{% endcapture\n  %}\n  <li>\n    <a href=\"img/{{ filename | url_encode }}\">{{ filename }}</a> {{ path |\n    filesize }}\n  </li>\n  {% endfor %}\n</ul>
\n

Bien entendu, la magie a lieu dans {{ path | filesize }}. Mais notez comment nous utilisons la balise {% capture %} de Liquid pour créer une nouvelle variable path avec Liquid, que nous passons ensuite à notre filtre.

\n

Maintenant, lançons eleventy pour générer les fichiers.

\n
~/giffleball $ eleventy --formats=html,gif,jpg\nWriting _site/index.html from ./index.html.\nWrote 1 file in 0.07 seconds
\n

Cela va générer le code suivant dans le fichier _site/index.html (ici nous ne montrons que le rendu de la liste et pas le fichier HTML entier pour faire court) :

\n
<ul>\n  <li><a href=\"img/%3F%3F%3F.jpg\">???.jpg</a> 0 KB</li>\n  <li><a href=\"img/%E2%80%A6.jpg\">….jpg</a> 0 KB</li>\n  <li><a href=\"img/parrot.gif\">parrot.gif</a> 0 KB</li>\n</ul>
\n

OK, c'est presque ça — mais c'est quoi tous ces espacements ? (Notez que c'est une question purement rhétorique à laquelle je vais m'empresser de répondre tout de suite.) Lors du traitement des modèles, Liquid ne supprime pas les retours à la ligne et les espaces autours des balises Liquid. Heureusement pour nous, Liquid fournit un outil pour contrôler ces espacements. Il faut utiliser {%- à la place de {% pour supprimer l’espacement avant la balise Liquid. Et indépendamment on peut aussi utiliser -%} à la place de %} à la fin pour supprimer l’espace après la balise Liquid. L'un ou l’autre. Les deux. Personnellement je trouve que ça rend mieux avec juste {%- au début. Il est important pour moi d’avoir une vue du code source qui soit propre, alors nettoyons tout ça :

\n
<ul>\n  {%- for filename in images %}\n  {%- capture path %}img/{{ filename }}{% endcapture %}\n  <li><a href=\"img/{{ filename | url_encode }}\">{{ filename }}</a> {{ path | filesize }}</li>\n  {%- endfor %}\n</ul>
\n

Ce qui produit :

\n
<ul>\n  <li><a href=\"img/%3F%3F%3F.jpg\">???.jpg</a> 0 KB</li>\n  <li><a href=\"img/%E2%80%A6.jpg\">….jpg</a> 0 KB</li>\n  <li><a href=\"img/parrot.gif\">parrot.gif</a> 0 KB</li>\n</ul>
\n

Magnifique.

\n

C’est encore un peu tôt pour nous réjouir, notre filtre n'est pas fini

\n

OK, faisons en sorte que notre filtre serve à quelque chose plutôt que de simplement retourner systématiquement \"0 KB\". Modifiez votre fichier .eleventy.js comme ceci :

\n
const fs = require(\"fs\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addFilter(\"filesize\", function (path) {\n    let stat = fs.statSync(path);\n    if (stat) {\n      return (stat.size / 1024).toFixed(2) + \" KB\";\n    }\n    return;\n    (\"\");\n  });\n};
\n

C’est la manière la plus simple de le faire marcher, ça n'ajoute aucune nouvelle dépendance lors d’un npm install.

\n

Allons plus loin à l’aide de NPM

\n

Un des gros avantages d’Eleventy sur d’autres générateurs de site statique comme Jekyll ou Hugo, c'est l’accès à tout l’écosystème de NPM. Il y a tellement d’excellents modules. Si vous êtes assez courageux pour jouer avec npm, lancez cette commande pour générer un fichier package.json pour notre projet :

\n
~/giffleball $ npm init -f
\n

Nous pouvons maintenant installer des modules cools à notre projet, comme file-size pour des tailles de fichiers plus lisibles.

\n
~/giffleball $ npm install --save file-size\n+ file-size@1.0.0\nadded 1 package in 1.491s
\n

Utilisons-le pour coder notre filtrer dans le fichier .eleventy.js:

\n
const fs = require(\"fs\");\nconst filesize = require(\"file-size\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addFilter(\"filesize\", function (path) {\n    let stat = fs.statSync(path);\n    if (stat) {\n      return filesize(stat.size).human();\n    }\n    return \"\";\n  });\n};
\n

Ce qui nous donne :

\n
<ul>\n  <li><a href=\"img/%3F%3F%3F.jpg\">???.jpg</a> 44.52 KiB</li>\n  <li><a href=\"img/%E2%80%A6.jpg\">….jpg</a> 55.39 KiB</li>\n  <li><a href=\"img/parrot.gif\">parrot.gif</a> 2.05 KiB</li>\n</ul>
\n

Félicitations ! Vous avez ajouté un filtre et tiré profit du vaste et immense écosystème NPM.

\n

J'espère que vous appréciez la puissance offerte par l’utilisation de filtres dans nos fichiers de gabarits. Ils peuvent transformer des contenus simples à l’aide de la puissance de l’écosystème NPM.

\n

À suivre

\n

Dans la prochaine partie nous verrons comment faire marcher ensemble plusieurs fichiers de gabarits avec des fichiers de mise en page et des fichiers de données externes.

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/01/09/wordpress-comme-cms-pour-vos-sites-statiques/", "url": "https://jamstatic.fr/2018/01/09/wordpress-comme-cms-pour-vos-sites-statiques/", "title": "Utiliser WordPress comme CMS pour vos sites statiques", "summary": "Grâce à son API REST WordPress fait aussi CMS headless. Stefan Baumgartner montre comment récupérer les contenus pour générer un site statique avec Metalsmith.", "date_published": "2018-01-09T14:50:46+00:00","content_text": "La mode est au CMS headless,\ncomprenez au découplage du back et du front. WordPress n'échappe pas à la règle.\nMême si son API REST ne permet pas encore de faire tout ce qu'on voudrait, il\nest tout à fait possible d’aller récupérer les contenus entrés par les\nutilisateurs dans l’interface d’administration qu'ils affectionnent tant pour\nensuite les passer à la moulinette d’un générateur de site statique. Stefan\nBaumgartner a testé pour vous avec Metalsmith,\nvoici comment il a procédé.\nLa toute-puissante JAMStack offre des sites web statiques rapides\net sécurisés, et avec des systèmes de gestion de contenu headless ils deviennent même faciles à éditer ! Toutefois il peut\narriver que de temps à autre, vous vous retrouviez devant un blog WordPress avec\ntellement d’articles (et d’auteurs qui ont peur du changement !) pour que la\nraison vous pousse à ne pas le migrer. Mais WordPress aussi fonctionne en\nheadless. D'ailleurs, le propre service d’hébergement de WordPress communique\navec le core de WordPress uniquement au travers de son API, l’interface\nd’édition fait partie de la toute nouvelle et belle application\nCalypso.\nUn des gros avantages quand on utilise un générateur de site statique, c'est que\ngénéralement il se moque de la provenance de votre contenu. Utilisons donc\nl’attrayante API REST de WordPress pour récupérer un\npeu de contenu et générer des sites statiques !\nDans mon exemple, j'utilise le générateur de site statique\nMetalsmith. C’est juste car je travaille avec au\nquotidien et qu'il est assez simple de faire tourner de nouveaux plugins dessus.\nMais ça marche aussi avec\nles générateurs de Jekyll par\nexemple. Du moment que votre générateur sait comment utiliser des fichiers JSON\npour les données en entrée, vous pouvez utiliser les exemples de code ci-dessous\npour stocker ce qui est retourné dans l’étape de préparation des données. C’est\nparti !\nL'API WordPress\nChaque installation de WordPress possède une API JSON à part entière. Ça veut\ndire que vous pouvez accéder aux articles et aux pages via des URLs. Ça m'a tout\nl’air d’un CMS headless ça ! Si vous avez une instance de WordPress qui tourne\nquelque part, ajoutez \/wp-json\/wp\/v2\/posts à la fin de l’URL principale. Vous\ndevriez avoir quelque chose en sortie !\nEn fait les 10 derniers articles ainsi que toutes leurs métadonnées vous sont\nprésentés dans un format JSON facile à comprendre.\nRécupérer les informations sur l’auteur\nVous remarquerez d’emblée que le champ author de chaque article est un nombre.\nC’est ainsi que les données sont structurées dans WordPress. Il faudrait que\nvous alliez chercher le numéro dans la table des auteurs et WordPress ne propose\npas une URL d’API pour cela.\nToutefois, vous pouvez activer l’option masquée par défaut _embed qui va\najouter toutes les données relatives à l’auteur.\nDonc avec https:\/\/url-vers-votre-blog\/wp-json\/wp\/v2\/posts?_embed vous avez\ntoutes les données dont vous avez besoin !\nRécupérer tous les articles\nSi vous avez un nombre très important d’articles, le prochain défi sera de les\nrécupérer tous. Malheureusement ce ne sera peut-être pas possible en une seule\nrequête. Vous pouvez maximiser le nombre d’articles retournés à 100 en ajoutant\nle paramètre supplémentaire per_page :\nhttps:\/\/url-vers-votre-blog\/wp-json\/wp\/v2\/posts?_embed&per_page=100\nEnsuite, il va falloir récupérer les informations de pagination. Il existe un\nparamètre page qui permet de sélectionner la page que vous souhaitez\nrécupérer. Vous avez la possibilité de l’utiliser récursivement pour récupérer\ntoutes les pages qui existent. Vous pouvez également vérifier les entêtes HTTP\npersonnalisés de WordPress pour connaître le nombre de pages à récupérer. Ici,\nc'est comme ça que je vais procéder. Gardez juste en tête que les paramètres\nCORS de votre serveur doivent autoriser le passage de ces entêtes à votre\nclient. L'entête personnalisé qui contient le nombre de pages est\nX-WP-TotalPages.\nPour télécharger les données, j'utilise\nisomorphic-fetch, qui fournit\nla même API fetch pour Node et pour le navigateur. Regardons tout ça :\nconst fetch = require(\"isomorphic-fetch\");\n\nconst mainURL = \"http:\/\/chemin-vers-votre-blog\";\nconst apiURL = \"\/wp-json\/wp\/v2\/posts\";\nconst url = `${mainURL}${apiURL}?_embed&per_page=100`;\n\nfetch(url) \/* 1 *\/\n .then((res) => {\n const noPages = res.headers.get(\"X-WP-TotalPages\"); \/* 2 *\/\n const pagesToFetch = new Array(noPages - 1)\n .fill(0)\n .map((el, id) => fetch(`${url}&page=${id + 2}`)); \/* 3 *\/\n return Promise.all([res, ...pagesToFetch]); \/* 4 *\/\n })\n .then((results) => Promise.all(results.map((el) => el.json()))) \/* 5 *\/\n .then((pages) => [].concat(...pages)); \/* 6 *\/\n\nNous téléchargeons les 100 premiers articles de notre blog. Si notre blog\nWordPress contient moins de 100 articles, nous n'avons plus rien à\ntélécharger.\nL'entête X-WP-TotalPages nous indique combien il nous reste de pages à\ntélécharger.\nNous créons un tableau de promesses pour les pages à télécharger, nous\ncommençons à la page 2 (la page 1 a déjà été téléchargée)\nPromise.all nous permet de passer le premier résultat et tous les suivants\nissus de notre tableau pagesToFetch.\nAppel de promesse suivant : convertir tous les résultats en JSON.\nEt enfin nous convertissons tous nos résultats dans un seul et unique\ntableau qui contient toutes les données des articles de notre blog.\n\nL'appel .then suivant contiendra un tableau avec toutes les entrées du blog.\nVous pouvez stocker ces données sous forme de fichier JSON (si votre générateur\nde site n'est pas extensible) ou dans notre cas : créer une vraie page de\ndonnées que nous voulons générer.\nAjouter vos articles dans Metalsmith\nMetalsmith — comme beaucoup de générateurs de sites statiques — sait quel est le\ndossier qui contient vos fichiers source. La plupart du temps au format\nMarkdown. Ces fichiers sont ensuite convertis en HTML. Toutefois, Metalsmith\npermet aussi d’ajouter des données externes. Il est assez simple de manipuler\nles tableaux de fichiers et d’ajouter de nouveaux fichiers. La seule chose à\nsavoir c'est que chaque fichier doit posséder une clef unique : l’URL ou le\nchemin où il va être stocké. Le contenu de chaque entrée est un objet qui\ncontient toutes les données que vous souhaitez stocker. Regardons tout ça !\nUn plugin WordPress pour Metalsmith\nMetalsmith fonctionne avec des plugins. À chaque fois que vous lancez une\ngénération avec Metalsmith, il va appliquer tous les plugins que vous avez\ndéfinis, un peu comme avec Gulp.\nRéutilisons l’exemple de code précédent et améliorons-le pour en faire un plugin\nMetalsmith :\nconst { URL } = require('url’);\n\nconst wordpress = (url) => (files, smith, done) => { \/* 1 *\/\n fetch(url)\n \/* … include code from above …*\/\n .then(allPages => {\n allPages.forEach(page => {\n const relativeURL\n = new URL(page.link).pathname; \/* 2 *\/\n const key = `.\/${relativeURL}\/index.html`;\n let value = page; \/* 3 *\/\n value.layout = 'post.hbs';\n value.contents =\n new Buffer(page.content.rendered, 'utf8');\n files[key] = value; \/* 4 *\/\n });\n done(); \/* 5 *\/\n });\n}\n\nL'interface pour les plugins Metalsmith est (files, metalsmith, done). Le\npremier paramètre désigne l’ensemble des fichiers qui doivent être\ntransformés en HTML. Le deuxième paramètre est l’objet Metalsmith. Le\ntroisième paramètre est une fonction de callback. C’est particulièrement\nutile pour les opérations asynchrones. Appelez done lorsque votre plugin a\nfini son travail.\nUne fois que nous avons tous les articles à partir des appels à l’API (voir\nci-dessus), nous avons transformé quelque peu les données. D'abord, nous\ndevons modifier les permaliens de WordPress pour que Metalsmith puisse s'y\nretrouver. Nous utilisons le package URL de Node pour récupérer l’URL\nrelative (sans le nom de domaine) et à partir de cela nous créons un chemin\nrelatif dans le système de fichier. Vous remarquerez que nous ajoutons\nindex.html. De cette manière nous créons tout un tas de dossiers avec un\nseul fichier HTML dedans. Nous obtenons ainsi de belles URLs pour nos sites\nstatiques.\nEnsuite, nous créons des paires clé-valeur pour l’objet fichier. Chaque\nvaleur correspond à une entrée dans le tableau post que nous avons\nrécupéré plus tôt. Nous précisons ensuite le gabarit à utiliser et indiquons\nle contenu (le plugin metalsmith-layouts a besoin de ces deux valeurs pour\nfonctionner).\nAprès ça, nous stockons cette valeur dans le chemin relatif que nous avons\ndéfini plus tôt.\nUne fois qu'on a fait ça pour tous les articles, nous appelons la fonction\nde callback done pour indiquer la fin du traitement par nos plugins.\n\nParfait. En quelques lignes de code nous avons dit à Metalsmith d’étendre les\nfichiers qu'il transforme déjà avec les fichiers que nous récupérons à partir\nd’une API. C’est ce qui rend Metalsmith extrêmement puissant, car vous n'êtes\nplus lié à un seul et unique CMS. Vous pouvez même vous brancher sur différents\nsystèmes de gestion de contenu, récents ou plus anciens, et ne produire qu'un\nseul fichier en sortie. Trop bien !\nScript de génération pour Metalsmith\nNous voulons pouvoir utiliser notre nouveau plugin de manière très simple lors\nde l’enchaînement des traitements par Metalsmith. Nous ne faisons appel qu'au\nplugin layouts qui va générer un contenu un peu plus sémantique à partir de\nnos fichiers Handlebars.\nconst Metalsmith = require('metalsmith');\nconst layouts = require('metalsmith-layouts');\n\n\/** le plugin **\/\n\nMetalsmith('.')\n .use(wordpress(apiURL))\n .use(layouts({\n engine: 'handlebars'\n }))\n .source('.\/source')\n .destination('.\/build’)\n .build((err) => {\n if (err) throw err;\n console.log('Finished’);\n });\nOn commence d’abord par récupérer toutes les données depuis l’API WordPress,\npuis on les fait passer dans le plugin metalsmith-layouts. Puis on lance la\ngénération à proprement parlé. Si vous exécutez ce fichier, vous verrez qu'il\ngénère un dossier build dans votre système de fichier.\nGabarit de page\nLe fichier de gabarit est un fichier Handlebars qui définit une structure HTML\nde base. contents fait référence au champ que nous avons défini plus tôt dans\nnotre plugin Metalsmith pour WordPress. Le reste vient directement de l’objet et\nintègre automatiquement les données de _embedded l’auteur. C’est tout simple :\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"UTF-8\">\n <title>{{title.rendered}}<\/title>\n<\/head>\n<body>\n <h1>{{title.rendered}}<\/h1>\n {{{contents}}}\n\n <aside>\n by {{_embedded.author.0.name}}\n <\/aside>\n<\/body>\n<\/html>\nÉtape suivante\nExcellent ! Après m'être familiarisé avec l’API de WordPress, avoir récupéré\ntous les contenus, créer des sites statiques à partir des données a été un jeu\nd’enfant. J'ai créé un\ndépôt à valeur d’exemple sur GitHub.\nDites-moi ce que vous en pensez.\nL'étape suivante serait de créer un petit plugin WordPress (un vrai avec du PHP\net tout) qui utilise le hook de publication pour activer automatiquement votre\nsystème d’intégration continue. Mais vu la richesse de l’écosystème de\nWordPress, il se pourrait bien de quelque chose de ce genre existe déjà.\nUn commentaire ? Envoyez un tweet !", "content_html": "\n

La toute-puissante JAMStack offre des sites web statiques rapides\net sécurisés, et avec des systèmes de gestion de contenu headless ils deviennent même faciles à éditer ! Toutefois il peut\narriver que de temps à autre, vous vous retrouviez devant un blog WordPress avec\ntellement d’articles (et d’auteurs qui ont peur du changement !) pour que la\nraison vous pousse à ne pas le migrer. Mais WordPress aussi fonctionne en\nheadless. D'ailleurs, le propre service d’hébergement de WordPress communique\navec le core de WordPress uniquement au travers de son API, l’interface\nd’édition fait partie de la toute nouvelle et belle application\nCalypso.

\n

Un des gros avantages quand on utilise un générateur de site statique, c'est que\ngénéralement il se moque de la provenance de votre contenu. Utilisons donc\nl’attrayante API REST de WordPress pour récupérer un\npeu de contenu et générer des sites statiques !

\n

Dans mon exemple, j'utilise le générateur de site statique\nMetalsmith. C’est juste car je travaille avec au\nquotidien et qu'il est assez simple de faire tourner de nouveaux plugins dessus.\nMais ça marche aussi avec\nles générateurs de Jekyll par\nexemple. Du moment que votre générateur sait comment utiliser des fichiers JSON\npour les données en entrée, vous pouvez utiliser les exemples de code ci-dessous\npour stocker ce qui est retourné dans l’étape de préparation des données. C’est\nparti !

\n

L'API WordPress

\n

Chaque installation de WordPress possède une API JSON à part entière. Ça veut\ndire que vous pouvez accéder aux articles et aux pages via des URLs. Ça m'a tout\nl’air d’un CMS headless ça ! Si vous avez une instance de WordPress qui tourne\nquelque part, ajoutez /wp-json/wp/v2/posts à la fin de l’URL principale. Vous\ndevriez avoir quelque chose en sortie !

\n

En fait les 10 derniers articles ainsi que toutes leurs métadonnées vous sont\nprésentés dans un format JSON facile à comprendre.

\n

Récupérer les informations sur l’auteur

\n

Vous remarquerez d’emblée que le champ author de chaque article est un nombre.\nC’est ainsi que les données sont structurées dans WordPress. Il faudrait que\nvous alliez chercher le numéro dans la table des auteurs et WordPress ne propose\npas une URL d’API pour cela.

\n

Toutefois, vous pouvez activer l’option masquée par défaut _embed qui va\najouter toutes les données relatives à l’auteur.

\n

Donc avec https://url-vers-votre-blog/wp-json/wp/v2/posts?_embed vous avez\ntoutes les données dont vous avez besoin !

\n

Récupérer tous les articles

\n

Si vous avez un nombre très important d’articles, le prochain défi sera de les\nrécupérer tous. Malheureusement ce ne sera peut-être pas possible en une seule\nrequête. Vous pouvez maximiser le nombre d’articles retournés à 100 en ajoutant\nle paramètre supplémentaire per_page :

\n

https://url-vers-votre-blog/wp-json/wp/v2/posts?_embed&per_page=100

\n

Ensuite, il va falloir récupérer les informations de pagination. Il existe un\nparamètre page qui permet de sélectionner la page que vous souhaitez\nrécupérer. Vous avez la possibilité de l’utiliser récursivement pour récupérer\ntoutes les pages qui existent. Vous pouvez également vérifier les entêtes HTTP\npersonnalisés de WordPress pour connaître le nombre de pages à récupérer. Ici,\nc'est comme ça que je vais procéder. Gardez juste en tête que les paramètres\nCORS de votre serveur doivent autoriser le passage de ces entêtes à votre\nclient. L'entête personnalisé qui contient le nombre de pages est\nX-WP-TotalPages.

\n

Pour télécharger les données, j'utilise\nisomorphic-fetch, qui fournit\nla même API fetch pour Node et pour le navigateur. Regardons tout ça :

\n
const fetch = require(\"isomorphic-fetch\");\n\nconst mainURL = \"http://chemin-vers-votre-blog\";\nconst apiURL = \"/wp-json/wp/v2/posts\";\nconst url = `${mainURL}${apiURL}?_embed&per_page=100`;\n\nfetch(url) /* 1 */\n  .then((res) => {\n    const noPages = res.headers.get(\"X-WP-TotalPages\"); /* 2 */\n    const pagesToFetch = new Array(noPages - 1)\n      .fill(0)\n      .map((el, id) => fetch(`${url}&page=${id + 2}`)); /* 3 */\n    return Promise.all([res, ...pagesToFetch]); /* 4 */\n  })\n  .then((results) => Promise.all(results.map((el) => el.json()))) /* 5 */\n  .then((pages) => [].concat(...pages)); /* 6 */
\n
    \n
  1. Nous téléchargeons les 100 premiers articles de notre blog. Si notre blog\nWordPress contient moins de 100 articles, nous n'avons plus rien à\ntélécharger.
    2. \n
  2. L'entête X-WP-TotalPages nous indique combien il nous reste de pages à\ntélécharger.
    3. \n
  3. Nous créons un tableau de promesses pour les pages à télécharger, nous\ncommençons à la page 2 (la page 1 a déjà été téléchargée)
    4. \n
  4. Promise.all nous permet de passer le premier résultat et tous les suivants\nissus de notre tableau pagesToFetch.
    5. \n
  5. Appel de promesse suivant : convertir tous les résultats en JSON.
    6. \n
  6. Et enfin nous convertissons tous nos résultats dans un seul et unique\ntableau qui contient toutes les données des articles de notre blog.
    7. \n
\n

L'appel .then suivant contiendra un tableau avec toutes les entrées du blog.\nVous pouvez stocker ces données sous forme de fichier JSON (si votre générateur\nde site n'est pas extensible) ou dans notre cas : créer une vraie page de\ndonnées que nous voulons générer.

\n

Ajouter vos articles dans Metalsmith

\n

Metalsmith — comme beaucoup de générateurs de sites statiques — sait quel est le\ndossier qui contient vos fichiers source. La plupart du temps au format\nMarkdown. Ces fichiers sont ensuite convertis en HTML. Toutefois, Metalsmith\npermet aussi d’ajouter des données externes. Il est assez simple de manipuler\nles tableaux de fichiers et d’ajouter de nouveaux fichiers. La seule chose à\nsavoir c'est que chaque fichier doit posséder une clef unique : l’URL ou le\nchemin où il va être stocké. Le contenu de chaque entrée est un objet qui\ncontient toutes les données que vous souhaitez stocker. Regardons tout ça !

\n

Un plugin WordPress pour Metalsmith

\n

Metalsmith fonctionne avec des plugins. À chaque fois que vous lancez une\ngénération avec Metalsmith, il va appliquer tous les plugins que vous avez\ndéfinis, un peu comme avec Gulp.

\n

Réutilisons l’exemple de code précédent et améliorons-le pour en faire un plugin\nMetalsmith :

\n
const { URL } = require('url’);\n\nconst wordpress = (url) => (files, smith, done) => { /* 1 */\n  fetch(url)\n    /* … include code from above …*/\n    .then(allPages => {\n      allPages.forEach(page => {\n        const relativeURL\n          = new URL(page.link).pathname;             /* 2 */\n        const key = `./${relativeURL}/index.html`;\n        let value = page;                            /* 3 */\n        value.layout = 'post.hbs';\n        value.contents =\n          new Buffer(page.content.rendered, 'utf8');\n        files[key] = value;                          /* 4 */\n      });\n      done();                                        /* 5 */\n    });\n}
\n
    \n
  1. L'interface pour les plugins Metalsmith est (files, metalsmith, done). Le\npremier paramètre désigne l’ensemble des fichiers qui doivent être\ntransformés en HTML. Le deuxième paramètre est l’objet Metalsmith. Le\ntroisième paramètre est une fonction de callback. C’est particulièrement\nutile pour les opérations asynchrones. Appelez done lorsque votre plugin a\nfini son travail.
    2. \n
  2. Une fois que nous avons tous les articles à partir des appels à l’API (voir\nci-dessus), nous avons transformé quelque peu les données. D'abord, nous\ndevons modifier les permaliens de WordPress pour que Metalsmith puisse s'y\nretrouver. Nous utilisons le package URL de Node pour récupérer l’URL\nrelative (sans le nom de domaine) et à partir de cela nous créons un chemin\nrelatif dans le système de fichier. Vous remarquerez que nous ajoutons\nindex.html. De cette manière nous créons tout un tas de dossiers avec un\nseul fichier HTML dedans. Nous obtenons ainsi de belles URLs pour nos sites\nstatiques.
    3. \n
  3. Ensuite, nous créons des paires clé-valeur pour l’objet fichier. Chaque\nvaleur correspond à une entrée dans le tableau post que nous avons\nrécupéré plus tôt. Nous précisons ensuite le gabarit à utiliser et indiquons\nle contenu (le plugin metalsmith-layouts a besoin de ces deux valeurs pour\nfonctionner).
    4. \n
  4. Après ça, nous stockons cette valeur dans le chemin relatif que nous avons\ndéfini plus tôt.
    5. \n
  5. Une fois qu'on a fait ça pour tous les articles, nous appelons la fonction\nde callback done pour indiquer la fin du traitement par nos plugins.
    6. \n
\n

Parfait. En quelques lignes de code nous avons dit à Metalsmith d’étendre les\nfichiers qu'il transforme déjà avec les fichiers que nous récupérons à partir\nd’une API. C’est ce qui rend Metalsmith extrêmement puissant, car vous n'êtes\nplus lié à un seul et unique CMS. Vous pouvez même vous brancher sur différents\nsystèmes de gestion de contenu, récents ou plus anciens, et ne produire qu'un\nseul fichier en sortie. Trop bien !

\n

Script de génération pour Metalsmith

\n

Nous voulons pouvoir utiliser notre nouveau plugin de manière très simple lors\nde l’enchaînement des traitements par Metalsmith. Nous ne faisons appel qu'au\nplugin layouts qui va générer un contenu un peu plus sémantique à partir de\nnos fichiers Handlebars.

\n
const Metalsmith = require('metalsmith');\nconst layouts = require('metalsmith-layouts');\n\n/** le plugin  **/\n\nMetalsmith('.')\n  .use(wordpress(apiURL))\n  .use(layouts({\n    engine: 'handlebars'\n  }))\n  .source('./source')\n  .destination('./build’)\n  .build((err) => {\n    if (err) throw err;\n    console.log('Finished’);\n  });
\n

On commence d’abord par récupérer toutes les données depuis l’API WordPress,\npuis on les fait passer dans le plugin metalsmith-layouts. Puis on lance la\ngénération à proprement parlé. Si vous exécutez ce fichier, vous verrez qu'il\ngénère un dossier build dans votre système de fichier.

\n

Gabarit de page

\n

Le fichier de gabarit est un fichier Handlebars qui définit une structure HTML\nde base. contents fait référence au champ que nous avons défini plus tôt dans\nnotre plugin Metalsmith pour WordPress. Le reste vient directement de l’objet et\nintègre automatiquement les données de _embedded l’auteur. C’est tout simple :

\n
<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <title>{{title.rendered}}</title>\n</head>\n<body>\n  <h1>{{title.rendered}}</h1>\n  {{{contents}}}\n\n  <aside>\n    by {{_embedded.author.0.name}}\n  </aside>\n</body>\n</html>
\n

Étape suivante

\n

Excellent ! Après m'être familiarisé avec l’API de WordPress, avoir récupéré\ntous les contenus, créer des sites statiques à partir des données a été un jeu\nd’enfant. J'ai créé un\ndépôt à valeur d’exemple sur GitHub.\nDites-moi ce que vous en pensez.

\n

L'étape suivante serait de créer un petit plugin WordPress (un vrai avec du PHP\net tout) qui utilise le hook de publication pour activer automatiquement votre\nsystème d’intégration continue. Mais vu la richesse de l’écosystème de\nWordPress, il se pourrait bien de quelque chose de ce genre existe déjà.

\n

Un commentaire ? Envoyez un tweet !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2018/01/07/netlify-en-10-fonctionnalites/", "url": "https://jamstatic.fr/2018/01/07/netlify-en-10-fonctionnalites/", "title": "Netlify en 10 fonctionnalités", "summary": "Déployez et hébergez gratuitement vos sites statiques comme les pros : CDN, HTTPS, CI, environnements de build, formulaires, tests A\/B, et bien plus.", "date_published": "2018-01-07T20:05:43+00:00","content_text": "En l’espace de quelques années Netlify est devenu un acteur incontournable de l’écosystème Jamstack - ils sont d’ailleurs à l’origine de cette appellation - et des sites statiques. Nous sommes nous-mêmes des utilisateurs plus que satisfaits de ce service et l’article que vous lisez en ce moment est lui-même hébergé sur un de leurs CDN. Netlify c'est le genre de service qui a réussi à faire de ses clients ses premiers ambassadeurs, tant leur produit est plus que recommandable.\nNetlify — la contraction de Net et Simplify — a pour but de simplifier la mise en production et de fournir tous les outils modernes nécessaires à des stratégies de déploiement agiles à tout un chacun, sans avoir besoin pour cela d’être un devops confirmé. Ce n'est pas simplement une solution pour héberger vos sites statiques à moindre frais, le passage de Smashing Magazine à une architecture Jamstack hébergée par Netlify a montré que ça pouvait aller bien au delà en faisant appel à différentes APIs et microservices.\nPhil Hawksworth, nouvellement en charge des relations avec les développeurs chez Netlify a publié une liste de fonctionnalités disponibles quelle que soit la formule utilisée, même celle entièrement gratuite.\n\n\n\n\n\nMais d’abord, comment démarrer simplement\nSi vous ne connaissez pas encore ce service, sachez que c'est extrêmement simple d’héberger un site chez Netlify. Nul besoin de connaître toutes les fonctionnalités avancées pour vous lancer.\nLa manière la plus simple d’héberger un site chez Netlify est de glisser-déposer un dossier contenant vos fichiers dans un navigateur sur https:\/\/app.netlify.com.\n\n\n\n\nNetlify’s easy peasy drag and drop deployment\n\nVous pouvez aussi déployer directement grâce à l’utilitaire en ligne de commande, mais je prefère vous renvoyer à la documentation pour ça, sinon vous allez croire que j'essaie de caser discrètement des éléments en plus dans ma liste. Bon OK, c'est ce que je faisais, vous m'avez démasqué. Passons maintenant à la liste à proprement parler.\n1. Déploiements atomiques avec publication et retour en arrière immédiats\nSi vous avez déjà rencontré des problèmes de mise en production ou de déploiement sur des projets de développement web, vous apprécierez grandement cette fonctionnalité.\nChaque génération réussie sur Netlify entraîne le déploiement d’une nouvelle instance de votre site. La publication sur les différents extrémités des nœuds du réseau de CDN de Netlify et l’invalidation de cache se font automatiquement et de manière quasi-instantanée, à tel point que que je trouve inutile de mesurer combien de temps ça prend.\nLes déploiements sont immutables. Cela signifie que chaque résultat de déploiement correspond à une version du site qui ne changera jamais. Les mises à jour créent de nouvelles instances du site pour remplacer les versions précédentes (qui sont gentiment remerciées pour leur service et mises au repos, sans être supprimées pour autant). Cela veut dire que vous pouvez revenir à tout moment à une version précédente de votre site d’un simple clic dans l’interface d’administration ou via l’API.\nEn fait, tout ce que vous pouvez faire dans l’interface d’administration, vous pouvez le faire aussi avec l’API. La documentation de l’API vous explique comment faire tout cela. Je ne compte pas même pas ça comme une fonctionnalité à part entière ici, c'est juste un petit bonus de plus !\n2. Notifications et permaliens\nUne fois encore, il y a plus d’une fonctionnalité dans cet élément de ma liste, il faudra vous y faire.\nNetlify vous permet de configurer des notifications en fonction des différents types d’évènement liés à un déploiement. Vous pouvez définir qui sera informé en cas de nouveau déploiement, ou lorsqu'un déploiement réussit, échoue, est verrouillé ou déverrouillé (je ne vous ai pas dit mais on peut aussi choisir de faire pointer la version du site vers un déploiement en particulier).\nVous pouvez envoyer des notifications par mail ou sur un canal Slack (je suis fan, tous mes projets ont un canal Slack dédié à l’intégration continue). Vous pouvez même décider qu'une notification va déclencher un webhook, ajouter des messages à des commits Git ou commenter sur des pull requests.\nCe qui rend ces notifications encore plus utiles, c'est qu'elles incluent un lien unique vers le déploiement en question. Je vous ai dit que tous les déploiements sont immutables et toujours actifs. Cela signifie que chacun d’eux possède sa propre URL pour qu'on puisse y accéder et voir ce déploiement en particulier.\nAvoir des liens uniques pour chaque déploiement c'est énorme. Vous pouvez partager à tout moment n'importe quelle version de votre site avec votre équipe en charge des tests, votre client, ou n'importe qui d’autre. \"À quoi ressemblait la version 3.2.14 du site déjà ? Tiens, voilà le lien.\"\nEt cet accès instantané vous est partagé directement à chaque notification.\n3. Branches de déploiement et sous-domaines\nC’est bien pratique de pouvoir déployer d’autres branches que celle de production. Pouvoir développer de nouvelles fonctionnalités dans des branches dédiées et ensuite pouvoir les tester et les passer en revue sur votre environnement de production, c'est incroyablement puissant.\nNetlify vous permet de garder le contrôle sur la façon dont vous déployez. Vous pouvez choisir de déployer uniquement la branche de production, toutes vos branches, ou seulement certaines branches.\n\n\n\n\n\n\nParamètres du déploiement continu.\n\nUne fois déployée, chaque branche sera accessible depuis un sous-domaine généré en fonction du nom de la branche utilisée. Ça donne un truc comme ça :\nma-branche--mon-site.netlify.com\nGrâce à la gestion des DNS de Netlify, vous pouvez aussi choisir d’affecter vos propres sous-domaines à des branches. Vous avez une liberté totale pour définir comment les différentes branches vont pousser du contenu sur les différents sous-domaines de votre site.\n4. Tests A\/B, Tests A\/B avec plusieurs variantes ou tests séparés\nIl existe plusieurs variantes et termes pour désigner les tests A\/B, Netlify appelle cela le split testing parce que c'est ce que ça fait : découper le trafic de votre site entre les différentes branches de votre choix.\nVous pouvez partager le trafic de votre site en autant de branches que vous le souhaitez et définir le pourcentage de trafic attribué à chacune des branches.\n\n\n\n\n\n\nLa configuration du split testing chez Netlify.\n\nCette fonctionnalité me bluffe. Elle rend les différents types de tests A\/B vraiment trivial à mettre en place. Si vous tirez déjà parti du déploiement de branches, il n'y a pas grand-chose à faire de plus.\nVous me direz que beaucoup d’entreprises peuvent vous vendre des services de tests A\/B pour votre site. J'ai été un grand adepte de ces services. Mais la plupart, si ce n'est tous, vont faire ça en magouillant un peu à coup de JavaScript une fois votre site servi et chargé dans le navigateur.\nVu le mal qu'on se donne, en tant de développeurs web, à minimiser l’impact qu'ont les ressources externes en JavaScript sur le rendu de nos sites, c'est vraiment bête de réduire tous ces efforts à néant en introduisant un ralentissement de la performance dans notre rendu.\nDe plus, si la performance des différentes variantes que nous testons diffère de la production, alors comment pouvons nous bénéficier d’une comparaison vraiment fiable de la performance de ces options ? Les tests sont faussés.\nL'approche de Netlify c'est de servir chaque variante de test directement depuis son CDN optimisé. Tous les trucs super intelligents comme la répartition du trafic, les variantes de tests et l’assurance de la consistence d’utilisation se passent au niveau du CDN - sur les nœuds les plus proches possibles de l’utilisateur.\nChaque variante de test est servie et rendue comme sur la \"production\". Fantastique.\n5. Commandes de génération contextuelles\nNon seulement vous pouvez déployer différentes branches, mais vous pouvez aussi personnaliser le contenu et les environnements de vos déploiements en fonction de différents contextes comme la préproduction, la qualification et la production.\nIl fut un temps où c'était compliqué de mettre en place différents environnements de déploiement pour votre projet. Netlify rend les choses plus simples que je ne l’ai jamais vu. Vous pouvez créer staging.votre-projet.com et testing.votre-projet.com et tout ce que vous voulez à côté de votre www.votre-projet.com simplement à l’aide d’un peu de configuration. Et ils tournent tous sur des environnements identiques, c'est très important pour la fiabilité du développement et la stratégie de déploiement.\nVous pourriez vouloir lancer des commandes de génération légèrement différentes en fonction de l’environnement sur lequel vous déployez, ou générer une fonctionnalité pas encore disponible en production. Vous pouvez faire tout cela en configurant différents contextes de déploiement.\nCela vous permet de faire des choses comme générer la production avec npm run build:prod et une branche de fonctionnalité avec npm run build:ma-fonctionnalite. Pratique !\nCela se paramètre à l’aide d’un fichier de configuration netlify.toml qu'on peut laisser à la racine du projet pour accéder à toutes sortes d’options pour vos déploiements sur Netlify.\nPar exemple :\n\n\nExemple de fichier de configuration de site netlify.toml.\n\nVous trouverez plus d’informations à ce sujet dans la documentation des contextes de déploiement.\n6. Gestion des certificats SSL et SSL gratuit avec Let’s Encrypt\nMême si ce n'est pas forcément évident à première vue, il est très important de servir les sites web en HTTPS plutôt qu'en HTTP, même si ce sont des sites servis en statique.\nUn des créateurs de Netlify explique tout ça très bien en donnant cinq bonne raisons de servir votre site en HTTPS et Google a également publié de bons articles qui expliquent pourquoi HTTPS est si important, quelle que soit l’architecture utilisée.\nVous êtes convaincu et vous voulez acheter un certificat numérique ? N'ayez crainte, l’opération peut être bien plus simple que vous ne pourriez le penser.\nNetlify rend triviale la configuration de HTTPS sur vos noms de domaines.Vous avez le choix entre la gestion automatisée de SSL, la gestion personnalisée de SSL et même une adresse IP dédiée SSL pour les entreprises qui en ont besoin.\nLa plupart des gens peuvent se contenter de la gestion automatisée grâce aux certificats offerts par Let's Encrypt. La configuration se fait en un clic (bon ok peut-être trois, mais ça m'a pris moins d’une minute). En plus le certificat est renouvelé automatiquement, pour que vous n'ayez pas à le faire tous les ans.\n\n\n\n\n\n\nLa configuration de SSL chez Netlify avec renouvellement automatique des certificats grâce à Let’s Encrypt.\n\n7. Lancer des tests avec l’intégration continue de Netlify\nUne des choses qui fait que Netlify est très puissant c'est qu'en plus d’un réseau optimisé de CDN pour héberger vos sites, ils fournissent aussi un environnement de conteneurs pour lancer vos builds. Cela signifie que n'importe quel build lancé dans votre environnement de développement ou sur un serveur d’intégration continue peut en fait être directement exécuté sur Netlify.\nSi votre script de déploiement inclus des tests, Netlify les exécutera pour vous et qu'il en résulte un succès ou un échec, vous serez prévenus de l’issue finale.\nRemplacer mon infrastructure d’intégration continue, mon infrastructure d’hébergement ainsi que mes scripts de déploiement par un seul et unique service ? Je suis partant.\n8. Gestion des formulaires\nSi votre site a besoin d’intégrer des formulaires, vous vous êtes peut-être dit par le passé que ce n'était pas compatible avec un site statique. Pourtant Netlify propose une solution simple pour régler ce problème.\nSi vous avez besoin d’ajouter un formulaire sur votre site qui récolte des informations entrées par vos utilisateurs, Netlify peut s'en charger pour vous. En ajoutant un simple attribut au code HTML de votre formulaire, Netlify va exposer le point d’accès qui va bien pour le formulaire et rendre toutes les données postées accessibles pour vous depuis l’interface d’administration et l’API.\nComme les données sont accessibles via l’API, vous pouvez accéder à ces contenus lors de l’étape de génération afin de les utiliser sur votre site. Avec un peu d’imagination, cela ouvre pas mal de possibilités intéressantes.\nLes soumissions de formulaires peuvent aussi déclencher des notifications. Tout devient alors possible : des messages Slack, des webhooks ou même des intégrations Zapier.\n9. Redirections, réécritures et proxy\nN'oubliez aucune URL en route ! En ajoutant un fichier _redirects dans votre dossier déployé nous avez accès à tout plein d’options de configuration en ce qui concerne les redirections et les réécritures d’URLs. Elles sont déclenchées sur les nœuds finaux des CDN, ce qui les rend particulièrement rapides et efficientes.\nVous avez aussi la possibilité de préciser le code de réponse HTTP dans le fichier _redirects, ce qui vous permet de personnaliser vos erreurs 404 ou même de rendre d’autres ressources accessibles au travers d’un proxy.\nVoici un exemple :\n\n\nUn exemple de fichier de configuration _redirects.\n\nVous voulez des splats, des placeholders, des paramètres de requêtes et plus encore ? Jetez un œil à la documentation sur les redirections.\n10. Contrôle des entêtes personnalisés\nCelui là ravira toux ceux qui ont hébergé leur site sur GitHub Pages et qui ont couru après le score parfait sur Lighthouse ou Page Speed Insights. Vous avez tout bien fait, mais vous avez besoin de pouvoir définir vos entêtes de cache HTTP pour bénéficier de cette dernière optimisation de performance qui vous manque tant… malheureusement vous n'en avez pas la possibilité.\nMaintenant vous l’avez.\nNetlify utilise pour cela une approche similaire à celle de la gestion des redirections que nous venons de voir plus haut. Grâce à un fichier _headers déposé dans votre dossier de déploiement, vous pouvez ainsi contrôler les entêtes HTTP de toutes les ressources de votre site.\nEt vous pouvez faire bien plus que contrôler les entêtes de cache. La possibilité de configurer vos entêtes à l’aide de fichier _headers vous permet de définir votre politique de sécurité en matière de contenu (CSP), vos options X-Frame et plein d’autres choses toutes aussi importantes pour vous aider à contrôler la sécurité de votre site.\n\n\nUn exemple de fichier de configuration _headers.\n\nBénéficier d’une telle granularité pour ce type de contrôle est souvent bien plus complexe que cela. Il me semble que cette fonctionnalité rend accessible le contrôle de la sécurité à davantage de développeurs.\nÇa en fait 10, mais ce n'est pas tout\nJ'aurais pu mentionner bien d’autres choses, mais vous ne voulez pas d’une liste interminable.\nPlus je creuse, plus je découvre qu'il est possible de contrôler pas mal de choses. Il est important que les développeurs puissent bénéficier d’une solution simple pour mettre en ligne leurs sites statiques, et comme l’écosystème de la Jamstack évolue en permanence, les possibilités sont de plus en plus grandes.\nÇa vaut le coup de garder un œil sur Netlify, d’autres fonctionnalités prometteuses sont actuellement testées par des alpha-testeurs enthousiastes.\nVous pouvez suivre Netlify sur Twitter pour rester informé des nouvelles fonctionnalités, plonger dans la documentation, ou prendre connaissance des nos projets open source pour étendre les possibilités de l’écosystème Jamstack.", "content_html": "\n\n\n\n\"Image\n\n

Mais d’abord, comment démarrer simplement

\n

Si vous ne connaissez pas encore ce service, sachez que c'est extrêmement simple d’héberger un site chez Netlify. Nul besoin de connaître toutes les fonctionnalités avancées pour vous lancer.

\n

La manière la plus simple d’héberger un site chez Netlify est de glisser-déposer un dossier contenant vos fichiers dans un navigateur sur https://app.netlify.com.

\n

\n
\n\n
\n
Netlify’s easy peasy drag and drop deployment
\n

\n

Vous pouvez aussi déployer directement grâce à l’utilitaire en ligne de commande, mais je prefère vous renvoyer à la documentation pour ça, sinon vous allez croire que j'essaie de caser discrètement des éléments en plus dans ma liste. Bon OK, c'est ce que je faisais, vous m'avez démasqué. Passons maintenant à la liste à proprement parler.

\n

1. Déploiements atomiques avec publication et retour en arrière immédiats

\n

Si vous avez déjà rencontré des problèmes de mise en production ou de déploiement sur des projets de développement web, vous apprécierez grandement cette fonctionnalité.

\n

Chaque génération réussie sur Netlify entraîne le déploiement d’une nouvelle instance de votre site. La publication sur les différents extrémités des nœuds du réseau de CDN de Netlify et l’invalidation de cache se font automatiquement et de manière quasi-instantanée, à tel point que que je trouve inutile de mesurer combien de temps ça prend.

\n

Les déploiements sont immutables. Cela signifie que chaque résultat de déploiement correspond à une version du site qui ne changera jamais. Les mises à jour créent de nouvelles instances du site pour remplacer les versions précédentes (qui sont gentiment remerciées pour leur service et mises au repos, sans être supprimées pour autant). Cela veut dire que vous pouvez revenir à tout moment à une version précédente de votre site d’un simple clic dans l’interface d’administration ou via l’API.

\n

En fait, tout ce que vous pouvez faire dans l’interface d’administration, vous pouvez le faire aussi avec l’API. La documentation de l’API vous explique comment faire tout cela. Je ne compte pas même pas ça comme une fonctionnalité à part entière ici, c'est juste un petit bonus de plus !

\n

2. Notifications et permaliens

\n

Une fois encore, il y a plus d’une fonctionnalité dans cet élément de ma liste, il faudra vous y faire.

\n

Netlify vous permet de configurer des notifications en fonction des différents types d’évènement liés à un déploiement. Vous pouvez définir qui sera informé en cas de nouveau déploiement, ou lorsqu'un déploiement réussit, échoue, est verrouillé ou déverrouillé (je ne vous ai pas dit mais on peut aussi choisir de faire pointer la version du site vers un déploiement en particulier).

\n

Vous pouvez envoyer des notifications par mail ou sur un canal Slack (je suis fan, tous mes projets ont un canal Slack dédié à l’intégration continue). Vous pouvez même décider qu'une notification va déclencher un webhook, ajouter des messages à des commits Git ou commenter sur des pull requests.

\n

Ce qui rend ces notifications encore plus utiles, c'est qu'elles incluent un lien unique vers le déploiement en question. Je vous ai dit que tous les déploiements sont immutables et toujours actifs. Cela signifie que chacun d’eux possède sa propre URL pour qu'on puisse y accéder et voir ce déploiement en particulier.

\n

Avoir des liens uniques pour chaque déploiement c'est énorme. Vous pouvez partager à tout moment n'importe quelle version de votre site avec votre équipe en charge des tests, votre client, ou n'importe qui d’autre. \"À quoi ressemblait la version 3.2.14 du site déjà ? Tiens, voilà le lien.\"

\n

Et cet accès instantané vous est partagé directement à chaque notification.

\n

3. Branches de déploiement et sous-domaines

\n

C’est bien pratique de pouvoir déployer d’autres branches que celle de production. Pouvoir développer de nouvelles fonctionnalités dans des branches dédiées et ensuite pouvoir les tester et les passer en revue sur votre environnement de production, c'est incroyablement puissant.

\n

Netlify vous permet de garder le contrôle sur la façon dont vous déployez. Vous pouvez choisir de déployer uniquement la branche de production, toutes vos branches, ou seulement certaines branches.

\n
\n\n\n\n\"Paramètres\n\n
Paramètres du déploiement continu.
\n
\n

Une fois déployée, chaque branche sera accessible depuis un sous-domaine généré en fonction du nom de la branche utilisée. Ça donne un truc comme ça :

\n

ma-branche--mon-site.netlify.com

\n

Grâce à la gestion des DNS de Netlify, vous pouvez aussi choisir d’affecter vos propres sous-domaines à des branches. Vous avez une liberté totale pour définir comment les différentes branches vont pousser du contenu sur les différents sous-domaines de votre site.

\n

4. Tests A/B, Tests A/B avec plusieurs variantes ou tests séparés

\n

Il existe plusieurs variantes et termes pour désigner les tests A/B, Netlify appelle cela le split testing parce que c'est ce que ça fait : découper le trafic de votre site entre les différentes branches de votre choix.

\n

Vous pouvez partager le trafic de votre site en autant de branches que vous le souhaitez et définir le pourcentage de trafic attribué à chacune des branches.

\n
\n\n\n\n\"La\n\n
La configuration du split testing chez Netlify.
\n
\n

Cette fonctionnalité me bluffe. Elle rend les différents types de tests A/B vraiment trivial à mettre en place. Si vous tirez déjà parti du déploiement de branches, il n'y a pas grand-chose à faire de plus.

\n

Vous me direz que beaucoup d’entreprises peuvent vous vendre des services de tests A/B pour votre site. J'ai été un grand adepte de ces services. Mais la plupart, si ce n'est tous, vont faire ça en magouillant un peu à coup de JavaScript une fois votre site servi et chargé dans le navigateur.

\n

Vu le mal qu'on se donne, en tant de développeurs web, à minimiser l’impact qu'ont les ressources externes en JavaScript sur le rendu de nos sites, c'est vraiment bête de réduire tous ces efforts à néant en introduisant un ralentissement de la performance dans notre rendu.

\n

De plus, si la performance des différentes variantes que nous testons diffère de la production, alors comment pouvons nous bénéficier d’une comparaison vraiment fiable de la performance de ces options ? Les tests sont faussés.

\n

L'approche de Netlify c'est de servir chaque variante de test directement depuis son CDN optimisé. Tous les trucs super intelligents comme la répartition du trafic, les variantes de tests et l’assurance de la consistence d’utilisation se passent au niveau du CDN - sur les nœuds les plus proches possibles de l’utilisateur.

\n

Chaque variante de test est servie et rendue comme sur la \"production\". Fantastique.

\n

5. Commandes de génération contextuelles

\n

Non seulement vous pouvez déployer différentes branches, mais vous pouvez aussi personnaliser le contenu et les environnements de vos déploiements en fonction de différents contextes comme la préproduction, la qualification et la production.

\n

Il fut un temps où c'était compliqué de mettre en place différents environnements de déploiement pour votre projet. Netlify rend les choses plus simples que je ne l’ai jamais vu. Vous pouvez créer staging.votre-projet.com et testing.votre-projet.com et tout ce que vous voulez à côté de votre www.votre-projet.com simplement à l’aide d’un peu de configuration. Et ils tournent tous sur des environnements identiques, c'est très important pour la fiabilité du développement et la stratégie de déploiement.

\n

Vous pourriez vouloir lancer des commandes de génération légèrement différentes en fonction de l’environnement sur lequel vous déployez, ou générer une fonctionnalité pas encore disponible en production. Vous pouvez faire tout cela en configurant différents contextes de déploiement.

\n

Cela vous permet de faire des choses comme générer la production avec npm run build:prod et une branche de fonctionnalité avec npm run build:ma-fonctionnalite. Pratique !

\n

Cela se paramètre à l’aide d’un fichier de configuration netlify.toml qu'on peut laisser à la racine du projet pour accéder à toutes sortes d’options pour vos déploiements sur Netlify.

\n

Par exemple :

\n

\n\n\n

Jekyll peut paraître un peu déroutant au début. En effet\nJekyll ne fait pas grand-chose à vos fichiers, si ce n'est qu'il les classifie\nde différentes façons.

\n

Jekyll va soit copier, soit omettre, soit transformer les fichiers du répertoire\nsource dans le répertoire de destination[^1]. Lorsque Jekyll transforme vos\nfichiers, c'est toujours de cette manière, si ce n'est que la deuxième étape\npeut être potentiellement sautée.[^2]

\n

Si un fichier commence par une entête\nYAML Front Matter Jekyll va appliquer\nles transformations suivante au fichier:

\n
    \n
  1. Interprétation du code Liquid : Le contenu du fichier est d’abord\nparcouru par le parser de Liquid, les\nvariables comme site ou page auxquelles le modèle Liquid veut accéder\nsont alors interprétées.
    2. \n
  2. Conversion du contenu : en fonction de l’extension de fichier, Jekyll\nfait appel à un convertisseur dédié, par example Kramdown pour les fichiers\n.md ou .markdown, qui est chargé de convertir le résultat obtenu après\nl’étape 1.
    3. \n
  3. Parsing du modèle: Le résultat de cette conversion est alors transmis\ndans la variable {{content}}, soit au modèle de page par défaut, soit à\ncelui qui est spécifié dans l’entête YAML Front Matter.
    4. \n
  4. Le résultat de cette dernière conversion du modèle de page, généralement un\nfichier HTML, est écrit dans votre répertoire de destination.
    5. \n
\n

J'aimerais maintenant vous montrer un exemple où Jekyll applique cette\ntransformation. Ensuite, lors d’un\ntest complet de génération de site, nous\nirons étudier la structure générale de l’algorithme au\ncœur de Jekyll pour voir quels traitements sont effectués\nsur les différents types de fichiers.

\n

La transformation de Jekyll

\n

Le mécanisme de transformation de Jekyll est situé dans\nla méthode run du fichier renderer,\nqui fait essentiellement la chose suivante, en sautant potentiellement quelques\nétapes :

\n
after_liquid = render_with_liquid(file_content) # line 62\nafter_markdown = convert(after_liquid) # line 66\nplace_in_layout(after_markdown) # line 71
\n

Donc si nous transformons l’article présent dans le thème par défaut de Jekyll :

\n
---\nlayout: post\ntitle: \"Bienvenue dans Jekyll !\"\ndate: 2016-08-17 13:50:36 +0100\ncategories: jekyll update\n---\n\nYou’ll find this post in your `_posts` directory. Go ahead and edit it and\nre-build the site to see your changes. You can rebuild the site in many\ndifferent ways, but the most common way is to run `jekyll serve`, which launches\na web server and auto-regenerates your site when a file is updated.\n\nTo add new posts, simply add a file in the `_posts` directory that follows the\nconvention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front\nmatter. Take a look at the source for this post to get an idea about how it\nworks.\n\nJekyll also offers powerful support for code snippets:\n\n    def print_hi(name)\n      puts \"Hi, #{name}\"\n    end\n    print_hi('Tom')\n    #=> prints 'Hi, Tom' to STDOUT.\n\nCheck out the [Jekyll docs][jekyll-docs] for more info on how to get the most\nout of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub\nrepo][jekyll-gh]. If you have questions, you can ask them on [Jekyll\nTalk][jekyll-talk].\n\n[jekyll-docs]: https://jekyllrb.com/docs/home\n[jekyll-gh]: https://github.com/jekyll/jekyll\n[jekyll-talk]: https://talk.jekyllrb.com/
\n

…vous pouvez voir le résultat des deux premières étapes de la transformation :

\n
\n
En entrée
\n
1. Liquidifié
\n
2. Converti
\n
\n 
\nYou’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.\n\nTo add new posts, simply add a file in the `_posts` directory that follows the\nconvention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front\nmatter. Take a look at the source for this post to get an idea about how it\nworks.\n\nJekyll also offers powerful support for code snippets:\n\n    def print_hi(name)\n      puts \"Hi, #{name}\"\n    end\n    print_hi('Tom')\n    #=> prints 'Hi, Tom' to STDOUT.\n\nCheck out the [Jekyll docs][jekyll-docs] for more info on how to get the most\nout of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub\nrepo][jekyll-gh]. If you have questions, you can ask them on [Jekyll\nTalk][jekyll-talk].\n\n[jekyll-docs]: https://jekyllrb.com/docs/home\n[jekyll-gh]: https://github.com/jekyll/jekyll\n[jekyll-talk]: https://talk.jekyllrb.com/\n\n
\n\n
\n\n
\n 
\nYou’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.\n\nTo add new posts, simply add a file in the `_posts` directory that follows the\nconvention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front\nmatter. Take a look at the source for this post to get an idea about how it\nworks.\n\nJekyll also offers powerful support for code snippets:\n\n
def print_hi(name)\n  puts \"Hi, \\#{name}\"\nend\nprint_hi('Tom')\n\n #=> prints 'Hi, Tom' to STDOUT.
\n\nCheck out the [Jekyll docs][jekyll-docs] for more info on how to get the most\nout of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub\nrepo][jekyll-gh]. If you have questions, you can ask them on [Jekyll\nTalk][jekyll-talk].\n\n[jekyll-docs]: https://jekyllrb.com/docs/home\n[jekyll-gh]: https://github.com/jekyll/jekyll\n[jekyll-talk]: https://talk.jekyllrb.com/\n\n
\n\n
\n
\n 
\n
You’ll find this post in your _posts directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run jekyll serve, which launches a web server and auto-regenerates your site when a file is updated.
\n
To add new posts, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.ext and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
\n
Jekyll also offers powerful support for code snippets:
\n
def print_hi(name)\n  puts \"Hi, \\#{name}\"\nend\nprint_hi('Tom')\n#=> prints 'Hi, Tom' to STDOUT.
\n
Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.
\n
\n
\n
\n

Puis vient la dernière étape où nous mettons tout cela dans la variable\n{{content}} de notre modèle :

\n
\n
Modèle
\n
3. Résultat final
\n 
\n
\n\n  
\n    
{{ page.title | escape }}
\n    
{% if page.author %} • {{ page.author }}{% endif %}
\n  
\n\n  
\n    {{ content }}\n  
\n\n
\n
\n
\n
\n
\n\n  
\n    
Welcome to Jekyll!
\n    
\n  
\n\n  
\n    
You’ll find this post in your _posts directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run jekyll serve, which launches a web server and auto-regenerates your site when a file is updated.
\n\n    
To add new posts, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.ext and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
\n\n    
Jekyll also offers powerful support for code snippets:
\n\n    
\n    def print_hi(name)\n    puts \"Hi, \\#{name}\"\n    end\n    print_hi('Tom')\n    #=> prints 'Hi, Tom' to STDOUT.
\n    
\n\n    
Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.
\n\n  
\n\n
\n
\n
\n
\n

Ceci est juste un exemple de conversion avec kramdown pour le markdown et\nd’insertion du résultat dans un modèle. Jekyll intègre d’autres convertisseurs\ncomme\nsmartypants.\nJekyll inclut aussi par défaut un\nconvertisseur pour Sass dans\nle\nfichier de spécification de sa gem Ruby,\nqui n'est pas un convertisseur intégré, mais vous comprendrez quand vous\nlancerez la commande jekyll new. Vous pouvez installer d’autres convertisseurs\nà l’aide de plugins. Les modèles sont des fichiers qui sont soit stockés dans\nvotre dossier _layouts, soit dans celui empaqueté dans la gem du thème utilisé\npar votre fichier de configuration.

\n

Le cœur de Jekyll

\n

Maintenant que vous comprenez l’étape de transformation de Jekyll, regardons\ncomme elle s'intègre dans un processus de génération de site plus global à\npartir de fichiers en entrée.

\n

Si nous pitons le code exécuté lors de l’invocation de la commande\njekyll build, nous nous apercevons que\nsite.process\nreprésente le cœur de Jekyll. Vous trouverez les parties importantes un peu plus\nbas accompagnées de mes commentaires explicatifs. Reportez-vous à\nla partie sur le debug si vous souhaitez vous baladez à votre tour\ndans l’appel de la méthode.

\n
# Public: Lit, processe et écrit le Site dans la destination.\n#\n# Ne retourne rien.\ndef process\n  reset # vide tous les layouts/pages/static_file/data/collections du site.\n  read # lit les fichiers de votre répértoire et les stocke dans un objet Site, les classer dépend\n  # d’où ils se trouvent, ce qu'ils contiennent et de votre fichier de configuration.\n  generate # Vous donne la chance de lancer des générateurs pour ajouter plus de choses au site..\n  render # c'est la méthode chargée de la conversion.\n  cleanup # se débarasse de tous les fichiers qui auraient pu restés d’une génération précédente ou qui traitent des metadonnées.\n  write # écrit les fichiers dans votre dossier de destination.\n  print_stats\nend
\n

render applique la transformation de Jekyll aux fichiers qui possèdent une\nentête YAML Front Matter. Les\ndocuments sont créés à partir des fichiers de collection qui possèdent des\nentêtes YAML Front Matter et les pages sont d’autres documents avec des entêtes\nYAML. Vous devez déclarer les collections dans votre fichier _config.yml,\ncomme ça vous saurez que vous en avez. Vous devez également savoir que\nles posts et les brouillons de posts sont simplement des collections spéciales,\nce sont donc aussi des documents.

\n
def render\n    …\n    render_docs(payload) # cette fonction s'occupe du rendu des fichiers de collections qui possèdent des entêtes Front Matter, y compris le dossier _posts (les brouillons sont ajoutés aux posts avec l’option --drafts)\n    render_pages(payload) # cette fonction s'occupe du rendu des fichiers qui n'appartiennent pas à des collections mais qui ont des entêtes Front Matter\n    # cela peut être vos fichiers `feed.xml`, `index.html`, `main.scss`, etc.\n    …\nend\n…\n\ndef render_docs(payload)\n  collections.each do |_, collection|\n    collection.docs.each do |document|\n      if regenerator.regenerate?(document)\n        document.output = Jekyll::Renderer.new(self, document, payload).run\n        document.trigger_hooks(:post_render)\n      end\n    end\n  end\nend\n…\ndef render_pages(payload)\n  pages.flatten.each do |page|\n    if regenerator.regenerate?(page)\n      page.output = Jekyll::Renderer.new(self, page, payload).run\n      page.trigger_hooks(:post_render)\n    end\n  end\nend
\n

Test exhaustif d’une génération

\n

Regardons à présent ce que nous obtenons lors d’un exemple de génération à\npartir de quelques types de fichiers dans différents répertoires, avec et sans\nl’option --drafts (active ou non la génération des brouillons). Le conteneur\nDocker de ce test est dispos sur\nbytesandwich/jekyll-outcomes.

\n

Il recopie ces fichiers :

\n\n

… dans chacun de ces répertoires :

\n\n

Sauf que pour chaque association de fichier et de répertoire, le nom du\nrépertoire de destination est ajouté à la fin du fichier de manière à ce que\nnous puissions mieux appréhender les corresponsances entre les fichiers d’entrée\net les fichiers de sortie. Vous retrouvez un aperçu du résultat de la commande\ntree après les deux tableaux.

\n

J'ai fait un tableau avec une ligne par répertoire et une colonne par fichier,\nla cellule contient l’opération effectuée sur le fichier, qui peut être :

\n\n

Génération des fichiers sans l’option brouillons

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
 text.txtfrontmatter-not-post.md2016-05-05-post-without-frontmatter.mdyaml.yml2020-02-02-post-future.md2016-05-05-post-normal.md
/copiétransformécopiécopiétransformétransformé
/postsomisomispost transforméomisomispost transformé
/draftsomisomisomisomisomisomis
/dataomisomisomisomisomisomis
/my_output_collectioncopiétransformécopiécopiéomistransformé
/my_non_output_collectioncopiéomiscopiécopiéomisomis
/underscore_diromisomisomisomisomisomis
/regular_dircopiétransformécopiécopiétransformétransformé
\n

Génération des fichiers avec l’option brouillon

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
 text.txtfrontmatter-not-post.md2016-05-05-post-without-frontmatter.mdyaml.yml2020-02-02-post-future.md2016-05-05-post-normal.md
/copiétransformécopiécopiétransformétransformé
/postsomisomispost transforméomisomispost transformé
/draftsAucunepost transformépost transformépost transforméomispost transformé
/dataomisomisomisomisomisomis
/my_output_collectioncopiétransformécopiécopiéomistransformé
/my_non_output_collectioncopiéomiscopiécopiéomisomis
/underscore_diromisomisomisomisomisomis
/regular_dircopiétransformécopiécopiétransformétransformé
\n
\n
Source
\n
Site
\n
Site avec les brouillons
\n 
\nbash-4.3# tree .\n.\n├── 2016-05-05-post-normal.md\n├── 2016-05-05-post-without-frontmatter.md\n├── 2020-02-02-post-future.md\n├── Gemfile\n├── Gemfile.lock\n├── _config.yml\n├── _data\n│   ├── 2016-05-05-post-normal-data.md\n│   ├── 2016-05-05-post-without-frontmatter-data.md\n│   ├── 2020-02-02-post-future-data.md\n│   ├── frontmatter-not-post-data.md\n│   ├── text-data.txt\n│   └── yaml-data.yml\n├── _drafts\n│   ├── 2016-05-05-post-normal-drafts.md\n│   ├── 2016-05-05-post-without-frontmatter-drafts.md\n│   ├── 2020-02-02-post-future-drafts.md\n│   ├── frontmatter-not-post-drafts.md\n│   ├── text-drafts.txt\n│   └── yaml-drafts.yml\n├── _layouts\n│   └── special.html\n├── _my_non_output_collection\n│   ├── 2016-05-05-post-normal-my_non_output_collection.md\n│   ├── 2016-05-05-post-without-frontmatter-my_non_output_collection.md\n│   ├── 2020-02-02-post-future-my_non_output_collection.md\n│   ├── frontmatter-not-post-my_non_output_collection.md\n│   ├── text-my_non_output_collection.txt\n│   └── yaml-my_non_output_collection.yml\n├── _my_output_collection\n│   ├── 2016-05-05-post-normal-my_output_collection.md\n│   ├── 2016-05-05-post-without-frontmatter-my_output_collection.md\n│   ├── 2020-02-02-post-future-my_output_collection.md\n│   ├── frontmatter-not-post-my_output_collection.md\n│   ├── text-my_output_collection.txt\n│   └── yaml-my_output_collection.yml\n├── _posts\n│   ├── 2016-05-05-post-normal-posts.md\n│   ├── 2016-05-05-post-without-frontmatter-posts.md\n│   ├── 2016-09-14-welcome-to-jekyll.markdown\n│   ├── 2020-02-02-post-future-posts.md\n│   ├── frontmatter-not-post-posts.md\n│   ├── text-posts.txt\n│   └── yaml-posts.yml\n├── _underscore_dir\n│   ├── 2016-05-05-post-normal-underscore_dir.md\n│   ├── 2016-05-05-post-without-frontmatter-underscore_dir.md\n│   ├── 2020-02-02-post-future-underscore_dir.md\n│   ├── frontmatter-not-post-underscore_dir.md\n│   ├── text-underscore_dir.txt\n│   └── yaml-underscore_dir.yml\n├── about.md\n├── css\n│   └── main.scss\n├── feed.xml\n├── frontmatter-not-post.md\n├── index.html\n├── regular_dir\n│   ├── 2016-05-05-post-normal-regular_dir.md\n│   ├── 2016-05-05-post-without-frontmatter-regular_dir.md\n│   ├── 2020-02-02-post-future-regular_dir.md\n│   ├── frontmatter-not-post-regular_dir.md\n│   ├── text-regular_dir.txt\n│   └── yaml-regular_dir.yml\n├── text.txt\n└── yaml.yml\n\n9 directories, 57 files
\n\n
\n 
\nbash-4.3# tree _site\n_site\n├── 2016\n│   └── 05\n│       └── 05\n│           ├── post-normal-posts.html\n│           └── post-without-frontmatter-posts.html\n├── 2016-05-05-post-normal.html\n├── 2016-05-05-post-without-frontmatter.md\n├── 2020-02-02-post-future.html\n├── Gemfile\n├── Gemfile.lock\n├── about\n│   └── index.html\n├── css\n│   └── main.css\n├── feed.xml\n├── frontmatter-not-post.html\n├── index.html\n├── jekyll\n│   └── update\n│       └── 2016\n│           └── 09\n│               └── 14\n│                   └── welcome-to-jekyll.html\n├── my_non_output_collection\n│   ├── 2016-05-05-post-without-frontmatter-my_non_output_collection.md\n│   ├── text-my_non_output_collection.txt\n│   └── yaml-my_non_output_collection.yml\n├── my_output_collection\n│   ├── 2016-05-05-post-normal-my_output_collection.html\n│   ├── 2016-05-05-post-without-frontmatter-my_output_collection.md\n│   ├── frontmatter-not-post-my_output_collection.html\n│   ├── text-my_output_collection.txt\n│   └── yaml-my_output_collection.yml\n├── regular_dir\n│   ├── 2016-05-05-post-normal-regular_dir.html\n│   ├── 2016-05-05-post-without-frontmatter-regular_dir.md\n│   ├── 2020-02-02-post-future-regular_dir.html\n│   ├── frontmatter-not-post-regular_dir.html\n│   ├── text-regular_dir.txt\n│   └── yaml-regular_dir.yml\n├── text.txt\n└── yaml.yml\n\n13 directories, 29 files
\n\n
\nbash-4.3# tree _site\n_site\n├── 2016\n│   ├── 05\n│   │   └── 05\n│   │       ├── post-normal-drafts.html\n│   │       ├── post-normal-posts.html\n│   │       ├── post-without-frontmatter-drafts.html\n│   │       └── post-without-frontmatter-posts.html\n│   └── 09\n│       └── 14\n│           ├── frontmatter-not-post-drafts.html\n│           ├── text-drafts.txt\n│           └── yaml-drafts.yml\n├── 2016-05-05-post-normal.html\n├── 2016-05-05-post-without-frontmatter.md\n├── 2020-02-02-post-future.html\n├── Gemfile\n├── Gemfile.lock\n├── about\n│   └── index.html\n├── css\n│   └── main.css\n├── feed.xml\n├── frontmatter-not-post.html\n├── index.html\n├── jekyll\n│   └── update\n│       └── 2016\n│           └── 09\n│               └── 14\n│                   └── welcome-to-jekyll.html\n├── my_non_output_collection\n│   ├── 2016-05-05-post-without-frontmatter-my_non_output_collection.md\n│   ├── text-my_non_output_collection.txt\n│   └── yaml-my_non_output_collection.yml\n├── my_output_collection\n│   ├── 2016-05-05-post-normal-my_output_collection.html\n│   ├── 2016-05-05-post-without-frontmatter-my_output_collection.md\n│   ├── frontmatter-not-post-my_output_collection.html\n│   ├── text-my_output_collection.txt\n│   └── yaml-my_output_collection.yml\n├── regular_dir\n│   ├── 2016-05-05-post-normal-regular_dir.html\n│   ├── 2016-05-05-post-without-frontmatter-regular_dir.md\n│   ├── 2020-02-02-post-future-regular_dir.html\n│   ├── frontmatter-not-post-regular_dir.html\n│   ├── text-regular_dir.txt\n│   └── yaml-regular_dir.yml\n├── text.txt\n└── yaml.yml\n\n15 directories, 34 files
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2016/12/09/des-commentaires-statiques-avec-jekyll-et-staticman/", "url": "https://jamstatic.fr/2016/12/09/des-commentaires-statiques-avec-jekyll-et-staticman/", "title": "Des commentaires statiques avec Jekyll et Staticman", "summary": "Utilisation de Staticman pour ajouter des commentaires et des notifications de réponses sur un site statique sous Jekyll", "date_published": "2016-12-09T00:00:00+00:00","content_text": "Michael Rose, l’auteur du thème Jekyll Minimal Mistakes, revient sur les détails de l’implémentation de commentaires statiques — les commentaires sont versionnés au format YAML dans le dépôt GitHub — à l’aide de Staticman, un service open-source développé par Eduardo Bouças, qui permet d’insérer des contenus générés par les utilisateurs sur un site plus si statique que ça, proposant ainsi une alternative à Disqus au même titre que Jekyll AWS comment.\nDepuis que j'ai quitté Disqus pour un système de commentaires statiques, Staticman a muri avec des ajouts de fonctionnalités comme les fils de commentaires et les notifications par mail.\nÀ l’aide des instructions fournies par Eduardo Bouças dans cette issue GitHub, je me suis lancé dans l’amélioration de l’expérience relative aux commentaires sur Made Mistakes. Voici comme j'ai procédé.\nPasser à la version 2 de Staticman\nPour tirer parti de ces nouvelles fonctionnalités, il était nécessaire de migrer les paramètres de Staticman du fichier _config.yml de Jekyll vers un nouveau fichier staticman.yml1. Comme il n'y a eu aucun changement dans les paramètres, la transition vers la version 2 était grandement simplifiée.\ncomments:\n allowedFields : ['name', 'email', 'url', 'message']\n branch : \"master\"\n commitMessage : \"Nouveau commentaire.\"\n filename : \"commentaire-{@timestamp}\"\n format : \"yaml\"\n moderation : true\n path : \"src\/_data\/comments\/{options.slug}\"\n requiredFields : ['name', 'email', 'message']\n transforms:\n email : md5\n generatedFields:\n date:\n type : \"date\"\n options:\n format : \"iso8601\"\nNouvelles options de configuration\nAssurez-vous de jeter un œil au modèle de fichier de configuration et à la liste complète des paramètres pour vous faire une idée des possibilités de configuration.\nPar exemple, vous pouvez configurer plusieurs propriétés (commentaires, avis et autres types de contenus générés par les utilisateurs), modifier le message de commit et le corps de texte de la pull request, activer les notifications par mail et bien plus à partir du fichier staticman.yml.\nSupprimer\/Ajouter Staticman en tant que collaborateur\nJe ne suis pas vraiment certain que l’opération suivante soit nécessaire. Je me suis heurté à des erreurs lors de mes tests de commentaires et cela a eu l’air de régler le problème. Il est possible que je me sois trompé quelque part ailleurs dans la configuration et que l’origine du problème était ailleurs…\nQuoi qu’il en soit, vous pouvez toujours partager votre expérience de la mise à jour de la version 1 à la version 2 de Staticman dans les commentaires de ce billet.\n\nRévoquez les droits de collaboration de Staticman v1 dans les paramètres de votre dépôt GitHub. \n\n\n\n\n\nAjoutez de nouveau Staticman en tant que collaborateur.\nFaites un appel sur ce endpoint de la version 2 de l’API https:\/\/api.staticman.net\/v2\/connect\/{votre nom d’utilisateur GitHub}\/{nom de votre dépôt} pour accepter l’invitation de collaboration.\n\nMettre à jour l’appel POST du formulaire de commentaires\nPour faire une requête POST correcte à Staticman, l’attribut action de mon formulaire de commentaire avait besoin d’une petite mise à jour. Remplacer v1 par v2 dans _includes\/page__comments.html, puis suffixer avec \/comments2 et le tour était joué pour moi.\n<form\n id=\"comment-form\"\n class=\"page__form js-form form\"\n method=\"post\"\n action=\"https:\/\/api.staticman.net\/v2\/entry\/{{ site.repository }}\/{{ site.staticman.branch }}\/comments\"\n><\/form>\nAjout du support des fils de commentaires\nRéussir à faire marcher les commentaires imbriqués s'est révélé assez pénible. Plusieurs erreurs Liquid, plusieurs tentatives avant d’arriver à faire marcher des boucles for à l’intérieur d’autres boucles for, des filtres de tableau qui pétaient des trucs et tout un tas de galères font que j'ai mis un moment avant de m'en sortir.\nAjout d’un identifiant au parent\nPour imbriquer correctement les réponses, j'avais besoin de pouvoir déterminer leur hiérarchie. La v2 de Staticman possède un nouveau champ nommé options[parent]3 qui peut être utilisé pour aider à établir cette relation. Avant d’aller plus loin, ajoutons déjà cet identifiant à mon formulaire dans un champ caché.\n<input type=\"hidden\" id=\"comment-parent\" name=\"options[parent]\" value=\"\" \/>\nMise à jour des boucles Liquid\nAfin d’éviter d’afficher des doublons, j'avais besoin d’exclure les réponses et de ne montrer que les commentaires parents dans la boucle principale. C'était le moment idéal pour utiliser le filtre where_exp de Jekyll.\nLe filtre d’expression where de Jekyll\nSélectionne tous les objets d’un tableau pour lesquels la condition est vraie, depuis la version 3.2.0 de Jekyll.\nExemple: site.members | where_exp:\"item\",\"item.graduation_year == 2014\"\nSi le champ caché options[parent] que j'ai ajouté au formulaire fonctionne correctement, je devrais obtenir des fichiers de données de commentaires similaires à ceux-ci :\nExemple de commentaire parent\nmessage: Ceci est le message du commentaire parent\nname: Prénom Nom\nemail: md5g1bb3r15h\ndate: 2016-11-30T22:03:15.286Z\nExemple de commentaire enfant\n_parent: 7\nmessage: Ceci est un message de commentaire enfant\nname: Prénom Nom\nemail: md5g1bb3r15h\ndate: 2016-11-02T05:08:43.280Z\nComme vous pouvez le voir ci-dessus, le commentaire \"enfant\" a une donnée _parent renseignée à partir du champ caché options[parent] du formulaire.\nSachant cela, j'ai tenté d’utiliser where_exp:\"item\",\"item._parent == nil\" pour créer un tableau ne contenant que les commentaires \"parents\".\nMalheureusement, le code suivant n'a pas marché :\n{% assign comments = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == nil\" %}\n{% for comment in comments %}\n {% assign avatar = comment[1].avatar %}\n {% assign email = comment[1].email %}\n {% assign name = comment[1].name %}\n {% assign url = comment[1].url %}\n {% assign date = comment[1].date %}\n {% assign message = comment[1].message %}\n {% include comment.html index=forloop.index avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}\nÀ la place, j'ai eu tout un tas de commentaires vides avec le balisage suivant :\n<article id=\"comment-1\" class=\"js-comment comment\">\n <div class=\"comment__avatar\">\n <img src=\"\" alt=\"\" \/>\n <\/div>\n <h3 class=\"comment__author-name\"><\/h3>\n <div class=\"comment__timestamp\">\n <a href=\"#comment-1\" title=\"Permalien vers ce commentaire\">\n <time datetime=\"\"><\/time>\n <\/a>\n <\/div>\n <div class=\"comment__content\"><\/div>\n<\/article>\nHmm… j'imagine qu'il était temps d’ajouter des filtres inspect à mes tableaux pour voir ce qui se passait.\n{{ site.data.comments[page.slug] | inspect }}\nExemple de tableau avant filtrage avec where_exp\n{\n \"comment-1471818805944\" => {\n \"message\" => \"Ceci est un message de commentaire parent.\",\n \"name\" => \"Prénom Nom\",\n \"email\" => \"md5g1bb3r15h\",\n \"url\" => \"\",\n \"hidden\" => \"\",\n \"date\" => \"2016-08-21T22:33:25.272Z\"\n },\n \"comment-1471904599908\" => {\n \"message\" => \"Ceci est un autre message de commentaire parent.\",\n \"name\" => \"Prénom Nom\",\n \"email\" => \"md5g1bb3r15h\",\n \"url\" => \"\",\n \"hidden\" => \"\",\n \"date\" => \"2016-08-22T21:42:48.075Z\"\n }\n}\nExemple de tableau après filtrage avec where_exp\n[\n {\n \"message\" => \"Ceci est un message de commentaire parent.\",\n \"name\" => \"Prénom Nom\",\n \"email\" => \"md5g1bb3r15h\",\n \"url\" => \"\",\n \"hidden\" => \"\",\n \"date\" => \"2016-08-21T22:33:25.272Z\"\n },\n {\n \"message\" => \"Ceci est un autre message de commentaire parent.\",\n \"name\" => \"Prénom Nom\",\n \"email\" => \"md5g1bb3r15h\",\n \"url\" => \"\",\n \"hidden\" => \"\",\n \"date\" => \"2016-08-22T21:42:48.075Z\"\n }\n]\nApparemment l’utilisation du filtre where_exp aplatit quelque peu les choses en supprimant les objets comment-xxxxxxxxxxxxx. Cela fait que mes tags assign retournent des valeurs nulles parce que comment[1] n'existe plus.\n{% assign avatar = comment[1].avatar %}\n{% assign email = comment[1].email %}\n{% assign name = comment[1].name %}\n{% assign url = comment[1].url %}\n{% assign date = comment[1].date %}\n{% assign message = comment[1].message %}\nUne fois cela découvert, la solution était simple --- supprimer [1] pour chacun des noms des propriétés.\n{% assign avatar = comment.avatar %}\n{% assign email = comment.email %}\n{% assign name = comment.name %}\n{% assign url = comment.url %}\n{% assign date = comment.date %}\n{% assign message = comment.message %}\n\n\n\n\n\n\nÇa marche, nous avons des commentaires parents.\n\nNote : sort et les filtres where ne font pas bon ménage\nJe suis tombé sur des comportements étranges et des erreurs dus à l’utilisation du filtre de tri sort avec les filtres de recherche where et where_exp. J'en suis arrivé à la conclusion que ce n'était pas nécessaire, car les éléments étaient déjà classés par ordre alphabétique en fonction de leurs noms de fichier et j'ai donc supprimé les filtres.\nJ'utilise le format suivant : filename: \\\"comment-{@timestamp}\\\". Tout dépend donc de comment vous nommez vos fichiers de commentaires.\nAfficher les commentaires imbriqués\nVoici ce que je cherchais à accomplir… avant que le mal de tête ne commence\n😧 🔫\n\nDéclarer une boucle et, à chaque itération, créer un nouveau tableau nommé replies ne contenant que les réponses aux commentaires.\nÉvaluer la valeur de _parent pour ces réponses.\nSi _parent est égal à l’index de la boucle parente alors il doit être traité comme un commentaire \"enfant\".\nSinon, on passe à l’entrée suivante du tableau.\nEt ainsi de suite.\n\nJ'ai déterminé que la manière la plus simple d’assigner un identifiant unique à chaque commentaire parent était de le faire à l’aide d’une séquence.\nHeureusement Liquid nous permet de faire cela à l’aide de forloop.index.\n{% assign index = forloop.index %}\nEnsuite j'ai imbriqué une copie modifiée de la boucle parent précédente à l’intérieur d’elle-même --- pour faire fonction de boucle \"enfant\" ou replies.\n{% assign replies = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == include.index\" %}\n{% for reply in replies %}\n {% assign parent = reply._parent %}\n {% assign avatar = reply.avatar %}\n {% assign email = reply.email %}\n {% assign name = reply.name %}\n {% assign url = reply.url %}\n {% assign date = reply.date %}\n {% assign message = reply.message %}\n {% include comment.html parent=parent avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}\nMalheureusement le filtre where_exp s'est révélé problématique une fois de plus, obligeant Jekyll à générer l’erreur suivante :\nLiquid Exception: Liquid error (line 47): Nesting too deep in \/_layouts\/page.html.\nAprès avoir brièvement songé un moment au film Inception, j'ai appliqué un filtre inspect pour m'aider à m'en sortir avec la boucle replies. J'en ai conclu que la condition where_exp échouait4 parce que je tentais de comparer un entier avec une chaîne de caractères 😳.\nPour résoudre cela, j'ai placé une balise capture autour de la variable d’index pour la convertir en chaîne de caractères. Puis j'ai modifié la condition du filtre where_exp afin de comparer _parent avec cette nouvelle variable {{ i }} --- pour corriger le problème et me permettre de passer à la suite.\n{% capture i %}{{ include.index }}{% endcapture %}\n{% assign replies = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == i\" %}\n_includes\/page__comments.html\n<section class=\"page__reactions\">\n {% if site.repository and site.staticman.branch %}\n {% if site.data.comments[page.slug] %}\n <!-- Start static comments -->\n <div id=\"comments\" class=\"js-comments\">\n <h2 class=\"page__section-label\">\n {% if site.data.comments[page.slug].size > 1 %}\n {{ site.data.comments[page.slug] | size }}\n {% endif %}\n Comments\n <\/h2>\n {% assign comments = site.data.comments[page.slug] | sort | where_exp: 'comment', 'comment[1].replying_to == blank' %}\n {% for comment in comments %}\n {% assign index = forloop.index %}\n {% assign replying_to = comment[1].replying_to | to_integer %}\n {% assign avatar = comment[1].avatar %}\n {% assign email = comment[1].email %}\n {% assign name = comment[1].name %}\n {% assign url = comment[1].url %}\n {% assign date = comment[1].date %}\n {% assign message = comment[1].message %}\n {% include comment.html index=index replying_to=replying_to avatar=avatar email=email name=name url=url date=date message=message %}\n {% endfor %}\n <\/div>\n <!-- End static comments -->\n {% endif %}\n\n {% unless page.comments_locked == true %}\n <!-- Start new comment form -->\n <div id=\"respond\">\n <h2 class=\"page__section-label\">Leave a Comment <small><a rel=\"nofollow\" id=\"cancel-comment-reply-link\" href=\"{{ page.url | absolute_url }}#respond\" style=\"display:none;\">Cancel reply<\/a><\/small><\/h2>\n <form id=\"comment-form\" class=\"page__form js-form form\" method=\"post\" action=\"https:\/\/api.staticman.net\/v2\/entry\/{{ site.repository }}\/{{ site.staticman.branch }}\/comments\">\n <fieldset>\n <label for=\"comment-form-message\"><strong>Comment<\/strong> <small>(<a href=\"https:\/\/kramdown.gettalong.org\/quickref.html\">Markdown<\/a> is allowed)<\/small><\/label>\n <textarea type=\"text\" rows=\"6\" id=\"comment-form-message\" name=\"fields[message]\" required spellcheck=\"true\"><\/textarea>\n <\/fieldset>\n <fieldset>\n <label for=\"comment-form-name\"><strong>Name<\/strong><\/label>\n <input type=\"text\" id=\"comment-form-name\" name=\"fields[name]\" required spellcheck=\"false\">\n <\/fieldset>\n <fieldset>\n <label for=\"comment-form-email\"><strong>Email<\/strong> <small>(used for <a href=\"http:\/\/gravatar.com\">Gravatar<\/a> image and reply notifications)<\/small><\/label>\n <input type=\"email\" id=\"comment-form-email\" name=\"fields[email]\" required spellcheck=\"false\">\n <\/fieldset>\n <fieldset>\n <label for=\"comment-form-url\"><strong>Website<\/strong> <small>(optional)<\/small><\/label>\n <input type=\"url\" id=\"comment-form-url\" name=\"fields[url]\"\/>\n <\/fieldset>\n <fieldset class=\"hidden\" style=\"display: none;\">\n <input type=\"hidden\" name=\"options[origin]\" value=\"{{ page.url | absolute_url }}\">\n <input type=\"hidden\" name=\"options[parent]\" value=\"{{ page.url | absolute_url }}\">\n <input type=\"hidden\" id=\"comment-replying-to\" name=\"fields[replying_to]\" value=\"\">\n <input type=\"hidden\" id=\"comment-post-id\" name=\"options[slug]\" value=\"{{ page.slug }}\">\n <label for=\"comment-form-location\">Leave blank if you are a human<\/label>\n <input type=\"text\" id=\"comment-form-location\" name=\"fields[hidden]\" autocomplete=\"off\">\n <\/fieldset>\n <!-- Start comment form alert messaging -->\n <p class=\"hidden js-notice\">\n <span class=\"js-notice-text\"><\/span>\n <\/p>\n <!-- End comment form alert messaging -->\n <fieldset>\n <label for=\"comment-form-reply\">\n <input type=\"checkbox\" id=\"comment-form-reply\" name=\"options[subscribe]\" value=\"email\">\n Notify me of replies by email.\n <\/label>\n <button type=\"submit\" id=\"comment-form-submit\" class=\"btn btn--large\">Submit Comment<\/button>\n <\/fieldset>\n <\/form>\n <\/div>\n <!-- End new comment form -->\n {% else %}\n <p><em>Comments are closed. If you have a question concerning the content of this page, please feel free to <a href=\"\/contact\/\">contact me<\/a>.<\/em><\/p>\n {% endunless %}\n {% endif %}\n<\/section>\n_includes\/comment.html\n<article id=\"comment{% unless include.r %}{{ index | prepend: '-' }}{% else %}{{ include.index | prepend: '-' }}{% endunless %}\" class=\"js-comment comment {% if include.name == site.author.name %}admin{% endif %} {% unless include.replying_to == 0 %}child{% endunless %}\">\n <div class=\"comment__avatar\">\n {% if include.avatar %}\n <img src=\"{{ include.avatar }}\" alt=\"{{ include.name | escape }}\">\n {% elsif include.email %}\n <img src=\"https:\/\/www.gravatar.com\/avatar\/{{ include.email }}?d=mm&s=60\" srcset=\"https:\/\/www.gravatar.com\/avatar\/{{ include.email }}?d=mm&s=120 2x\" alt=\"{{ include.name | escape }}\">\n {% else %}\n <img src=\"\/assets\/images\/avatar-60.png\" srcset=\"\/assets\/images\/avatar-120.png 2x\" alt=\"{{ include.name | escape }}\">\n {% endif %}\n <\/div>\n <h3 class=\"comment__author-name\">\n {% unless include.url == blank %}\n <a rel=\"external nofollow\" href=\"{{ include.url }}\">\n {% if include.name == site.author.name %}<svg class=\"icon\" width=\"20px\" height=\"20px\"><use xlink:href=\"#icon-mistake\"><\/use><\/svg> {% endif %}{{ include.name }}\n <\/a>\n {% else %}\n {% if include.name == site.author.name %}<svg class=\"icon\" width=\"20px\" height=\"20px\"><use xlink:href=\"#icon-mistake\"><\/use><\/svg> {% endif %}{{ include.name }}\n {% endunless %}\n <\/h3>\n <div class=\"comment__timestamp\">\n {% if include.date %}\n {% if include.index %}<a href=\"#comment{% if r %}{{ index | prepend: '-' }}{% else %}{{ include.index | prepend: '-' }}{% endif %}\" title=\"path to this comment\">{% endif %}\n <time datetime=\"{{ include.date | date_to_xmlschema }}\">{{ include.date | date: '%B %d, %Y' }}<\/time>\n {% if include.index %}<\/a>{% endif %}\n {% endif %}\n <\/div>\n <div class=\"comment__content\">\n {{ include.message | markdownify }}\n <\/div>\n {% unless include.replying_to != 0 or page.comments_locked == true %}\n <div class=\"comment__reply\">\n <a rel=\"nofollow\" class=\"btn\" href=\"#comment-{{ include.index }}\" onclick=\"return addComment.moveForm('comment-{{ include.index }}', '{{ include.index }}', 'respond', '{{ page.slug }}')\">Reply to {{ include.name }}<\/a>\n <\/div>\n {% endunless %}\n<\/article>\n\n{% capture i %}{{ include.index }}{% endcapture %}\n{% assign replies = site.data.comments[page.slug] | sort | where_exp: 'comment', 'comment[1].replying_to == i' %}\n{% for reply in replies %}\n {% assign index = forloop.index | prepend: '-' | prepend: include.index %}\n {% assign replying_to = reply[1].replying_to | to_integer %}\n {% assign avatar = reply[1].avatar %}\n {% assign email = reply[1].email %}\n {% assign name = reply[1].name %}\n {% assign url = reply[1].url %}\n {% assign date = reply[1].date %}\n {% assign message = reply[1].message %}\n {% include comment.html index=index replying_to=replying_to avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}\nHTML et JavaScript pour la réponse à un commentaire\nL'étape suivante a consisté à ajouter quelques touches finales pour que le tout fonctionne.\nHabitué à la manière dont WordPress gère les formulaires de réponse, j'y ai pioché de l’inspiration. En mettant le nez dans le code JavaScript qui se trouve dans wp-includes\/js\/comment-reply.js j'ai trouvé tout ce dont j'avais besoin :\n\nune fonction respond pour déplacer le formulaire dans la vue,\nune fonction cancel pour supprimer un formulaire de réponse et le repositionner à son état d’origine,\npasser l’identifiant unique du parent à options[parent] lors de la soumission du formulaire.\n\nJ'ai commencé par utiliser une condition unless pour n'afficher que les liens \"répondre\" sur les commentaires parents. J'avais seulement envisagé un seul niveau de profondeur pour les réponses, donc cela m'a semblé être un bon moyen pour m'en tenir à ça.\n{% unless r %}\n <div class=\"comment__reply\">\n <a rel=\"nofollow\" class=\"btn\" href=\"#comment-{{ include.index }}\">\n Reply to {{ include.name }}\n <\/a>\n <\/div>\n{% endunless %}\n\n\n\n\n\n\nCommentaires imbriqués sur un seul niveau de profondeur.\n\nPour donner vie au lien répondre j'ai lui ai ajouté l’attribut onclick suivant et du JavaScript.\nonclick = \"return addComment.moveForm('comment-{{ include.index }}', '{{ include.index }}', 'respond’, '{{ page.slug }}')\";\nJ'ai juste eu à modifier quelques noms de variables dans le script comment-reply.js de WordPress pour que tout marche bien avec le balisage de mon formulaire.\nAjout du support des notifications par mail\nComparées aux réponses de commentaires imbriqués, les notifications par mail\nfurent très simples à mettre en place.\nMise à jour de la configuration staticman.yml\nPour s'assurer que les liens dans les mails de notifications sont sûrs et ne\nproviennent que de domaines de confiance, définissez allowedOrigins en\nfonction.\nExemple :\nallowedOrigins: [\"mademistakes.com\"]\nLe(s) domaine(s) autorisé()s doi(ven)t correspondre à ceux passés par le champ options.origin que nous allons ajouter à la prochaine étape. Seuls les domaines correspondants déclencheront les notifications à envoyer, faute de quoi l’opération échouera.\nProTip : Utilisez votre propre compte Mailgun\nL'instance publique de Static man utilise un compte Mailgun limité à 10 000 emails par mois. Je\nvous encourage à créer un compte et à ajouter votre propre API et domaine Mailgun dans le fichier staticman.yml. Assurez-vous de bien chiffrer les deux en utilisant le chemin suivant : https:\/\/api.staticman.net\/v2\/encrypt\/{TEXTE À CHIFFRER}.\nMise à jour du formulaire de commentaire\nPour terminer, ajoutons deux champs au formulaire de commentaire.\nChamp 1 : Un champ caché qui passe la valeur d’origin5 défini dans le fichier staticman.yml:\n<input type=\"hidden\" name=\"options[origin]\" value=\"{{ page.url | absolute_url }}\">\nChamp 2 : Un input de type case à cocher pour s'inscrire aux notifications par mail.\n<label for=\"comment-form-reply\">\n <input type=\"checkbox\" id=\"comment-form-reply\" name=\"options[subscribe]\" value=\"email\">\n Me prévenir par mail des nouveaux commentaires.\n<\/label>\nRien de bien surprenant ici, name=options[subscribe] and value=\"email\" sont ajoutés au champ pour associer les données d’abonnement avec l’adresse mail.\nSi tout est correctement configuré, l’utilisateur devrait recevoir un mail dès qu'un nouveau commentaire est posté sur le billet ou la page auxquels il s'est abonné.\n\n\n\n\n\n\nExemple d’un mail de notification « Nouvelle réponse » de Staticman.\n\nVoilà, vous avez mis en place un système de commentaires basé sur des fichiers statiques dans Jekyll et qui gère les commentaires imbriqués et les notifications de réponse. Maintenant j'aimerais gagner une minute de temps de génération pour pouvoir ajouter les nouveaux commentaires encore plus vite 😦.\n\n\n\n\nUn des avantages du nouveau fichier de configuration c'est qu'on peut utiliser Staticman avec d’autres générateurs de site statique. La v2 ne vous oblige plus à utiliser un fichier _config.yml spécifique à Jekyll. ↩\n\n\nLes propriétés de site sont optionnelles. Se reporter à la documentation de Staticman pour plus de détails sur comment connecter vos formulaires. ↩\n\n\nStaticman nomme ce champ _parent dans les entrées. ↩\n\n\n15 n'est pas la même chose que '15'. Ces guillemets simples font toute la différence… ↩\n\n\nCette URL sera ajoutée dans la notification par mail envoyée aux abonnés pour leur permettre d’ouvrir directement la page. ↩\n\n\n", "content_html": "\n

Depuis que j'ai quitté Disqus pour un système de commentaires statiques, Staticman a muri avec des ajouts de fonctionnalités comme les fils de commentaires et les notifications par mail.

\n

À l’aide des instructions fournies par Eduardo Bouças dans cette issue GitHub, je me suis lancé dans l’amélioration de l’expérience relative aux commentaires sur Made Mistakes. Voici comme j'ai procédé.

\n

Passer à la version 2 de Staticman

\n

Pour tirer parti de ces nouvelles fonctionnalités, il était nécessaire de migrer les paramètres de Staticman du fichier _config.yml de Jekyll vers un nouveau fichier staticman.yml1. Comme il n'y a eu aucun changement dans les paramètres, la transition vers la version 2 était grandement simplifiée.

\n
comments:\n  allowedFields     : ['name', 'email', 'url', 'message']\n  branch            : \"master\"\n  commitMessage     : \"Nouveau commentaire.\"\n  filename          : \"commentaire-{@timestamp}\"\n  format            : \"yaml\"\n  moderation        : true\n  path              : \"src/_data/comments/{options.slug}\"\n  requiredFields    : ['name', 'email', 'message']\n  transforms:\n    email           : md5\n  generatedFields:\n    date:\n      type          : \"date\"\n      options:\n        format      : \"iso8601\"
\n

Nouvelles options de configuration

\n

Assurez-vous de jeter un œil au modèle de fichier de configuration et à la liste complète des paramètres pour vous faire une idée des possibilités de configuration.

\n

Par exemple, vous pouvez configurer plusieurs propriétés (commentaires, avis et autres types de contenus générés par les utilisateurs), modifier le message de commit et le corps de texte de la pull request, activer les notifications par mail et bien plus à partir du fichier staticman.yml.

\n

Supprimer/Ajouter Staticman en tant que collaborateur

\n

Je ne suis pas vraiment certain que l’opération suivante soit nécessaire. Je me suis heurté à des erreurs lors de mes tests de commentaires et cela a eu l’air de régler le problème. Il est possible que je me sois trompé quelque part ailleurs dans la configuration et que l’origine du problème était ailleurs…

\n

Quoi qu’il en soit, vous pouvez toujours partager votre expérience de la mise à jour de la version 1 à la version 2 de Staticman dans les commentaires de ce billet.

\n
    \n
  1. Révoquez les droits de collaboration de Staticman v1 dans les paramètres de votre dépôt GitHub. \n\n\n\"Supprimer\n\n
    2. \n
  2. Ajoutez de nouveau Staticman en tant que collaborateur.
    3. \n
  3. Faites un appel sur ce endpoint de la version 2 de l’API https://api.staticman.net/v2/connect/{votre nom d’utilisateur GitHub}/{nom de votre dépôt} pour accepter l’invitation de collaboration.
    4. \n
\n

Mettre à jour l’appel POST du formulaire de commentaires

\n

Pour faire une requête POST correcte à Staticman, l’attribut action de mon formulaire de commentaire avait besoin d’une petite mise à jour. Remplacer v1 par v2 dans _includes/page__comments.html, puis suffixer avec /comments2 et le tour était joué pour moi.

\n
<form\n  id=\"comment-form\"\n  class=\"page__form js-form form\"\n  method=\"post\"\n  action=\"https://api.staticman.net/v2/entry/{{ site.repository }}/{{ site.staticman.branch }}/comments\"\n></form>
\n

Ajout du support des fils de commentaires

\n

Réussir à faire marcher les commentaires imbriqués s'est révélé assez pénible. Plusieurs erreurs Liquid, plusieurs tentatives avant d’arriver à faire marcher des boucles for à l’intérieur d’autres boucles for, des filtres de tableau qui pétaient des trucs et tout un tas de galères font que j'ai mis un moment avant de m'en sortir.

\n

Ajout d’un identifiant au parent

\n

Pour imbriquer correctement les réponses, j'avais besoin de pouvoir déterminer leur hiérarchie. La v2 de Staticman possède un nouveau champ nommé options[parent]3 qui peut être utilisé pour aider à établir cette relation. Avant d’aller plus loin, ajoutons déjà cet identifiant à mon formulaire dans un champ caché.

\n
<input type=\"hidden\" id=\"comment-parent\" name=\"options[parent]\" value=\"\" />
\n

Mise à jour des boucles Liquid

\n

Afin d’éviter d’afficher des doublons, j'avais besoin d’exclure les réponses et de ne montrer que les commentaires parents dans la boucle principale. C'était le moment idéal pour utiliser le filtre where_exp de Jekyll.

\n\n

Si le champ caché options[parent] que j'ai ajouté au formulaire fonctionne correctement, je devrais obtenir des fichiers de données de commentaires similaires à ceux-ci :

\n

Exemple de commentaire parent

\n
message: Ceci est le message du commentaire parent\nname: Prénom Nom\nemail: md5g1bb3r15h\ndate: 2016-11-30T22:03:15.286Z
\n

Exemple de commentaire enfant

\n
_parent: 7\nmessage: Ceci est un message de commentaire enfant\nname: Prénom Nom\nemail: md5g1bb3r15h\ndate: 2016-11-02T05:08:43.280Z
\n

Comme vous pouvez le voir ci-dessus, le commentaire \"enfant\" a une donnée _parent renseignée à partir du champ caché options[parent] du formulaire.
\nSachant cela, j'ai tenté d’utiliser where_exp:\"item\",\"item._parent == nil\" pour créer un tableau ne contenant que les commentaires \"parents\".

\n

Malheureusement, le code suivant n'a pas marché :

\n
{% assign comments = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == nil\" %}\n{% for comment in comments %}\n  {% assign avatar = comment[1].avatar %}\n  {% assign email = comment[1].email %}\n  {% assign name = comment[1].name %}\n  {% assign url = comment[1].url %}\n  {% assign date = comment[1].date %}\n  {% assign message = comment[1].message %}\n  {% include comment.html index=forloop.index avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}
\n

À la place, j'ai eu tout un tas de commentaires vides avec le balisage suivant :

\n
<article id=\"comment-1\" class=\"js-comment comment\">\n  <div class=\"comment__avatar\">\n    <img src=\"\" alt=\"\" />\n  </div>\n  <h3 class=\"comment__author-name\"></h3>\n  <div class=\"comment__timestamp\">\n    <a href=\"#comment-1\" title=\"Permalien vers ce commentaire\">\n      <time datetime=\"\"></time>\n    </a>\n  </div>\n  <div class=\"comment__content\"></div>\n</article>
\n

Hmm… j'imagine qu'il était temps d’ajouter des filtres inspect à mes tableaux pour voir ce qui se passait.

\n
{{ site.data.comments[page.slug] | inspect }}
\n

Exemple de tableau avant filtrage avec where_exp

\n
{\n  \"comment-1471818805944\" => {\n    \"message\" => \"Ceci est un message de commentaire parent.\",\n    \"name\"    => \"Prénom Nom\",\n    \"email\"   => \"md5g1bb3r15h\",\n    \"url\"     => \"\",\n    \"hidden\"  => \"\",\n    \"date\"    => \"2016-08-21T22:33:25.272Z\"\n  },\n  \"comment-1471904599908\" => {\n    \"message\" => \"Ceci est un autre message de commentaire parent.\",\n    \"name\"    => \"Prénom Nom\",\n    \"email\"   => \"md5g1bb3r15h\",\n    \"url\"     => \"\",\n    \"hidden\"  => \"\",\n    \"date\"    => \"2016-08-22T21:42:48.075Z\"\n  }\n}
\n

Exemple de tableau après filtrage avec where_exp

\n
[\n  {\n    \"message\" => \"Ceci est un message de commentaire parent.\",\n    \"name\"    => \"Prénom Nom\",\n    \"email\"   => \"md5g1bb3r15h\",\n    \"url\"     => \"\",\n    \"hidden\"  => \"\",\n    \"date\"    => \"2016-08-21T22:33:25.272Z\"\n  },\n  {\n    \"message\" => \"Ceci est un autre message de commentaire parent.\",\n    \"name\"    => \"Prénom Nom\",\n    \"email\"   => \"md5g1bb3r15h\",\n    \"url\"     => \"\",\n    \"hidden\"  => \"\",\n    \"date\"    => \"2016-08-22T21:42:48.075Z\"\n  }\n]
\n

Apparemment l’utilisation du filtre where_exp aplatit quelque peu les choses en supprimant les objets comment-xxxxxxxxxxxxx. Cela fait que mes tags assign retournent des valeurs nulles parce que comment[1] n'existe plus.

\n
{% assign avatar  = comment[1].avatar %}\n{% assign email   = comment[1].email %}\n{% assign name    = comment[1].name %}\n{% assign url     = comment[1].url %}\n{% assign date    = comment[1].date %}\n{% assign message = comment[1].message %}
\n

Une fois cela découvert, la solution était simple --- supprimer [1] pour chacun des noms des propriétés.

\n
{% assign avatar  = comment.avatar %}\n{% assign email   = comment.email %}\n{% assign name    = comment.name %}\n{% assign url     = comment.url %}\n{% assign date    = comment.date %}\n{% assign message = comment.message %}
\n
\n\n\n\n\"Seulement\n\n
Ça marche, nous avons des commentaires parents.
\n
\n\n

Afficher les commentaires imbriqués

\n

Voici ce que je cherchais à accomplir… avant que le mal de tête ne commence\n😧 🔫

\n\n

J'ai déterminé que la manière la plus simple d’assigner un identifiant unique à chaque commentaire parent était de le faire à l’aide d’une séquence.
\nHeureusement Liquid nous permet de faire cela à l’aide de forloop.index.

\n
{% assign index = forloop.index %}
\n

Ensuite j'ai imbriqué une copie modifiée de la boucle parent précédente à l’intérieur d’elle-même --- pour faire fonction de boucle \"enfant\" ou replies.

\n
{% assign replies = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == include.index\" %}\n{% for reply in replies %}\n  {% assign parent  = reply._parent %}\n  {% assign avatar  = reply.avatar %}\n  {% assign email   = reply.email %}\n  {% assign name    = reply.name %}\n  {% assign url     = reply.url %}\n  {% assign date    = reply.date %}\n  {% assign message = reply.message %}\n  {% include comment.html parent=parent avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}
\n

Malheureusement le filtre where_exp s'est révélé problématique une fois de plus, obligeant Jekyll à générer l’erreur suivante :
\nLiquid Exception: Liquid error (line 47): Nesting too deep in /_layouts/page.html.

\n

Après avoir brièvement songé un moment au film Inception, j'ai appliqué un filtre inspect pour m'aider à m'en sortir avec la boucle replies. J'en ai conclu que la condition where_exp échouait4 parce que je tentais de comparer un entier avec une chaîne de caractères 😳.

\n

Pour résoudre cela, j'ai placé une balise capture autour de la variable d’index pour la convertir en chaîne de caractères. Puis j'ai modifié la condition du filtre where_exp afin de comparer _parent avec cette nouvelle variable {{ i }} --- pour corriger le problème et me permettre de passer à la suite.

\n
{% capture i %}{{ include.index }}{% endcapture %}\n{% assign replies = site.data.comments[page.slug] | where_exp:\"item\",\"item._parent == i\" %}
\n

_includes/page__comments.html

\n
<section class=\"page__reactions\">\n  {% if site.repository and site.staticman.branch %}\n    {% if site.data.comments[page.slug] %}\n      <!-- Start static comments -->\n      <div id=\"comments\" class=\"js-comments\">\n        <h2 class=\"page__section-label\">\n          {% if site.data.comments[page.slug].size > 1 %}\n            {{ site.data.comments[page.slug] | size }}\n          {% endif %}\n          Comments\n        </h2>\n        {% assign comments = site.data.comments[page.slug] | sort | where_exp: 'comment', 'comment[1].replying_to == blank' %}\n        {% for comment in comments %}\n          {% assign index       = forloop.index %}\n          {% assign replying_to = comment[1].replying_to | to_integer %}\n          {% assign avatar      = comment[1].avatar %}\n          {% assign email       = comment[1].email %}\n          {% assign name        = comment[1].name %}\n          {% assign url         = comment[1].url %}\n          {% assign date        = comment[1].date %}\n          {% assign message     = comment[1].message %}\n          {% include comment.html index=index replying_to=replying_to avatar=avatar email=email name=name url=url date=date message=message %}\n        {% endfor %}\n      </div>\n      <!-- End static comments -->\n    {% endif %}\n\n    {% unless page.comments_locked == true %}\n      <!-- Start new comment form -->\n      <div id=\"respond\">\n        <h2 class=\"page__section-label\">Leave a Comment <small><a rel=\"nofollow\" id=\"cancel-comment-reply-link\" href=\"{{ page.url | absolute_url }}#respond\" style=\"display:none;\">Cancel reply</a></small></h2>\n        <form id=\"comment-form\" class=\"page__form js-form form\" method=\"post\" action=\"https://api.staticman.net/v2/entry/{{ site.repository }}/{{ site.staticman.branch }}/comments\">\n          <fieldset>\n            <label for=\"comment-form-message\"><strong>Comment</strong> <small>(<a href=\"https://kramdown.gettalong.org/quickref.html\">Markdown</a> is allowed)</small></label>\n            <textarea type=\"text\" rows=\"6\" id=\"comment-form-message\" name=\"fields[message]\" required spellcheck=\"true\"></textarea>\n          </fieldset>\n          <fieldset>\n            <label for=\"comment-form-name\"><strong>Name</strong></label>\n            <input type=\"text\" id=\"comment-form-name\" name=\"fields[name]\" required spellcheck=\"false\">\n          </fieldset>\n          <fieldset>\n            <label for=\"comment-form-email\"><strong>Email</strong> <small>(used for <a href=\"http://gravatar.com\">Gravatar</a> image and reply notifications)</small></label>\n            <input type=\"email\" id=\"comment-form-email\" name=\"fields[email]\" required spellcheck=\"false\">\n          </fieldset>\n          <fieldset>\n            <label for=\"comment-form-url\"><strong>Website</strong> <small>(optional)</small></label>\n            <input type=\"url\" id=\"comment-form-url\" name=\"fields[url]\"/>\n          </fieldset>\n          <fieldset class=\"hidden\" style=\"display: none;\">\n            <input type=\"hidden\" name=\"options[origin]\" value=\"{{ page.url | absolute_url }}\">\n            <input type=\"hidden\" name=\"options[parent]\" value=\"{{ page.url | absolute_url }}\">\n            <input type=\"hidden\" id=\"comment-replying-to\" name=\"fields[replying_to]\" value=\"\">\n            <input type=\"hidden\" id=\"comment-post-id\" name=\"options[slug]\" value=\"{{ page.slug }}\">\n            <label for=\"comment-form-location\">Leave blank if you are a human</label>\n            <input type=\"text\" id=\"comment-form-location\" name=\"fields[hidden]\" autocomplete=\"off\">\n          </fieldset>\n          <!-- Start comment form alert messaging -->\n          <p class=\"hidden js-notice\">\n            <span class=\"js-notice-text\"></span>\n          </p>\n          <!-- End comment form alert messaging -->\n          <fieldset>\n            <label for=\"comment-form-reply\">\n              <input type=\"checkbox\" id=\"comment-form-reply\" name=\"options[subscribe]\" value=\"email\">\n              Notify me of replies by email.\n            </label>\n            <button type=\"submit\" id=\"comment-form-submit\" class=\"btn btn--large\">Submit Comment</button>\n          </fieldset>\n        </form>\n      </div>\n      <!-- End new comment form -->\n    {% else %}\n      <p><em>Comments are closed. If you have a question concerning the content of this page, please feel free to <a href=\"/contact/\">contact me</a>.</em></p>\n    {% endunless %}\n  {% endif %}\n</section>
\n

_includes/comment.html

\n
<article id=\"comment{% unless include.r %}{{ index | prepend: '-' }}{% else %}{{ include.index | prepend: '-' }}{% endunless %}\" class=\"js-comment comment {% if include.name == site.author.name %}admin{% endif %} {% unless include.replying_to == 0 %}child{% endunless %}\">\n  <div class=\"comment__avatar\">\n    {% if include.avatar %}\n      <img src=\"{{ include.avatar }}\" alt=\"{{ include.name | escape }}\">\n    {% elsif include.email %}\n      <img src=\"https://www.gravatar.com/avatar/{{ include.email }}?d=mm&s=60\" srcset=\"https://www.gravatar.com/avatar/{{ include.email }}?d=mm&s=120 2x\" alt=\"{{ include.name | escape }}\">\n    {% else %}\n      <img src=\"/assets/images/avatar-60.png\" srcset=\"/assets/images/avatar-120.png 2x\" alt=\"{{ include.name | escape }}\">\n    {% endif %}\n  </div>\n  <h3 class=\"comment__author-name\">\n    {% unless include.url == blank %}\n      <a rel=\"external nofollow\" href=\"{{ include.url }}\">\n        {% if include.name == site.author.name %}<svg class=\"icon\" width=\"20px\" height=\"20px\"><use xlink:href=\"#icon-mistake\"></use></svg> {% endif %}{{ include.name }}\n      </a>\n    {% else %}\n      {% if include.name == site.author.name %}<svg class=\"icon\" width=\"20px\" height=\"20px\"><use xlink:href=\"#icon-mistake\"></use></svg> {% endif %}{{ include.name }}\n    {% endunless %}\n  </h3>\n  <div class=\"comment__timestamp\">\n    {% if include.date %}\n      {% if include.index %}<a href=\"#comment{% if r %}{{ index | prepend: '-' }}{% else %}{{ include.index | prepend: '-' }}{% endif %}\" title=\"path to this comment\">{% endif %}\n      <time datetime=\"{{ include.date | date_to_xmlschema }}\">{{ include.date | date: '%B %d, %Y' }}</time>\n      {% if include.index %}</a>{% endif %}\n    {% endif %}\n  </div>\n  <div class=\"comment__content\">\n    {{ include.message | markdownify }}\n  </div>\n  {% unless include.replying_to != 0 or page.comments_locked == true %}\n    <div class=\"comment__reply\">\n      <a rel=\"nofollow\" class=\"btn\" href=\"#comment-{{ include.index }}\" onclick=\"return addComment.moveForm('comment-{{ include.index }}', '{{ include.index }}', 'respond', '{{ page.slug }}')\">Reply to {{ include.name }}</a>\n    </div>\n  {% endunless %}\n</article>\n\n{% capture i %}{{ include.index }}{% endcapture %}\n{% assign replies = site.data.comments[page.slug] | sort | where_exp: 'comment', 'comment[1].replying_to == i' %}\n{% for reply in replies %}\n  {% assign index       = forloop.index | prepend: '-' | prepend: include.index %}\n  {% assign replying_to = reply[1].replying_to | to_integer %}\n  {% assign avatar      = reply[1].avatar %}\n  {% assign email       = reply[1].email %}\n  {% assign name        = reply[1].name %}\n  {% assign url         = reply[1].url %}\n  {% assign date        = reply[1].date %}\n  {% assign message     = reply[1].message %}\n  {% include comment.html index=index replying_to=replying_to avatar=avatar email=email name=name url=url date=date message=message %}\n{% endfor %}
\n

HTML et JavaScript pour la réponse à un commentaire

\n

L'étape suivante a consisté à ajouter quelques touches finales pour que le tout fonctionne.

\n

Habitué à la manière dont WordPress gère les formulaires de réponse, j'y ai pioché de l’inspiration. En mettant le nez dans le code JavaScript qui se trouve dans wp-includes/js/comment-reply.js j'ai trouvé tout ce dont j'avais besoin :

\n\n

J'ai commencé par utiliser une condition unless pour n'afficher que les liens \"répondre\" sur les commentaires parents. J'avais seulement envisagé un seul niveau de profondeur pour les réponses, donc cela m'a semblé être un bon moyen pour m'en tenir à ça.

\n
{% unless r %}\n  <div class=\"comment__reply\">\n    <a rel=\"nofollow\" class=\"btn\" href=\"#comment-{{ include.index }}\">\n      Reply to {{ include.name }}\n    </a>\n  </div>\n{% endunless %}
\n
\n\n\n\n\"Commentaires\n\n
Commentaires imbriqués sur un seul niveau de profondeur.
\n
\n

Pour donner vie au lien répondre j'ai lui ai ajouté l’attribut onclick suivant et du JavaScript.

\n
onclick = \"return addComment.moveForm('comment-{{ include.index }}', '{{ include.index }}', 'respond’, '{{ page.slug }}')\";
\n

J'ai juste eu à modifier quelques noms de variables dans le script comment-reply.js de WordPress pour que tout marche bien avec le balisage de mon formulaire.

\n

Ajout du support des notifications par mail

\n

Comparées aux réponses de commentaires imbriqués, les notifications par mail\nfurent très simples à mettre en place.

\n

Mise à jour de la configuration staticman.yml

\n

Pour s'assurer que les liens dans les mails de notifications sont sûrs et ne\nproviennent que de domaines de confiance, définissez allowedOrigins en\nfonction.

\n

Exemple :

\n
allowedOrigins: [\"mademistakes.com\"]
\n

Le(s) domaine(s) autorisé()s doi(ven)t correspondre à ceux passés par le champ options.origin que nous allons ajouter à la prochaine étape. Seuls les domaines correspondants déclencheront les notifications à envoyer, faute de quoi l’opération échouera.

\n\n

Mise à jour du formulaire de commentaire

\n

Pour terminer, ajoutons deux champs au formulaire de commentaire.

\n

Champ 1 : Un champ caché qui passe la valeur d’origin5 défini dans le fichier staticman.yml:

\n
<input type=\"hidden\" name=\"options[origin]\" value=\"{{ page.url | absolute_url }}\">
\n

Champ 2 : Un input de type case à cocher pour s'inscrire aux notifications par mail.

\n
<label for=\"comment-form-reply\">\n  <input type=\"checkbox\" id=\"comment-form-reply\" name=\"options[subscribe]\" value=\"email\">\n  Me prévenir par mail des nouveaux commentaires.\n</label>
\n

Rien de bien surprenant ici, name=options[subscribe] and value=\"email\" sont ajoutés au champ pour associer les données d’abonnement avec l’adresse mail.

\n

Si tout est correctement configuré, l’utilisateur devrait recevoir un mail dès qu'un nouveau commentaire est posté sur le billet ou la page auxquels il s'est abonné.

\n
\n\n\n\n\"Staticman\n\n
Exemple d’un mail de notification « Nouvelle réponse » de Staticman.
\n
\n

Voilà, vous avez mis en place un système de commentaires basé sur des fichiers statiques dans Jekyll et qui gère les commentaires imbriqués et les notifications de réponse. Maintenant j'aimerais gagner une minute de temps de génération pour pouvoir ajouter les nouveaux commentaires encore plus vite 😦.

\n
\n
\n
    \n
  1. \n

    Un des avantages du nouveau fichier de configuration c'est qu'on peut utiliser Staticman avec d’autres générateurs de site statique. La v2 ne vous oblige plus à utiliser un fichier _config.yml spécifique à Jekyll. ↩

    \n
    2. \n
  2. \n

    Les propriétés de site sont optionnelles. Se reporter à la documentation de Staticman pour plus de détails sur comment connecter vos formulaires. ↩

    \n
    3. \n
  3. \n

    Staticman nomme ce champ _parent dans les entrées. ↩

    \n
    4. \n
  4. \n

    15 n'est pas la même chose que '15'. Ces guillemets simples font toute la différence… ↩

    \n
    5. \n
  5. \n

    Cette URL sera ajoutée dans la notification par mail envoyée aux abonnés pour leur permettre d’ouvrir directement la page. ↩

    \n
    6. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2016/11/10/designer-un-portfolio-avec-jekyll/", "url": "https://jamstatic.fr/2016/11/10/designer-un-portfolio-avec-jekyll/", "title": "Process de design d’un portfolio", "summary": "Les différentes étapes pour concevoir son portfolio avec Jekyll et GitHub Pages par Kat Fukui, webdesigner chez Github.", "date_published": "2016-11-10T00:00:00+00:00","content_text": "The Design Portfolio Workflow de @katmeister, s'adresse aux webdesigners curieux de se frotter un peu à la ligne de commande et à Jekyll. Nous espérons qu'il vous permettra de faire vos premiers pas avec Jekyll, d’apprécier la liberté et la souplesse qu'il procure et qui sait de pouvoir ensuite développer des thèmes pour Jekyll 😊\nUn guide complet pour coder et déployer un site, tout en ligne de commande\nDonc j'étais en train de mettre à jour mon portfolio, j'éditais quelques liens dans le pied de page sur toutes les pages et j'ai pensé… putain mais que suis-je en train de faire de ma vie ? N'y aurait-il pas un moyen plus intelligent de faire ? J'étais dans l’expectative quand James m'a suggéré de tester Jekyll. Mon épopée commence donc ici.\nJe partage ce guide pas-à-pas, car je pense que ce workflow pour un portfolio peut avoir de la valeur aux yeux de ceux qui souhaitent bénéficier de méthodes d’ingénierie robustes et éprouvées sans renoncer à leur amour du détail dans le design. Les designers aiment les systèmes clairs et les choses propres, donc pourquoi ne pas appliquer aussi cela à notre code ?\nJ'espère aussi que cet article montre aux designers curieux du code que ce n'est pas la peine d’avoir peur des outils modernes de développement web. Ça vous branche ? Allez, c'est parti !\n\n\n\n\n\n\nCe type, OK ?\n\nC’est quoi Jekyll ?\nJekyll est un \"générateur de site, simple et paré pour le blog\", ce qui signifie que vous créez des contenus dynamiques et des modèles sur votre ordinateur en local, puis Jekyll recrache le tout en fichiers statiques HTML et CSS que vous pouvez déposer sur votre site hébergé. Chaque entrée de portfolio est traitée comme un article de blog et est extrêmement simple à créer et à éditer. Jekyll inclus également un serveur web de test et supporte Sass.\n\n\nLiz, j'ai été là-bas et c'est incroyable.\n\nRapide ✔ Propre ✔ Simple ✔ Complet ✔\nOK, tu m’intéresses.\nDéveloppons un portfolio !\nC’est assez fascinant pour vous ? Développons et déployons un site ensemble pour faire une démonstration du processus de travail. Premièrement, nous allons lancer le terminal et travailler avec la ligne de commande.\n\n\n\n\n\n\nLe terminal\n\nMême si vous n'avez pas beaucoup l’habitude de taper des commandes, vous vous en sortirez en connaissant les bases, comme se déplacer dans les dossiers de votre répertoire de travail. Vous pouvez apprendre les bases ici ou ici. Sinon, le copier-coller n'est pas une si mauvaise chose pour commencer à apprendre.\nInstallons Jekyll1 ! Dans le terminal, j'ai tapé :\ngem install jekyll bundler\nPar défaut, le terminal s'ouvre dans votre dossier utilisateur. Vous pouvez voir les fichiers et les dossiers du répertoire courant en entrant ls. Ça me va très bien de créer mon nouveau portfolio à cet endroit, donc je vais taper :\njekyll new mon-site\ncd mon-site\njekyll serve\nExcellent ! J'ai donc maintenant un dossier sur mon ordinateur nommé mon-site.\nLa commande jekyll serve lance un serveur web local pour prévisualiser votre site à l’adresse http:\/\/localhost:4000. Je vais garder cet onglet ouvert dans mon navigateur.\n\n\n\n\n\n\nLe thème par défaut de Jekyll.\n\nPlongeons dans les fichiers\nRegardons à quoi ressemble l’arborescence de notre site Jekyll en ouvrant le dossier mon-site dans notre éditeur de texte préféré. J'ai utilisé Sublime Text pendant des années mais récemment je suis passé à Atom.\nC’est bien documenté et les paquets de la communauté sont assez mortels - pigments, Emmet et bezier-curve-editor pour n'en citer que quelques-uns.\n\n\n\n\n\n\nLe dossier mon-site ouvert dans Atom.\n\nPour ce guide, je vais utiliser Atom. Vous remarquerez le panneau avec l’arborescence de fichier sur la gauche. Laissez-moi vous la détailler :\nmon-site\/\n|\n|-- _config.yml # Configuration de votre site\n|-- _drafts\/ # Articles non publiés\n|-- _includes\/ # Composants HTML réutilisables\n|-- _layouts\/ # Modèles\n|-- _posts\/ # Articles (ou entrées de portfolio !)\n|-- _sass\/ # Fichiers Sass\n|-- _site\/ # Votre site généré\n|-- css\/ # fichier CSS principal\n|-- about.md # Page à propos\n|-- index.html # index du site\nC’est l’arborescence par défaut. Tout dossier dont le nom commence par un tiret bas _ ne sera pas généré tel quel. Par exemple quand Jekyll va générer votre site, il ne va pas créer un dossier layouts, par contre il générera le fichier index.html puisqu'il n'y a pas de tiret bas devant.\nVous pouvez ajouter autant de dossiers que vous voulez pour organiser vos icônes, vos vignettes, vos fichiers JavaScript, etc. Ils seront copiés dans le site généré tels quels. Organisez-vous comme bon vous semble, voici quelques exemples de dossiers :\nassets\/ # images du projet\nimages\/ # fichiers SVG, images diverses\njs\/ # fichiers Javascript, les vôtres et ceux des différentes bibliothèques utilisées.\nModifier les paramètres de votre site\nJekyll inclus ce super fichier nommé _config.yml dans le répertoire racine. Vous pouvez définir n'importe quel paramètre global de votre portfolio dedans. Ouvrons-le et personnalisons tout ça !\n\n\n\n\n\n\nRemplissez vos infos !\n\nJ'ai ajouté un paramètre permalink pour définir comment je voulais construire les URLs du site (sinon par défaut la date de l’article est présente). J'ai aussi ajouté une variable dribbble_username.\nÀ chaque fois que nous allons modifier _config.yml, il nous faudra relancer le serveur de Jekyll. Donc une fois les changements effectués, arrêtez le serveur en ligne de commande avec le raccourci ctrl-c. Entez à nouveau jekyll serve et jetez un coup d’œil à localhost !\n\n\n\n\n\n\nLes variables globales sont appliquées !\n\nCette flexibilité c'est ce qui rend Jekyll si fun et simple à mettre en œuvre.\nVoyons comment ce concept est aussi valable pour nos articles.\nAjoutons notre premier article !\nÀ quoi sert un portfolio sans démonstration de notre travail ? Écrivons un article à propos de mon side-projet d’application de livraison de nourriture pour chat, Food Right Meow. Dans le dossier _posts, je vais créer un nouveau fichier Markdown en utilisant la convention ANNEE-MOIS-JOUR-titre2. Le fichier de mon article est donc nommé 2016-11-10-livraison-nourriture-chats.markdown.\n\n\n\n\n\n\nYAML front matter.\n\nVous remarquerez une portion de contenu en haut de l’introduction de l’article sur Jekyll. Copions-la dans notre nouvel article et voyons ensemble ses pouvoirs extraordinaires.\nYAML front matter\nFront matter est un puissant outil qui permet de définir des variables spécifiques à une page. Ces variables sont accessibles de partout grâce aux balises Liquid, que nous allons voir très bientôt\nÉditons notre front matter en haut de l’article entre les triples tirets :\n\n\n\n\n\n\nC’est ici que nous définissons le titre, la date et la catégorie.\n\nJekyll possède quelques variables front matter prédéfinies, mais c'est en créant vos propres variables dans vos modèles que vous en tirerez le plus parti ! Regardons comment notre premier article utilise les variables front matter :\n\n\n\n\n\n\nÇa marche !\n\nLiquid\nAlors comment ça marche tout ça ? Ces variables front matter sont référencées dans le HTML et le Markdown grâce à Liquid, un langage de modélisation très facile à prendre en main. Liquid vous permet d’ajouter de la logique, comme des conditions if\/else et des boucles for, d’assigner des chaines de caractères à des variables. Les trucs entre {{ }} ou {% %} c'est pour faire bosser Liquid !\nSi vous ouvrez le fichier post.html dans le dossier _layouts, nous pouvons le voir en action.\n\n\n\n\n\nEn préfixant nos variables avec page, Liquid va rechercher dans votre page les entrées front matter correspondantes entre les triples tirets. Si elles existent, nous pouvons écrire le texte stocké dans ces variables dans notre HTML. Cool, non ?\nPlus de détails sur les variables par ici.\nEt si nous ajoutons encore quelques variables à nous dans le front matter pour épicer un peu nos articles :\n\n\n\n\n\nMaintenant que nous disposons de toutes ces super variables, comment pouvons-nous les utiliser ? Modifions notre modèle de mise en page post.html en utilisant les variables page.type et page.intro :\n\n\n\n\n\n\nRegardez ce qui est en violet.\n\nCool ! Vous pouvez bien entendu utiliser CSS comme à votre habitude pour mettre en forme tous les rendus de vos chouettes balises. Essayons d’autres trucs. Et si nous ajoutions des vignettes pour chaque article sur la page index.html ?\nEt leur légende aussi peut-être.\n\n\n\n\n\n\nFront matter c'est de la bombe !\n\nHé, c'est pas trop mal. Je suis sûr que vous pouvez déjà voir comment Jekyll va automatiser votre site en utilisant Liquid et YAML.\nÉcrire un article pour de vrai\nVous aurez noté l’extension .md ou .markdown pour vos articles. C’est l’abréviation pour Markdown, un langage léger qui convertit sans heurt du texte brut en HTML. Je me suis rendu-compte qu'écrire à l’aide de la syntaxe Markdown me permet de mieux me concentrer sur mon contenu, plutôt que de penser quelles balises fermer.\n\n\n\n\n\nLa beauté de Markdown c'est que vous pouvez toujours utiliser HTML si vous en avez besoin. Pour forcer le rendu de Markdown à l’intérieur de balises HTML, ajoutez markdown=1 et le tour est joué ! Le meilleur des deux mondes. Voici un extrait de l’article une fois généré :\n\n\n\n\n\n\nNe voudrions-nous pas vivre de Purring Cat ?\n\nUn autre exemple d’article en .md\nLorsque j'ai migré les vieux projets de mon portfolio dans Jekyll, j'ai trouvé que mélanger le HTML et Markdown c'était trop bizarre et que ça allait à l’encontre de l’objectif de clarté de Markdown. j’ai créé une démo qui montre ce que j'ai fait pour parvenir à des articles plus propres tout en gardant les styles désirés !\nCe n'est en aucun cas une obligation ou la bonne manière de faire — juste une technique pour satisfaire mon côté hyper-maniaque. 😊 Vous êtes libres de télécharger et de vous amuser avec les fichiers sur Github.\nAjoutons un peu de CSS à tout ça\nMaintenant que nous nous sommes familiarisés avec les possibilités de Jekyll et que nous avons un peu de contenu avec lequel travailler, ajoutons un peu de style ! Vous pouvez recopier le CSS ou le Sass de votre portfolio existant ou repartir de zéro.\n\n\n\n\n\nSass\nVous avez probablement remarqué que les projets Jekyll sont livrés avec des fichiers Sass (avec une extension .scss). Bien que vous n'ayez pas besoin de connaître Sass pour pouvoir utiliser Jekyll, c'est un outil apprécié et recommandé dans le processus de développement CSS. Sérieusement, votre CSS sera bien mieux organisé et cohérent une fois que vous l’aurez adopté.\nCes guides pour débutant m'ont beaucoup aidé quand j'ai commencé. Jekyll intègre par défaut le support de Sass, vous n'avez donc pas d’excuse pour l’adopter. 😉\nVersionnement avec Git\nMaintenant que vous vous êtes accommodés du terminal, je vous recommande vivement d’utiliser Git pour versionner votre portfolio. Git prend des \"clichés\" de votre dépôt — le répertoire du projet — à chaque fois que vous faites un commit, de façon à ce que vous puissiez revenir à des versions antérieures de votre travail quand c'est nécessaire. Si vous travaillez avec une autre personne, vous pouvez travailler chacun sur votre propre branche du projet et fusionner ensuite tout ça dans la branche master, visible de tous les intervenants du projet.\nConfigurer Git\nTéléchargez et installez Git. De retour dans votre terminal, entrez ces commandes (et ajoutez vos propres infos entre les guillemets) :\ngit config --global user.name “Votre Nom”\ngit config --global user.email \"[adresse mail]\"\nSuper, nous sommes parés pour Git ! Mais notre projet ne pourra pas utiliser Git tant que nous ne l’aurons pas initialisé. Dans le répertoire mon-site, je vais donc taper :\ngit init\nFacile ! Notre nouveau dépôt Git est vide, ajoutons-y donc nos fichiers.\ngit add .\nSuper, notre projet est ajouté au dépôt local et est prêt à être enregistré dans un commit. Prenons une photo de notre dépôt en faisant notre premier commit !\nUtilisez l’option -m suivi d’un message significatif entre guillemets.\ngit commit -m \"Première entrée du portfolio\"\nNotre projet possède officiellement un historique ! Git fonctionne en local, mais GitHub est un service de stockage distant pour pousser nos dépôts sur le web et les partager avec le reste du monde. Connectons notre dépôt local à un dépôt distant sur GitHub et poussons notre premier commit.\nCréer un dépôt sur GitHub\nMaintenant que nous avons initialisé Git pour notre portfolio, configurons un dépôt distant sur GitHub.\n\nCréez-vous un compte, si vous n'en possédez pas encore.\nCréez un nouveau dépôt. \n\n\n\n\n\nDans le coin en haut à droite.\n\n\nDonnez un nom et ajoutez une description à votre dépôt. Créez le dépôt ! \n\n\n\n\n\nMaintenant que vous avez créé le dépôt, vous allez voir cette page s'afficher sur GitHub : \n\n\n\n\nC’est la partie \"publier un dépôt existant en ligne de commande\" qui nous intéresse. Je vais copier-coller ces commandes dans le terminal.\ngit remote add origin connecte les deux dépôts pour permettre le déploiement.\ngit push pousse les commits locaux dans votre dépôt distant !\n\nActualisez la page de votre dépôt distant et félicitez-vous ! ON A RÉUSSI.\nMaintenant le monde entier peut admirer notre super portfolio !\n\n\n\n\n\n\nVoici un guide pour débutant très sympa pour des explications plus détaillées.\nGitHub Pages\nÀ partir de là, nous pouvons aller encore plus loin et configurer notre dépôt pour GitHub Pages — un hébergement gratuit sans FTP. Yep, ça veut dire que vous pouvez enregistrer et publier vos changements et voir immédiatement ces modifications en ligne !\nC’est un écosystème complet, accessible depuis votre terminal de confiance.\nMes conseils supplémentaires\nParce que ce guide n'est pas déjà assez long.\nTester sur mobile\nLe test sur mobile est inclus ! Autorisons Jekyll à accéder à notre mobile en lançant le serveur de cette manière dans le terminal :\njekyll serve --host 0.0.0.0\nEnsuite, récupérez votre adresse IP sur le réseau Wi-Fi local et faites là pointer vers le port 4000. En gros, vous allez taper un truc comme 192.168.x.x:4000 dans votre navigateur mobile. Si vous voulez savoir comment ça marche, lisez cet article.\nSystème de grille\n\n\n\n\n\nPour un portfolio, un système de grille léger est facile à implémenter et il ne se met pas en travers de votre CSS. J'utilise Jeet parce que j'aime sa syntaxe et sa souplesse. Ceci dit, il y en a des tonnes de super chouettes, comme Neat ou Toast.\nRythme vertical\n\n\n\n\n\n\nFrom Typecast.\n\nLe rythme vertical c'est l’espacement constant et la mise à l’échelle des paragraphes, des marges externes et internes, des tailles de police et des hauteurs de ligne. Trouver le bon rythme améliore la lisibilité et l’harmonie d’un site. J'utilise modular-scale sur mon propre portfolio. Apprenez en davantage sur le rythme vertical\nici ou là.\nFin\nEt voilà comment on crée et on déploie un joli modèle de portfolio, entièrement à partir du terminal. Vous n'avez plus qu'à créer un simple article au format texte pour les nouveaux projets et à taper quelques commandes pour le publier sur GitHub Pages.\nJ'espère que vous avez aimé construire un portfolio pour Food Right Meow avec moi. Créer et redesigner votre portfolio devrait être fun et enrichissant, alors à vos claviers et à vos lignes de commande !\nTéléchargez ou forkez le dépôt de démo\nVoir la démo en action\n\n\n\n\n\n\n\n\n\nInstallez Ruby et Jekyll à l’aide d’Homebrew sous Mac. ↩\n\n\nLe plugin jekyll-atom facilite la création de posts en respectant cette convention. ↩\n\n\n", "content_html": "\n

Un guide complet pour coder et déployer un site, tout en ligne de commande

\n

Donc j'étais en train de mettre à jour mon portfolio, j'éditais quelques liens dans le pied de page sur toutes les pages et j'ai pensé… putain mais que suis-je en train de faire de ma vie ? N'y aurait-il pas un moyen plus intelligent de faire ? J'étais dans l’expectative quand James m'a suggéré de tester Jekyll. Mon épopée commence donc ici.

\n

Je partage ce guide pas-à-pas, car je pense que ce workflow pour un portfolio peut avoir de la valeur aux yeux de ceux qui souhaitent bénéficier de méthodes d’ingénierie robustes et éprouvées sans renoncer à leur amour du détail dans le design. Les designers aiment les systèmes clairs et les choses propres, donc pourquoi ne pas appliquer aussi cela à notre code ?

\n

J'espère aussi que cet article montre aux designers curieux du code que ce n'est pas la peine d’avoir peur des outils modernes de développement web. Ça vous branche ? Allez, c'est parti !

\n
\n\n\n\n\"Ce\n\n
Ce type, OK ?
\n
\n

C’est quoi Jekyll ?

\n

Jekyll est un \"générateur de site, simple et paré pour le blog\", ce qui signifie que vous créez des contenus dynamiques et des modèles sur votre ordinateur en local, puis Jekyll recrache le tout en fichiers statiques HTML et CSS que vous pouvez déposer sur votre site hébergé. Chaque entrée de portfolio est traitée comme un article de blog et est extrêmement simple à créer et à éditer. Jekyll inclus également un serveur web de test et supporte Sass.

\n
\n\"Liz,\n
Liz, j'ai été là-bas et c'est incroyable.
\n
\n

Rapide ✔ Propre ✔ Simple ✔ Complet ✔

\n

OK, tu m’intéresses.

\n

Développons un portfolio !

\n

C’est assez fascinant pour vous ? Développons et déployons un site ensemble pour faire une démonstration du processus de travail. Premièrement, nous allons lancer le terminal et travailler avec la ligne de commande.

\n
\n\n\n\n\"Le\n\n
Le terminal
\n
\n

Même si vous n'avez pas beaucoup l’habitude de taper des commandes, vous vous en sortirez en connaissant les bases, comme se déplacer dans les dossiers de votre répertoire de travail. Vous pouvez apprendre les bases ici ou ici. Sinon, le copier-coller n'est pas une si mauvaise chose pour commencer à apprendre.

\n

Installons Jekyll1 ! Dans le terminal, j'ai tapé :

\n
gem install jekyll bundler
\n

Par défaut, le terminal s'ouvre dans votre dossier utilisateur. Vous pouvez voir les fichiers et les dossiers du répertoire courant en entrant ls. Ça me va très bien de créer mon nouveau portfolio à cet endroit, donc je vais taper :

\n
jekyll new mon-site\ncd mon-site\njekyll serve
\n

Excellent ! J'ai donc maintenant un dossier sur mon ordinateur nommé mon-site.
\nLa commande jekyll serve lance un serveur web local pour prévisualiser votre site à l’adresse http://localhost:4000. Je vais garder cet onglet ouvert dans mon navigateur.

\n
\n\n\n\n\"Le\n\n
Le thème par défaut de Jekyll.
\n
\n

Plongeons dans les fichiers

\n

Regardons à quoi ressemble l’arborescence de notre site Jekyll en ouvrant le dossier mon-site dans notre éditeur de texte préféré. J'ai utilisé Sublime Text pendant des années mais récemment je suis passé à Atom.
\nC’est bien documenté et les paquets de la communauté sont assez mortels - pigments, Emmet et bezier-curve-editor pour n'en citer que quelques-uns.

\n
\n\n\n\n\"Le\n\n
Le dossier mon-site ouvert dans Atom.
\n
\n

Pour ce guide, je vais utiliser Atom. Vous remarquerez le panneau avec l’arborescence de fichier sur la gauche. Laissez-moi vous la détailler :

\n
mon-site/\n|\n|-- _config.yml    # Configuration de votre site\n|-- _drafts/       # Articles non publiés\n|-- _includes/     # Composants HTML réutilisables\n|-- _layouts/      # Modèles\n|-- _posts/        # Articles (ou entrées de portfolio !)\n|-- _sass/         # Fichiers Sass\n|-- _site/         # Votre site généré\n|-- css/           # fichier CSS principal\n|-- about.md       # Page à propos\n|-- index.html     # index du site
\n

C’est l’arborescence par défaut. Tout dossier dont le nom commence par un tiret bas _ ne sera pas généré tel quel. Par exemple quand Jekyll va générer votre site, il ne va pas créer un dossier layouts, par contre il générera le fichier index.html puisqu'il n'y a pas de tiret bas devant.

\n

Vous pouvez ajouter autant de dossiers que vous voulez pour organiser vos icônes, vos vignettes, vos fichiers JavaScript, etc. Ils seront copiés dans le site généré tels quels. Organisez-vous comme bon vous semble, voici quelques exemples de dossiers :

\n
assets/        # images du projet\nimages/        # fichiers SVG, images diverses\njs/            # fichiers Javascript, les vôtres et ceux des différentes bibliothèques utilisées.
\n

Modifier les paramètres de votre site

\n

Jekyll inclus ce super fichier nommé _config.yml dans le répertoire racine. Vous pouvez définir n'importe quel paramètre global de votre portfolio dedans. Ouvrons-le et personnalisons tout ça !

\n
\n\n\n\n\"Remplissez\n\n
Remplissez vos infos !
\n
\n

J'ai ajouté un paramètre permalink pour définir comment je voulais construire les URLs du site (sinon par défaut la date de l’article est présente). J'ai aussi ajouté une variable dribbble_username.

\n

À chaque fois que nous allons modifier _config.yml, il nous faudra relancer le serveur de Jekyll. Donc une fois les changements effectués, arrêtez le serveur en ligne de commande avec le raccourci ctrl-c. Entez à nouveau jekyll serve et jetez un coup d’œil à localhost !

\n
\n\n\n\n\"Les\n\n
Les variables globales sont appliquées !
\n
\n

Cette flexibilité c'est ce qui rend Jekyll si fun et simple à mettre en œuvre.
\nVoyons comment ce concept est aussi valable pour nos articles.

\n

Ajoutons notre premier article !

\n

À quoi sert un portfolio sans démonstration de notre travail ? Écrivons un article à propos de mon side-projet d’application de livraison de nourriture pour chat, Food Right Meow. Dans le dossier _posts, je vais créer un nouveau fichier Markdown en utilisant la convention ANNEE-MOIS-JOUR-titre2. Le fichier de mon article est donc nommé 2016-11-10-livraison-nourriture-chats.markdown.

\n
\n\n\n\n\"YAML\n\n
YAML front matter.
\n
\n

Vous remarquerez une portion de contenu en haut de l’introduction de l’article sur Jekyll. Copions-la dans notre nouvel article et voyons ensemble ses pouvoirs extraordinaires.

\n

YAML front matter

\n

Front matter est un puissant outil qui permet de définir des variables spécifiques à une page. Ces variables sont accessibles de partout grâce aux balises Liquid, que nous allons voir très bientôt

\n

Éditons notre front matter en haut de l’article entre les triples tirets :

\n
\n\n\n\n\"C’est\n\n
C’est ici que nous définissons le titre, la date et la catégorie.
\n
\n

Jekyll possède quelques variables front matter prédéfinies, mais c'est en créant vos propres variables dans vos modèles que vous en tirerez le plus parti ! Regardons comment notre premier article utilise les variables front matter :

\n
\n\n\n\n\"Ça\n\n
Ça marche !
\n
\n

Liquid

\n

Alors comment ça marche tout ça ? Ces variables front matter sont référencées dans le HTML et le Markdown grâce à Liquid, un langage de modélisation très facile à prendre en main. Liquid vous permet d’ajouter de la logique, comme des conditions if/else et des boucles for, d’assigner des chaines de caractères à des variables. Les trucs entre {{ }} ou {% %} c'est pour faire bosser Liquid !

\n

Si vous ouvrez le fichier post.html dans le dossier _layouts, nous pouvons le voir en action.

\n\n\n\n\"\"\n\n

En préfixant nos variables avec page, Liquid va rechercher dans votre page les entrées front matter correspondantes entre les triples tirets. Si elles existent, nous pouvons écrire le texte stocké dans ces variables dans notre HTML. Cool, non ?
\nPlus de détails sur les variables par ici.

\n

Et si nous ajoutons encore quelques variables à nous dans le front matter pour épicer un peu nos articles :

\n\n\n\n\"img\"\n\n

Maintenant que nous disposons de toutes ces super variables, comment pouvons-nous les utiliser ? Modifions notre modèle de mise en page post.html en utilisant les variables page.type et page.intro :

\n
\n\n\n\n\"Regardez\n\n
Regardez ce qui est en violet.
\n
\n

Cool ! Vous pouvez bien entendu utiliser CSS comme à votre habitude pour mettre en forme tous les rendus de vos chouettes balises. Essayons d’autres trucs. Et si nous ajoutions des vignettes pour chaque article sur la page index.html ?
\nEt leur légende aussi peut-être.

\n
\n\n\n\n\"Front\n\n
Front matter c'est de la bombe !
\n
\n

Hé, c'est pas trop mal. Je suis sûr que vous pouvez déjà voir comment Jekyll va automatiser votre site en utilisant Liquid et YAML.

\n

Écrire un article pour de vrai

\n

Vous aurez noté l’extension .md ou .markdown pour vos articles. C’est l’abréviation pour Markdown, un langage léger qui convertit sans heurt du texte brut en HTML. Je me suis rendu-compte qu'écrire à l’aide de la syntaxe Markdown me permet de mieux me concentrer sur mon contenu, plutôt que de penser quelles balises fermer.

\n\n\n\n\"\"\n\n

La beauté de Markdown c'est que vous pouvez toujours utiliser HTML si vous en avez besoin. Pour forcer le rendu de Markdown à l’intérieur de balises HTML, ajoutez markdown=1 et le tour est joué ! Le meilleur des deux mondes. Voici un extrait de l’article une fois généré :

\n
\n\n\n\n\"Ne\n\n
Ne voudrions-nous pas vivre de Purring Cat ?
\n
\n

Un autre exemple d’article en .md

\n

Lorsque j'ai migré les vieux projets de mon portfolio dans Jekyll, j'ai trouvé que mélanger le HTML et Markdown c'était trop bizarre et que ça allait à l’encontre de l’objectif de clarté de Markdown. j’ai créé une démo qui montre ce que j'ai fait pour parvenir à des articles plus propres tout en gardant les styles désirés !
\nCe n'est en aucun cas une obligation ou la bonne manière de faire — juste une technique pour satisfaire mon côté hyper-maniaque. 😊 Vous êtes libres de télécharger et de vous amuser avec les fichiers sur Github.

\n

Ajoutons un peu de CSS à tout ça

\n

Maintenant que nous nous sommes familiarisés avec les possibilités de Jekyll et que nous avons un peu de contenu avec lequel travailler, ajoutons un peu de style ! Vous pouvez recopier le CSS ou le Sass de votre portfolio existant ou repartir de zéro.

\n\n\n\n\"img\"\n\n

Sass

\n

Vous avez probablement remarqué que les projets Jekyll sont livrés avec des fichiers Sass (avec une extension .scss). Bien que vous n'ayez pas besoin de connaître Sass pour pouvoir utiliser Jekyll, c'est un outil apprécié et recommandé dans le processus de développement CSS. Sérieusement, votre CSS sera bien mieux organisé et cohérent une fois que vous l’aurez adopté.
\nCes guides pour débutant m'ont beaucoup aidé quand j'ai commencé. Jekyll intègre par défaut le support de Sass, vous n'avez donc pas d’excuse pour l’adopter. 😉

\n

Versionnement avec Git

\n

Maintenant que vous vous êtes accommodés du terminal, je vous recommande vivement d’utiliser Git pour versionner votre portfolio. Git prend des \"clichés\" de votre dépôt — le répertoire du projet — à chaque fois que vous faites un commit, de façon à ce que vous puissiez revenir à des versions antérieures de votre travail quand c'est nécessaire. Si vous travaillez avec une autre personne, vous pouvez travailler chacun sur votre propre branche du projet et fusionner ensuite tout ça dans la branche master, visible de tous les intervenants du projet.

\n

Configurer Git

\n

Téléchargez et installez Git. De retour dans votre terminal, entrez ces commandes (et ajoutez vos propres infos entre les guillemets) :

\n
git config --global user.name “Votre Nom”\ngit config --global user.email \"[adresse mail]\"
\n

Super, nous sommes parés pour Git ! Mais notre projet ne pourra pas utiliser Git tant que nous ne l’aurons pas initialisé. Dans le répertoire mon-site, je vais donc taper :

\n
git init
\n

Facile ! Notre nouveau dépôt Git est vide, ajoutons-y donc nos fichiers.

\n
git add .
\n

Super, notre projet est ajouté au dépôt local et est prêt à être enregistré dans un commit. Prenons une photo de notre dépôt en faisant notre premier commit !
\nUtilisez l’option -m suivi d’un message significatif entre guillemets.

\n
git commit -m \"Première entrée du portfolio\"
\n

Notre projet possède officiellement un historique ! Git fonctionne en local, mais GitHub est un service de stockage distant pour pousser nos dépôts sur le web et les partager avec le reste du monde. Connectons notre dépôt local à un dépôt distant sur GitHub et poussons notre premier commit.

\n

Créer un dépôt sur GitHub

\n

Maintenant que nous avons initialisé Git pour notre portfolio, configurons un dépôt distant sur GitHub.

\n
    \n
  1. Créez-vous un compte, si vous n'en possédez pas encore.
    2. \n
  2. Créez un nouveau dépôt.
    \n\n\n\n\"Dans\n\n
    Dans le coin en haut à droite.
    \n
    \n
    3. \n
  3. Donnez un nom et ajoutez une description à votre dépôt. Créez le dépôt ! \n\n\n\"img\"\n\n
    4. \n
  4. Maintenant que vous avez créé le dépôt, vous allez voir cette page s'afficher sur GitHub : \n\n\n\"img\"\n\n

    C’est la partie \"publier un dépôt existant en ligne de commande\" qui nous intéresse. Je vais copier-coller ces commandes dans le terminal.
    \ngit remote add origin connecte les deux dépôts pour permettre le déploiement.
    \ngit push pousse les commits locaux dans votre dépôt distant !

    \n
    5. \n
  5. Actualisez la page de votre dépôt distant et félicitez-vous ! ON A RÉUSSI.
    \nMaintenant le monde entier peut admirer notre super portfolio !
    6. \n
\n\n\n\n\"\"\n\n

Voici un guide pour débutant très sympa pour des explications plus détaillées.

\n

GitHub Pages

\n

À partir de là, nous pouvons aller encore plus loin et configurer notre dépôt pour GitHub Pages — un hébergement gratuit sans FTP. Yep, ça veut dire que vous pouvez enregistrer et publier vos changements et voir immédiatement ces modifications en ligne !

\n

C’est un écosystème complet, accessible depuis votre terminal de confiance.

\n

Mes conseils supplémentaires

\n

Parce que ce guide n'est pas déjà assez long.

\n

Tester sur mobile

\n

Le test sur mobile est inclus ! Autorisons Jekyll à accéder à notre mobile en lançant le serveur de cette manière dans le terminal :

\n
jekyll serve --host 0.0.0.0
\n

Ensuite, récupérez votre adresse IP sur le réseau Wi-Fi local et faites là pointer vers le port 4000. En gros, vous allez taper un truc comme 192.168.x.x:4000 dans votre navigateur mobile. Si vous voulez savoir comment ça marche, lisez cet article.

\n

Système de grille

\n\n\n\n\"img\"\n\n

Pour un portfolio, un système de grille léger est facile à implémenter et il ne se met pas en travers de votre CSS. J'utilise Jeet parce que j'aime sa syntaxe et sa souplesse. Ceci dit, il y en a des tonnes de super chouettes, comme Neat ou Toast.

\n

Rythme vertical

\n
\n\n\n\n\"From\n\n
From Typecast.
\n
\n

Le rythme vertical c'est l’espacement constant et la mise à l’échelle des paragraphes, des marges externes et internes, des tailles de police et des hauteurs de ligne. Trouver le bon rythme améliore la lisibilité et l’harmonie d’un site. J'utilise modular-scale sur mon propre portfolio. Apprenez en davantage sur le rythme vertical\nici ou là.

\n

Fin

\n

Et voilà comment on crée et on déploie un joli modèle de portfolio, entièrement à partir du terminal. Vous n'avez plus qu'à créer un simple article au format texte pour les nouveaux projets et à taper quelques commandes pour le publier sur GitHub Pages.

\n

J'espère que vous avez aimé construire un portfolio pour Food Right Meow avec moi. Créer et redesigner votre portfolio devrait être fun et enrichissant, alors à vos claviers et à vos lignes de commande !

\n

Téléchargez ou forkez le dépôt de démo

\n

Voir la démo en action

\n\n\n\n\"\\o/\"\n\n
\n
\n
    \n
  1. \n

    Installez Ruby et Jekyll à l’aide d’Homebrew sous Mac. ↩

    \n
    2. \n
  2. \n

    Le plugin jekyll-atom facilite la création de posts en respectant cette convention. ↩

    \n
    3. \n
\n
", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2016/10/29/creer-un-theme-pour-jekyll/", "url": "https://jamstatic.fr/2016/10/29/creer-un-theme-pour-jekyll/", "title": "Créer un thème pour Jekyll", "summary": "Jekyll permet de publier des thèmes sous forme de gem, afin de faciliter l’installation et les mises à jour.", "date_published": "2016-10-29T13:18:59+00:00","content_text": "Depuis la version 3.2, les webdesigners ont la possibilité de créer des thèmes pour Jekyll. Le support des thèmes sous forme de gem est encore récent mais les premiers thèmes commencent à arriver. Nous allons voir dans cet article que l’opération est assez triviale si vous êtes déjà familiarisé avec Jekyll et Git. Packager un thème se fait en quelques minutes grâce à l’utilisation de bundler. Voyons ensemble à quoi ressemble le workflow de création de thème pour Jekyll.\nPrérequis\nNous allons supposer que vous connaissez déjà Jekyll, que vous savez créer des modèles de pages, si ce n'est pas le cas, commencez par lire la documentation officielle, vous verrez c'est très accessible, c'est du HTML auquel on va ajouter un peu de Liquid, le langage de templating conçu pour les concepteurs de thèmes Shopify, pour accéder à nos données.\nNous ne nous étendrons donc pas sur cette partie, qui consiste à préparer vos différents modèles de pages, ce sont les conventions par défaut de Jekyll qui s'appliquent : les feuilles de styles sont stockées dans le dossier _sass, les modèles de pages dans le dossier _layouts, les composants réutilisables dans _includes. Enfin tous les assets (CSS, JS, images, fonts) sont regroupés dans un dossier assets (et non _assets pour éviter les conflits avec le plugin jekyll-assets).\nOn notera que pour le moment par défaut, seuls ces dossiers seront fournis par le thème, nous verrons comment y ajouter des contenus et des exemples un peu plus bas.\nLes thèmes seront téléchargés sous forme de gem, vous devez donc avoir installé bundler avec la commande gem install bundler, ce qui est généralement le cas puisque Jekyll encourage son utilisation pour la gestion des dépendances. Enfin, il vous faut créer un compte sur Rubygems pour publier votre thème, ça ne vous prendra que quelques secondes si vous avez déjà un compte GitHub.\nPréparer son thème\nVous avez donc un site statique sous Jekyll et vous souhaitez le partager avec la communauté sous forme de thème. Il y a deux façons de faire, selon vos préférences. L'une d’elle consiste à utiliser la commande new-theme pour générer une structure de base dans laquelle vous allez pouvoir ajouter vos fichiers :\nbundle exec jekyll new-theme mon-super-theme\nCette commande va créer un dossier dans le répertoire courant, qui portera le même nom que celui que vous avez fourni en argument, étonnant non ?\nCe dossier comprend tous les dossiers évoqués plus haut : _includes, _layouts, _sass et assets ainsi qu'un fichier Gemfile et un fichier mon-super-theme.gempsec qui contient les informations sur votre thème.\nVous pouvez maintenant recopier les fichiers de votre thème dans cette structure d’exemple.\nL'autre manière de faire, c'est de partir de votre site fonctionnel et d’adapter sa structure de manière à vous retrouver avec quelque chose qui ressemble à ça :\n├── .gitignore\n├── Gemfile\n├── LICENSE.md\n├── README.md\n├── _includes\n│   └── head.html\n│   └── …\n├── _layouts\n│   ├── default.html\n│   ├── home.html\n│   ├── page.html\n│   └── post.html\n│   └── …\n├── _sass\n│   ├── _base.scss\n│   ├── _variables.scss\n│   ├── …\n├── assets\n│   ├── favicons\n│   ├── fonts\n│   └── images\n│   └── js\n│   └── css\n├── demo\n│   ├── 404.html\n│   ├── Gemfile\n│   ├── _config.yml\n│   ├── _posts\n│   │   ├── 2016-10-20-presentation-de-jekyll.md\n│   │   ├── 2016-01-02-exemple-de-contenu.md\n│   │   └── 2016-01-03-introduction.md\n│   │   └── …\n├── mon-super-theme.gemspec\n└── screenshot.png\nParmi les différences avec un site Jekyll classique, on remarque la présence d’un fichier Gemfile un peu particulier, d’un fichier gemspec pour la spécification de la gem, d’un fichier LICENSE (MIT par défaut), d’un fichier README.md, d’une capture d’écran et d’un dossier demo (ou example, c'est selon).\nSi on regarde le contenu du fichier Gemfile d’une gem, il est différent de ceux que vous avez l’habitude d’utiliser. Il fait simplement référence au fichier de spécification de la gem :\nsource \"https:\/\/rubygems.org\"\ngemspec\nEn effet, c'est le fichier gemspec qui va contenir toutes les infos sur notre thème : le numéro de version, sa description, ses dépendances, etc. Pour savoir tout ce que peut contenir ce type de fichier, je vous invite à consulter la documentation de référence des spécifications d’une gem.\nLorsque vous utilisez la commande new-theme de Jekyll, par défaut, le fichier de spécification de votre gem ressemble à ça :\n# frozen-string-literal: true\nGem::Specification.new do |spec|\n spec.name = \"mon-super-theme\"\n spec.version = \"0.1.0\"\n spec.authors = [\"Frank Taillandier\"]\n spec.email = [\"frank@jekyllrb.com\"]\n spec.summary = %q{TODO : Une courte description de votre thème, requise par Rubygems.}\n spec.homepage = \"TODO : Indiquez ici l’adresse du site de votre gem ou l’URL publique de son dépôt\"\n spec.license = \"MIT\"\n spec.files = `git ls-files -z`.split(\"\\x0\").select { |f| f.match(%r{^(assets|_layouts|_includes|_sass|LICENSE|README)}i) }\n spec.add_development_dependency \"jekyll\", \"~> 3.5\"\n spec.add_development_dependency \"bundler\", \"~> 1.15\"\n spec.add_development_dependency \"rake\", \"~> 12.0\"\nend\nOutre les méta-données à renseigner, il est intéressant de noter qu'une expression régulière basée sur une commande Git liste les fichiers à inclure dans la gem, cela implique donc que vos fichiers soient versionnés avec Git. Le minimum étant d’avoir initialisé votre dépôt, d’avoir ajouté tous les fichiers qui vont bien et d’avoir enregistré le tout : git init && git add . && git commit -m \"Initial commit\".\nOn peut voir aussi à la fin du fichier que la version 3.3 ou supérieure de Jekyll est requise, en effet avant cette version, le dossier assets n'était pas géré et le support initial des thèmes n'est arrivé qu'avec la version 3.2.\nOn constate aussi que bundler est déclaré en tant que dépendance pour le développement, ainsi que rake, souvent utilisé pour ajouter des tests ou des tâches automatisées.\nVous pouvez très bien vouloir ajouter d’autres dépendances lors de l’exécution, si vous souhaitez utiliser des plugins dans votre thème. Dans notre exemple, nous voulons ajouter la gestion d’un flux RSS, la génération d’un sitemap et des méta-données pour le SEO.\nNous ajoutons donc les dépendances ainsi que les versions minimales requises, comme nous le ferions dans un fichier Gemfile à l’aide de spec.add_runtime_dependency :\nspec.add_runtime_dependency \"jekyll-feed\", \"~> 0.8\"\nspec.add_runtime_dependency \"jekyll-sitemap\", \"~> 0.12\"\nspec.add_runtime_dependency \"jekyll-seo-tag\", \"~> 2.0\"\nUne fois que votre fichier de spécification est complété, vous allez pouvoir tester votre thème.\nTester son thème\nCommencez par lancer bundle install pour installer les dépendances mentionnées dans le fichier gemspec.\nFournir des exemples de contenu\nComme nous l’avons dit plus haut, pour le moment les thèmes sont livrés sans contenu et ne contiennent que les modèles et les assets. Lors d’une mise à jour de thème, tous ces fichiers seront écrasés, c'est le principal intérêt d’utiliser une gem pour le designer ou l’utilisateur, mais à aucun moment vous ne souhaitez écraser les contenus existants.\nCependant, même si la gem ne contient pas de contenus, rien ne vous empêche d’en ajouter dans le dépôt de votre thème pour fournir un exemple de thème entièrement fonctionnel à vos utilisateurs.\nAfin de ne pas mélanger les fichiers d’exemple avec ceux de votre thème, il est donc conseillé de créer un dossier demo (ou example ou ce que vous voulez) et d’y stocker des contenus destinés à présenter aux utilisateurs le rendu de votre thème.\nEn plus des fichiers générés par la commande new-theme, nous ajouterons dans ce dossier demo tout ce qu'il faut pour faire tourner un site sous Jekyll : un fichier _config.yml, un fichier Gemfile ainsi que des pages et des posts bien entendu. Vous pouvez également ajouter des exemples de données dans le dossier _data voire des collections, comme vous le feriez dans n'importe quel site.\nLe fichier demo\/Gemfile ressemble à quelques détails près à celui que vous utiliseriez pour n'importe quel site :\nsource \"https:\/\/rubygems.org\"\ngem \"jekyll\", \"~> 3.3\"\ngem \"mon-super-theme\", path: \"..\/\"\ngroup :jekyll_plugins do\n gem \"jekyll-sitemap\"\n gem \"jekyll-seo-tag\"\n gem \"jekyll-feed\"\nend\nNous voyons qu'il fait référence à la gem de notre thème, mais comme pour le moment nous n'avons pas encore publié notre thème sous forme de gem, nous nous contentons de faire référence au dossier parent, qui contient les fichiers de notre thème. Cette notation est bien pratique pour tester votre thème en local. Une fois votre gem publiée, vous pourrez choisir de supprimer paramètre path de votre gem, pour que bundler aille télécharger la dernière version sur Rubygems. Nous listons également les plugins utilisés dans notre thème.\nMaintenant, pour que Jekyll utilise notre thème, nous allons devoir le lui indiquer dans le fichier demo\/_config.yml en ajoutant la ligne :\ntheme: mon-super-theme\nLà encore, le nom utilisé doit être le même que celui de votre fichier gemspec. Nous indiquons également dans ce fichier de configuration que nous utilisons les plugins suivants :\ngems:\n - jekyll-feed\n - jekyll-sitemap\n - jekyll-seo-tag\nNous pouvons maintenant tester notre thème en exécutant la commande bundle exec jekyll serve --source demo depuis le répertoire racine ou cd demo && bundle exec jekyll serve, c'est du pareil au même. N'oubliez pas d’ajouter le répertoire de destination - _site par défaut - à votre fichier .gitignore.\nVérifiez le rendu sur différents navigateurs et appareils, aidez-vous d’html-proofer si vous souhaitez vous assurer que tous les liens internes fonctionnent :\nbundle exec htmlproofer .\/demo\/_site --disable-external\nVous êtes satisfait de la première version de votre thème ? Parfait ! Veillez maintenant à bien renseigner le fichier README.md pour expliquer comment installer et utiliser votre thème, c'est toujours agréable d’avoir une bonne documentation à sa disposition.\nAfin de permettre aux utilisateurs d’avoir un aperçu de votre thème, il est également recommandé d’ajouter une capture d’écran nommée screenshot.png à la racine de votre dépôt et de l’insérer dans votre fichier README.md.\nPackager son thème\nUne fois que votre thème est fonctionnel, documenté, vous êtes parés pour la publication. Cette étape est déjà documentée sur le site de Jekyll, nous nous contenterons simplement ici de rappeler qu'elle se fait en deux temps.\nLa première commande va créer la gem à proprement parlé à partir du fichier de spécification :\ngem build mon-super-theme.gemspec\n Successfully built RubyGem\n Name: mon-super-theme\n Version: 0.0.1\n File: mon-super-theme-0.0.1.gem\nComme il est inutile de versionner la gem générée (mais cela ne vous dispense pas d’utiliser les tags git pour vous rappeler du moment où vous l’avez générée), pensez donc à ajouter la ligne suivante dans votre fichier .gitignore :\n*.gem\nVous pouvez en profiter pour vérifier que l’installation de votre gem se déroule\nsans encombres :\ngem install mon-super-theme-0.0.1.gem\nSuccessfully installed mon-super-theme-0.0.1\n1 gem installed\nSi tout est OK, il ne vous reste maintenant plus qu'à publier votre thème sur Rubygems :\ngem push mon-super-theme-0.0.1.gem\nPushing gem to https:\/\/rubygems.org…\nEt voilà ! Votre thème peut maintenant être utilisé avec Jekyll. Il n'existe pas encore de site officiel qui répertorie tous les thèmes installables via des gems pour Jekyll, c'est donc à vous de communiquer sur la disponibilité de votre thème, par exemple sur le forum de Jekyll, sur Twitter avec le hashtag #jekyllrb ou en commentaire de ce billet 😄.\nSi vous cherchez des références, vous pouvez toujours prendre exemple sur des structures de thèmes accessibles sur Github, notamment :\n\nMinima, le thème par défaut de Jekyll, idéal pour se familiariser avec la structure que nous venons de voir,\nAlembic un bon point de départ un plus complet proposé par David Darnes\nMinimal mistakes, le thème très complet de Michael Rose, qui utilise des collections et tout un tas d’autres fonctionnalités plus avancées de Jekyll.\n\nVoilà, maintenant c'est à vous de jouer, faites de beaux thèmes pour Jekyll !", "content_html": "\n

Prérequis

\n

Nous allons supposer que vous connaissez déjà Jekyll, que vous savez créer des modèles de pages, si ce n'est pas le cas, commencez par lire la documentation officielle, vous verrez c'est très accessible, c'est du HTML auquel on va ajouter un peu de Liquid, le langage de templating conçu pour les concepteurs de thèmes Shopify, pour accéder à nos données.

\n

Nous ne nous étendrons donc pas sur cette partie, qui consiste à préparer vos différents modèles de pages, ce sont les conventions par défaut de Jekyll qui s'appliquent : les feuilles de styles sont stockées dans le dossier _sass, les modèles de pages dans le dossier _layouts, les composants réutilisables dans _includes. Enfin tous les assets (CSS, JS, images, fonts) sont regroupés dans un dossier assets (et non _assets pour éviter les conflits avec le plugin jekyll-assets).

\n

On notera que pour le moment par défaut, seuls ces dossiers seront fournis par le thème, nous verrons comment y ajouter des contenus et des exemples un peu plus bas.

\n

Les thèmes seront téléchargés sous forme de gem, vous devez donc avoir installé bundler avec la commande gem install bundler, ce qui est généralement le cas puisque Jekyll encourage son utilisation pour la gestion des dépendances. Enfin, il vous faut créer un compte sur Rubygems pour publier votre thème, ça ne vous prendra que quelques secondes si vous avez déjà un compte GitHub.

\n

Préparer son thème

\n

Vous avez donc un site statique sous Jekyll et vous souhaitez le partager avec la communauté sous forme de thème. Il y a deux façons de faire, selon vos préférences. L'une d’elle consiste à utiliser la commande new-theme pour générer une structure de base dans laquelle vous allez pouvoir ajouter vos fichiers :

\n
bundle exec jekyll new-theme mon-super-theme
\n

Cette commande va créer un dossier dans le répertoire courant, qui portera le même nom que celui que vous avez fourni en argument, étonnant non ?

\n

Ce dossier comprend tous les dossiers évoqués plus haut : _includes, _layouts, _sass et assets ainsi qu'un fichier Gemfile et un fichier mon-super-theme.gempsec qui contient les informations sur votre thème.

\n

Vous pouvez maintenant recopier les fichiers de votre thème dans cette structure d’exemple.

\n

L'autre manière de faire, c'est de partir de votre site fonctionnel et d’adapter sa structure de manière à vous retrouver avec quelque chose qui ressemble à ça :

\n
├── .gitignore\n├── Gemfile\n├── LICENSE.md\n├── README.md\n├── _includes\n│   └── head.html\n│   └── …\n├── _layouts\n│   ├── default.html\n│   ├── home.html\n│   ├── page.html\n│   └── post.html\n│   └── …\n├── _sass\n│   ├── _base.scss\n│   ├── _variables.scss\n│   ├── …\n├── assets\n│   ├── favicons\n│   ├── fonts\n│   └── images\n│   └── js\n│   └── css\n├── demo\n│   ├── 404.html\n│   ├── Gemfile\n│   ├── _config.yml\n│   ├── _posts\n│   │   ├── 2016-10-20-presentation-de-jekyll.md\n│   │   ├── 2016-01-02-exemple-de-contenu.md\n│   │   └── 2016-01-03-introduction.md\n│   │   └── …\n├── mon-super-theme.gemspec\n└── screenshot.png
\n

Parmi les différences avec un site Jekyll classique, on remarque la présence d’un fichier Gemfile un peu particulier, d’un fichier gemspec pour la spécification de la gem, d’un fichier LICENSE (MIT par défaut), d’un fichier README.md, d’une capture d’écran et d’un dossier demo (ou example, c'est selon).

\n

Si on regarde le contenu du fichier Gemfile d’une gem, il est différent de ceux que vous avez l’habitude d’utiliser. Il fait simplement référence au fichier de spécification de la gem :

\n
source \"https://rubygems.org\"\ngemspec
\n

En effet, c'est le fichier gemspec qui va contenir toutes les infos sur notre thème : le numéro de version, sa description, ses dépendances, etc. Pour savoir tout ce que peut contenir ce type de fichier, je vous invite à consulter la documentation de référence des spécifications d’une gem.

\n

Lorsque vous utilisez la commande new-theme de Jekyll, par défaut, le fichier de spécification de votre gem ressemble à ça :

\n
# frozen-string-literal: true\nGem::Specification.new do |spec|\n  spec.name     = \"mon-super-theme\"\n  spec.version  = \"0.1.0\"\n  spec.authors  = [\"Frank Taillandier\"]\n  spec.email    = [\"frank@jekyllrb.com\"]\n  spec.summary  = %q{TODO : Une courte description de votre thème, requise par Rubygems.}\n  spec.homepage = \"TODO : Indiquez ici l’adresse du site de votre gem ou l’URL publique de son dépôt\"\n  spec.license  = \"MIT\"\n  spec.files    = `git ls-files -z`.split(\"\\x0\").select { |f| f.match(%r{^(assets|_layouts|_includes|_sass|LICENSE|README)}i) }\n  spec.add_development_dependency \"jekyll\", \"~> 3.5\"\n  spec.add_development_dependency \"bundler\", \"~> 1.15\"\n  spec.add_development_dependency \"rake\", \"~> 12.0\"\nend
\n

Outre les méta-données à renseigner, il est intéressant de noter qu'une expression régulière basée sur une commande Git liste les fichiers à inclure dans la gem, cela implique donc que vos fichiers soient versionnés avec Git. Le minimum étant d’avoir initialisé votre dépôt, d’avoir ajouté tous les fichiers qui vont bien et d’avoir enregistré le tout : git init && git add . && git commit -m \"Initial commit\".

\n

On peut voir aussi à la fin du fichier que la version 3.3 ou supérieure de Jekyll est requise, en effet avant cette version, le dossier assets n'était pas géré et le support initial des thèmes n'est arrivé qu'avec la version 3.2.

\n

On constate aussi que bundler est déclaré en tant que dépendance pour le développement, ainsi que rake, souvent utilisé pour ajouter des tests ou des tâches automatisées.

\n

Vous pouvez très bien vouloir ajouter d’autres dépendances lors de l’exécution, si vous souhaitez utiliser des plugins dans votre thème. Dans notre exemple, nous voulons ajouter la gestion d’un flux RSS, la génération d’un sitemap et des méta-données pour le SEO.

\n

Nous ajoutons donc les dépendances ainsi que les versions minimales requises, comme nous le ferions dans un fichier Gemfile à l’aide de spec.add_runtime_dependency :

\n
spec.add_runtime_dependency \"jekyll-feed\", \"~> 0.8\"\nspec.add_runtime_dependency \"jekyll-sitemap\", \"~> 0.12\"\nspec.add_runtime_dependency \"jekyll-seo-tag\", \"~> 2.0\"
\n

Une fois que votre fichier de spécification est complété, vous allez pouvoir tester votre thème.

\n

Tester son thème

\n

Commencez par lancer bundle install pour installer les dépendances mentionnées dans le fichier gemspec.

\n

Fournir des exemples de contenu

\n

Comme nous l’avons dit plus haut, pour le moment les thèmes sont livrés sans contenu et ne contiennent que les modèles et les assets. Lors d’une mise à jour de thème, tous ces fichiers seront écrasés, c'est le principal intérêt d’utiliser une gem pour le designer ou l’utilisateur, mais à aucun moment vous ne souhaitez écraser les contenus existants.

\n

Cependant, même si la gem ne contient pas de contenus, rien ne vous empêche d’en ajouter dans le dépôt de votre thème pour fournir un exemple de thème entièrement fonctionnel à vos utilisateurs.

\n

Afin de ne pas mélanger les fichiers d’exemple avec ceux de votre thème, il est donc conseillé de créer un dossier demo (ou example ou ce que vous voulez) et d’y stocker des contenus destinés à présenter aux utilisateurs le rendu de votre thème.

\n

En plus des fichiers générés par la commande new-theme, nous ajouterons dans ce dossier demo tout ce qu'il faut pour faire tourner un site sous Jekyll : un fichier _config.yml, un fichier Gemfile ainsi que des pages et des posts bien entendu. Vous pouvez également ajouter des exemples de données dans le dossier _data voire des collections, comme vous le feriez dans n'importe quel site.

\n

Le fichier demo/Gemfile ressemble à quelques détails près à celui que vous utiliseriez pour n'importe quel site :

\n
source \"https://rubygems.org\"\ngem \"jekyll\", \"~> 3.3\"\ngem \"mon-super-theme\", path: \"../\"\ngroup :jekyll_plugins do\n  gem \"jekyll-sitemap\"\n  gem \"jekyll-seo-tag\"\n  gem \"jekyll-feed\"\nend
\n

Nous voyons qu'il fait référence à la gem de notre thème, mais comme pour le moment nous n'avons pas encore publié notre thème sous forme de gem, nous nous contentons de faire référence au dossier parent, qui contient les fichiers de notre thème. Cette notation est bien pratique pour tester votre thème en local. Une fois votre gem publiée, vous pourrez choisir de supprimer paramètre path de votre gem, pour que bundler aille télécharger la dernière version sur Rubygems. Nous listons également les plugins utilisés dans notre thème.

\n

Maintenant, pour que Jekyll utilise notre thème, nous allons devoir le lui indiquer dans le fichier demo/_config.yml en ajoutant la ligne :

\n
theme: mon-super-theme
\n

Là encore, le nom utilisé doit être le même que celui de votre fichier gemspec. Nous indiquons également dans ce fichier de configuration que nous utilisons les plugins suivants :

\n
gems:\n  - jekyll-feed\n  - jekyll-sitemap\n  - jekyll-seo-tag
\n

Nous pouvons maintenant tester notre thème en exécutant la commande bundle exec jekyll serve --source demo depuis le répertoire racine ou cd demo && bundle exec jekyll serve, c'est du pareil au même. N'oubliez pas d’ajouter le répertoire de destination - _site par défaut - à votre fichier .gitignore.

\n

Vérifiez le rendu sur différents navigateurs et appareils, aidez-vous d’html-proofer si vous souhaitez vous assurer que tous les liens internes fonctionnent :

\n
bundle exec htmlproofer ./demo/_site --disable-external
\n

Vous êtes satisfait de la première version de votre thème ? Parfait ! Veillez maintenant à bien renseigner le fichier README.md pour expliquer comment installer et utiliser votre thème, c'est toujours agréable d’avoir une bonne documentation à sa disposition.

\n

Afin de permettre aux utilisateurs d’avoir un aperçu de votre thème, il est également recommandé d’ajouter une capture d’écran nommée screenshot.png à la racine de votre dépôt et de l’insérer dans votre fichier README.md.

\n

Packager son thème

\n

Une fois que votre thème est fonctionnel, documenté, vous êtes parés pour la publication. Cette étape est déjà documentée sur le site de Jekyll, nous nous contenterons simplement ici de rappeler qu'elle se fait en deux temps.

\n

La première commande va créer la gem à proprement parlé à partir du fichier de spécification :

\n
gem build mon-super-theme.gemspec\n  Successfully built RubyGem\n  Name: mon-super-theme\n  Version: 0.0.1\n  File: mon-super-theme-0.0.1.gem
\n

Comme il est inutile de versionner la gem générée (mais cela ne vous dispense pas d’utiliser les tags git pour vous rappeler du moment où vous l’avez générée), pensez donc à ajouter la ligne suivante dans votre fichier .gitignore :

\n
*.gem
\n

Vous pouvez en profiter pour vérifier que l’installation de votre gem se déroule\nsans encombres :

\n
gem install mon-super-theme-0.0.1.gem\nSuccessfully installed mon-super-theme-0.0.1\n1 gem installed
\n

Si tout est OK, il ne vous reste maintenant plus qu'à publier votre thème sur Rubygems :

\n
gem push mon-super-theme-0.0.1.gem\nPushing gem to https://rubygems.org…
\n

Et voilà ! Votre thème peut maintenant être utilisé avec Jekyll. Il n'existe pas encore de site officiel qui répertorie tous les thèmes installables via des gems pour Jekyll, c'est donc à vous de communiquer sur la disponibilité de votre thème, par exemple sur le forum de Jekyll, sur Twitter avec le hashtag #jekyllrb ou en commentaire de ce billet 😄.

\n

Si vous cherchez des références, vous pouvez toujours prendre exemple sur des structures de thèmes accessibles sur Github, notamment :

\n\n

Voilà, maintenant c'est à vous de jouer, faites de beaux thèmes pour Jekyll !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2016/10/07/jekyll-3-3-est-dispo/", "url": "https://jamstatic.fr/2016/10/07/jekyll-3-3-est-dispo/", "title": "Les nouveautés de Jekyll 3.3", "summary": "Jekyll 3.3 intègre le support des assets dans les thèmes, de nouveaux filtres pour les URLs et bien plus encore.", "date_published": "2016-10-07T00:00:00+00:00","content_text": "Plein de nouveautés pour vous simplifier la vie dans la version\n3.3 de Jekyll. On retiendra trois fonctionnalités à tester en priorité.\nLes thèmes peuvent désormais fournir des assets statiques et dynamiques dans le dossier \/assets\nDepuis Jekyll 3.2, il est possible de packager un thème sous forme de\ngem, il était déjà possible d’embarquer des\nincludes, des layouts et des fichiers Sass. Avec la version 3.3, il est enfin\npossible d’ajouter aussi des assets à son thème. Les développeurs de thèmes vont\ndonc pouvoir fournir des thèmes complets et les utilisateurs pourront les tester\net les mettre à jour plus simplement. Cette fonctionnalité n'est pas encore très\nmature et le support de fichier de configuration pour les thèmes ou l’ajout d’un\ndossier data sont en cours de discussion.\nPour faciliter davantage la gestion de thème, tout fichier présent dans le\ndossier \/assets de votre thème sera considéré comme faisant partie du site de\nl’utilisateur du thème. Vous pouvez donc ajouter du Sass, du JavaScript, du\nCoffeeScript, des images, des fontes et tout ce qui sera utile à la présentation\net au comportement de votre thème. Les règles sont les mêmes que dans Jekyll :\nsi un fichier comporte des entêtes YAML Front Matter, il sera converti et traité\npar le moteur de rendu. Si le fichier ne comporte aucun en-tête YFM, il sera\nsimplement copié comme un asset statique.\nNotez bien que les fichiers de l’utilisateur avec le même chemin prennent\ntoujours le pas sur ceux de votre thème. Par exemple si un fichier\n\/assets\/main.scss est présent dans le dossier du site de l’utilisateur, c'est\nlui qui sera traité en lieu et place du fichier \/assets\/main.scss présent dans\nla gem de votre thème.\nNous vous invitons à vous reporter à la\ndocumentation officielle sur la gestion des assets dans les thèmes\npour plus d’informations.\nLes filtres relative_url et absolute_url\nDeux nouveaux filtres font leur apparition pour simplifier la gestion des URLs\ndans vos templates. Fini de vous emmêler les pinceaux avec baseurl et url.\nLorsque vous développez en local, si vous définissez la valeur de baseurl afin\nqu'elle corresponde à votre environnement de développement, mettons par exemple\nbaseurl: \"\/mondossier\", le filtre relative_url se chargera de préfixer cette\nvaleur pour toutes les URLs que vous appellerez :\n{{ \"\/docs\/assets\/\" | relative_url }} => \/mondossier\/docs\/assets\nPar défaut, baseurl est défini à \"\" et sera remplacé tel quel (ne définissez\njamais cette valeur à \"\/\"):\n{{ \"\/docs\/assets\/\" | relative_url }} => \/docs\/assets\nLe résultat d’un appel à relative_url produira toujours une URL relative au\ndomaine racine. Le même principe s'applique au filtre absolute_url, il ajoute\nles valeurs définies dans baseurl et url et facilite ainsi la création\nd’URLs absolues :\n{{ \"\/docs\/assets\/\" | absolute_url }} => http:\/\/jamstatic.fr\/mondossier\/docs\/assets\nsite.url est maintenant défini pour le serveur de développement\nQuand vous lancez la commande jekyll serve en local, elle va démarrer un\nserveur web, généralement à l’adresse http:\/\/localhost:4000, sur lequel vous\nallez pouvoir prévisualiser votre site durant la phase de développement. Si vous\nutilisez le filtre absolute_url ou site.url dans votre code, vous avez\nprobablement dû créer un fichier de configuration pour le développement, qui va\nréinitialiser la valeur d’url à http:\/\/localhost:4000.\nC’est maintenant inutile ! Quand vous lancez la commande jekyll serve, Jekyll\nva générer votre site avec les valeurs de host, port et des options\nrelatives à SSL. Par défaut ce sera donc url: http:\/\/localhost:4000. Quand\nvous développez en local, la valeur de site.url sera donc remplacée par\nhttp:\/\/localhost:4000.\nC’est le comportement par défaut lorsque vous exécutez Jekyll en local. Ce ne\nsera pas le cas si vous exécutez jekyll serve si vous précisez un\nenvironnement de production avec JEKYLL_ENV=production. Si la variable\nd’environnement JEKYLL_ENV possède une autre valeur que development (sa\nvaleur par défaut), Jekyll n'écrasera pas la valeur du paramètre url définie\ndans votre fichier de configuration. Attention, cela ne s'applique qu'à la\ncommande serve, pas à la commande build`.\nEt bien plus encore\nPour avoir le détail de tous les correctifs et les améliorations mineures\napportées, vous pouvez\nconsulter le CHANGELOG complet.\nJekyllez bien !", "content_html": "\n

Les thèmes peuvent désormais fournir des assets statiques et dynamiques dans le dossier /assets

\n

Depuis Jekyll 3.2, il est possible de packager un thème sous forme de\ngem, il était déjà possible d’embarquer des\nincludes, des layouts et des fichiers Sass. Avec la version 3.3, il est enfin\npossible d’ajouter aussi des assets à son thème. Les développeurs de thèmes vont\ndonc pouvoir fournir des thèmes complets et les utilisateurs pourront les tester\net les mettre à jour plus simplement. Cette fonctionnalité n'est pas encore très\nmature et le support de fichier de configuration pour les thèmes ou l’ajout d’un\ndossier data sont en cours de discussion.

\n

Pour faciliter davantage la gestion de thème, tout fichier présent dans le\ndossier /assets de votre thème sera considéré comme faisant partie du site de\nl’utilisateur du thème. Vous pouvez donc ajouter du Sass, du JavaScript, du\nCoffeeScript, des images, des fontes et tout ce qui sera utile à la présentation\net au comportement de votre thème. Les règles sont les mêmes que dans Jekyll :\nsi un fichier comporte des entêtes YAML Front Matter, il sera converti et traité\npar le moteur de rendu. Si le fichier ne comporte aucun en-tête YFM, il sera\nsimplement copié comme un asset statique.

\n

Notez bien que les fichiers de l’utilisateur avec le même chemin prennent\ntoujours le pas sur ceux de votre thème. Par exemple si un fichier\n/assets/main.scss est présent dans le dossier du site de l’utilisateur, c'est\nlui qui sera traité en lieu et place du fichier /assets/main.scss présent dans\nla gem de votre thème.

\n

Nous vous invitons à vous reporter à la\ndocumentation officielle sur la gestion des assets dans les thèmes\npour plus d’informations.

\n

Les filtres relative_url et absolute_url

\n

Deux nouveaux filtres font leur apparition pour simplifier la gestion des URLs\ndans vos templates. Fini de vous emmêler les pinceaux avec baseurl et url.\nLorsque vous développez en local, si vous définissez la valeur de baseurl afin\nqu'elle corresponde à votre environnement de développement, mettons par exemple\nbaseurl: \"/mondossier\", le filtre relative_url se chargera de préfixer cette\nvaleur pour toutes les URLs que vous appellerez :

\n
{{ \"/docs/assets/\" | relative_url }} => /mondossier/docs/assets
\n

Par défaut, baseurl est défini à \"\" et sera remplacé tel quel (ne définissez\njamais cette valeur à \"/\"):

\n
{{ \"/docs/assets/\" | relative_url }} => /docs/assets
\n

Le résultat d’un appel à relative_url produira toujours une URL relative au\ndomaine racine. Le même principe s'applique au filtre absolute_url, il ajoute\nles valeurs définies dans baseurl et url et facilite ainsi la création\nd’URLs absolues :

\n
{{ \"/docs/assets/\" | absolute_url }} => http://jamstatic.fr/mondossier/docs/assets
\n

site.url est maintenant défini pour le serveur de développement

\n

Quand vous lancez la commande jekyll serve en local, elle va démarrer un\nserveur web, généralement à l’adresse http://localhost:4000, sur lequel vous\nallez pouvoir prévisualiser votre site durant la phase de développement. Si vous\nutilisez le filtre absolute_url ou site.url dans votre code, vous avez\nprobablement dû créer un fichier de configuration pour le développement, qui va\nréinitialiser la valeur d’url à http://localhost:4000.

\n

C’est maintenant inutile ! Quand vous lancez la commande jekyll serve, Jekyll\nva générer votre site avec les valeurs de host, port et des options\nrelatives à SSL. Par défaut ce sera donc url: http://localhost:4000. Quand\nvous développez en local, la valeur de site.url sera donc remplacée par\nhttp://localhost:4000.

\n

C’est le comportement par défaut lorsque vous exécutez Jekyll en local. Ce ne\nsera pas le cas si vous exécutez jekyll serve si vous précisez un\nenvironnement de production avec JEKYLL_ENV=production. Si la variable\nd’environnement JEKYLL_ENV possède une autre valeur que development (sa\nvaleur par défaut), Jekyll n'écrasera pas la valeur du paramètre url définie\ndans votre fichier de configuration. Attention, cela ne s'applique qu'à la\ncommande serve, pas à la commande build`.

\n

Et bien plus encore

\n

Pour avoir le détail de tous les correctifs et les améliorations mineures\napportées, vous pouvez\nconsulter le CHANGELOG complet.

\n

Jekyllez bien !

", "authors": [ { "name": "frank" } ], "language": "fr" }, { "id": "https://jamstatic.fr/2016/09/18/utiliser-des-plugins-jekyll-avec-github-pages/", "url": "https://jamstatic.fr/2016/09/18/utiliser-des-plugins-jekyll-avec-github-pages/", "title": "Utiliser des plugins Jekyll sur GitHub Pages", "summary": "Automatiser la publication d'un site Jekyll sur GitHub Pages quels que soient les plugins utilisés.", "date_published": "2016-09-18T11:51:13+00:00", "date_modified": "2010-09-18T11:51:13+00:00","content_text": "La popularité de Jekyll est en partie due à son support natif par GitHub Pages. Si cette solution gratuite est bien pratique, elle n’en reste pas moins limitée en termes de support de plugins Jekyll et ce pour des raisons de sécurité. Si vous voulez utiliser des plugins comme jekyll-cloudinary ou jekyll-assets, il va falloir utiliser GitHub Actions ou générer votre site localement avant de le pousser en ligne.\nMise à jour : GitHub Actions permet maintenant de publier un site Jekyll quels que soient les plugins utilisés.\nNous allons voir que cette opération est facilement automatisable à l’aide d’un fichier Rakefile, la manière la plus courante en Ruby de créer des tâches.\nPrérequis\nNous partons du principe que vous avez déjà un site qui tourne avec Jekyll sur GitHub, si ce n’est pas le cas, reportez-vous à la documentation officielle.\nComme nous allons utiliser rake pour écrire une tâche automatisée, il vous faut ajoutez la dépendance à votre fichier Gemfile, si elle n'est pas déjà présente :\n gem \"rake\"\nUne fois que c'est fait, lancez bundle install pour installer rake.\nMaintenant que vous êtes parés sous allons voir les deux cas de figures possibles dans Github : les pages utilisateurs ou organisation et les pages projets.\nPages utilisateur et organisation\nPour activer la génération automatique par GitHub Pages d’un dépôt de compte utilisateur ou organisation, il suffit de respecter la nomenclature username\/username.github.io.\nGitHub va utiliser la branche master de ces dépôts et publier les pages. Cela fait que nous aurons une branche master qui contient le site généré et une branche source avec les sources de notre site.\nConfiguration du dépôt\nLa préparation du dépôt se résume à créer la branche source en ligne de commande :\ngit checkout -b source master\ngit push -u origin source\nMaintenant que vous avez créé la branche source, vous pouvez en faire la branche par défaut dans GitHub :\n\n\n\n\n\n\nParamétrage des branches dans GitHub.\n\nPublication automatique\nMaintenant que le dépôt est configuré, vous pouvez générer votre site et pousser les fichiers générés sur la branche master. Mais plutôt que de s'embêter à faire ça manuellement, créons un simple tâche rake. Créez (si vous n'en avez pas déjà un) un fichier Rakefile à la racine de votre site et ajoutez le contenu suivant 1 :\n\nMaintenant vous pouvez simplement lancer la commande rake publish pour générer et publier votre site sur GitHub Pages.\nSi vous utilisez un nom de domaine personnalisé, vérifiez bien que le fichier CNAME est bien présent dans la branche générée.\nPages projet\nLes pages projet sont presque pareilles que les pages utilisateur et organisation, à une différence près : la branche gh-pages est utilisée à la place de la branche master pour générer et publier les pages.\nIl n'y a aucune configuration supplémentaire à faire, il faut simplement apporter quelques petites modifications au fichier Rakefile :\n\nVous pouvez maintenant lancer rake site:publish pour générer votre site et le publier sur GitHub. Jetez également un coup d’œil au fichier Rakefile de Jekyll pour une implémentation alternative de la tâche rake site:publish.\n\n\n\n\n\n\nOctoJekyll.\n\nEnfin, sachez qu'il existe d’autres solutions d’hébergement comme GitLab Pages, Netlify, Cloudcannon, Siteleaf ou Forestry.io qui vous permettent d’utiliser les plugins de votre choix, sans avoir recours à ce genre de hack.\n\n\n\n\nLes tâches utilisées dans ce billet ont été écrites par Ixti, le créateur du plugin jekyll-assets. ↩\n\n\n", "content_html": "\n\n

Nous allons voir que cette opération est facilement automatisable à l’aide d’un fichier Rakefile, la manière la plus courante en Ruby de créer des tâches.

\n

Prérequis

\n

Nous partons du principe que vous avez déjà un site qui tourne avec Jekyll sur GitHub, si ce n’est pas le cas, reportez-vous à la documentation officielle.

\n

Comme nous allons utiliser rake pour écrire une tâche automatisée, il vous faut ajoutez la dépendance à votre fichier Gemfile, si elle n'est pas déjà présente :

\n
  gem \"rake\"
\n

Une fois que c'est fait, lancez bundle install pour installer rake.

\n

Maintenant que vous êtes parés sous allons voir les deux cas de figures possibles dans Github : les pages utilisateurs ou organisation et les pages projets.

\n

Pages utilisateur et organisation

\n

Pour activer la génération automatique par GitHub Pages d’un dépôt de compte utilisateur ou organisation, il suffit de respecter la nomenclature username/username.github.io.

\n

GitHub va utiliser la branche master de ces dépôts et publier les pages. Cela fait que nous aurons une branche master qui contient le site généré et une branche source avec les sources de notre site.

\n

Configuration du dépôt

\n

La préparation du dépôt se résume à créer la branche source en ligne de commande :

\n
git checkout -b source master\ngit push -u origin source
\n

Maintenant que vous avez créé la branche source, vous pouvez en faire la branche par défaut dans GitHub :

\n
\n\n\n\n\"Paramétrage\n\n
Paramétrage des branches dans GitHub.
\n
\n

Publication automatique

\n

Maintenant que le dépôt est configuré, vous pouvez générer votre site et pousser les fichiers générés sur la branche master. Mais plutôt que de s'embêter à faire ça manuellement, créons un simple tâche rake. Créez (si vous n'en avez pas déjà un) un fichier Rakefile à la racine de votre site et ajoutez le contenu suivant 1 :

\n