Démarrer un nouveau projet avec Eleventy

Cet article est le premier d'une série dans laquelle tu vas apprendre les bases d'Eleventy à travers la création d'un mini-blog. Dans cet article nous allons commencer par voir comment initialiser un nouveau projet à partir de zéro. Dans le suivant, nous créerons les sources de notre mini blog.

Eleventy, c'est quoi ?

Eleventy est un générateur de sites statiques (SSG). Un site statique est un site dont le rendu visuel des pages est fait avant la publication du site sur le serveur. Les pages HTML du site sont donc toutes prêtes à être envoyées au navigateur dès qu'on navigue vers leurs URL et n'ont pas à être générées dynamiquement à chaque requête.

Tip

Avant d'aller plus loin, si tu n'es pas familier avec la notion de site statique, je te conseille vivement la lecture de cet article qui t'expliquera dans quels cas l'utiliser, et les principes de base de construction d'un site statique à l'aide d'un générateur.
De plus, si tu te veux savoir quels sont les atouts d'Eleventy face à d'autres générateurs plus connus tels que Hugo, Gatsby, Astro ou Jekyll, tu peux jeter un œil à ce court article.

Je supposerai donc maintenant que tu sais ce qu'est un site statique et que tu connais les atouts du SSG Eleventy. Nous allons donc pouvoir entrer dans le code et voir concrètement comment mettre en place un projet Eleventy.

Partir d'un projet de démarrage... ou pas

La page Starter Projects du site d'Eleventy propose une liste de 170 projets de démarrage. Chacun représente un embryon de site avec ses dispositions de pages, styles et fonctionnalités propres. Partir d'un projet de démarrage qui correspond bien à ses besoins peut faire gagner beaucoup de temps par rapport à la création d'un projet à partir de zéro.

Cependant, trouver le bon projet de démarrage est loin d'être simple pour 3 raisons :

La page qui liste les projets n'affiche qu'une description très succincte de chaque projet et n'offre aucun moyen de filtrer la liste selon divers critères.
Certains projets ont un site de démonstration, mais ce dernier ne montre parfois pas grand-chose.
Beaucoup de projets n'ont pas été maintenus au cours de l'évolution d'Eleventy et sont donc maintenant complètement obsolètes ou bien nécessitent une mise à jour importante.

En pratique, cette liste est donc difficilement exploitable, et l'on peut perdre beaucoup de temps à errer d'un projet à l'autre.

Warning

De plus, choisir un projet de démarrage sans être sûr qu'il correspond à tes besoins risque finalement de te faire perdre beaucoup de temps.

Mon expérience perso est la suivante :
Pour créer mon blog, je suis parti du projet de démarrage officiel nommé eleventy-base-blog. Mais d'une part, ce projet n'est pas nativement multilingue, et d'autre part, lorsque j'ai commencé à mieux maîtriser Eleventy, je me suis aperçu que certains choix techniques de ce projet ne correspondaient pas à ce que je voulais. Si bien que le code actuel de mon site n'a plus rien à voir avec celui du projet de démarrage. Si c'était à refaire, je partirais donc aujourd'hui sans hésiter d'un projet vierge.

En effet, adapter le code d'un projet de démarrage existant peut parfois prendre plus de temps que de partir de zéro, surtout avec l'aide de l'IA. De plus, il y a un risque important de laisser du code mort (notamment des filtres et styles) qui ne fera que nous embrouiller par la suite.

Tip

Donc, à moins que tu sois pressé et peu exigeant, mon conseil serait de ne partir d'un projet de démarrage existant que s'il correspond vraiment bien à ce que tu souhaites faire. Une solution alternative est de démarrer un projet vierge et de t'inspirer du code de certains projets pour implémenter plus rapidement certaines choses.

Dans la suite de cet article, je vais te montrer comment créer un projet à partir de zéro. Si tu souhaites essayer un projet de démarrage téléchargé sur le site d'Eleventy, il te suffit de décompresser le fichier zip à l'endroit souhaité, et de lancer la commande npm install que nous allons voir plus loin.

Installer les outils nécessaires

Eleventy s'appuie sur Node.js pour générer le site. Avant de créer un projet, il faut donc commencer par installer Node.js sur ton poste si ce n'est pas déjà fait. Tu peux le télécharger sur le site officiel de Node. Le gestionnaire de packages npm s'installe automatiquement avec Node. Il nous sera très utile pour ajouter des plugins et lancer la génération de notre site.

Note

Node.js sert juste à la phase de génération du site, et non au fonctionnement du site en production. Un site statique n'a pas besoin de Node.js ni aucun framework serveur pour fonctionner.

Il te faut bien entendu aussi un éditeur de code. Je prendrai l'exemple de VS Code, mais tu peux en utiliser un autre.
Je te recommande aussi l'extension Better Nunjucks, qui apporte la coloration syntaxique et des snippets pour le langage de template Nunjucks que nous utiliserons dans notre projet.

Tip

L'extension vscode-icons est également très commode pour mieux s'y retrouver dans les nombreux fichiers de l'explorateur de projet, car elle associe des icônes et couleurs spécifiques à chaque type de fichier. On distingue ainsi beaucoup plus facilement les fichiers Nunjucks (HTML), Markdown, CSS et JavaScript.

Créer le projet

Pour créer un nouveau projet, voici les étapes à suivre :

Crée un dossier pour le projet à l'endroit souhaité sur ton disque
Ouvre ce dossier dans VS Code (Menu Fichier \ Ouvrir le dossier)
Ouvre un terminal (menu Terminal \ Nouveau Terminal ou CTRL+MAJ+ù). L'invite pointe normalement vers le dossier ouvert. Exécute les commandes suivantes une par une :

npm init -y
npm pkg set type="module"
npm install @11ty/eleventy

La première commande crée un fichier package.json qui référencera tous les packages npm (= modules) nécessaires au projet.
La 2e spécifie qu'on va utiliser le standard ECMAScript Modules plutôt que CommonJS pour référencer et utiliser les modules. Concrètement, cela permet d'utiliser la syntaxe import ... from "module_name";
La 3e installe le package npm d'Eleventy et toutes ses dépendances. Elle crée pour cela un dossier node_modules contenant plus de 1700 fichiers, mais qui ne pèsent au total que 16 Mo. Tu n'auras jamais besoin de modifier ce dossier manuellement.

Voici à quoi ressemble le contenu du fichier package.json pour un dossier de travail nommé "demo" :

{
  "name": "demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "@11ty/eleventy": "^3.1.2"
  }
}

On voit que le package Eleventy est automatiquement référencé dans la propriété "dependencies". Tu peux changer le nom du projet et ajouter une description si tu le souhaites. Mais le plus important est d'ajouter des commandes de build.

Ajouter les commandes de build

Il s'agit des commandes qui permettront de lancer la génération du site, c'est-à-dire de générer les fichiers de sortie à partir des fichiers d'entrée (les sources du projet). Pour cela, on modifie la section "scripts" avec ce qui suit :

"scripts": {
	"build": "npx @11ty/eleventy",
	"start": "npx @11ty/eleventy --serve --quiet",
}

La première commande lance Eleventy pour générer le site à partir des sources. Elle permet surtout de vérifier que tous les fichiers sources sont corrects et que le site se génère bien, sans le lancer.

La seconde commande fait la même chose, puis lance le serveur HTTP intégré dans Eleventy et ouvre la page d'index du site dans le navigateur par défaut. Elle permet donc en plus de vérifier le visuel du site.

Note

Comme tu peux le voir, Eleventy est autonome pour construire et exécuter un site. Cette intégration lui permet de construire un site bien plus vite que tous les autres générateurs de sites qui s'appuient sur des outils externes comme Webpack par exemple.

À ce stade, nous avons ce qu'il faut pour commencer la phase de développement du site en ajoutant des fichiers sources.

Créer un fichier de configuration

Un projet Eleventy comporte obligatoirement un fichier eleventy.config.js qui décrit sa configuration. Tu peux donc le créer dès maintenant à la racine du projet.

Ce fichier est en quelque sorte le noyau du projet, qui centralise toute sa configuration. Nous le compléterons au fur et à mesure de la construction de notre projet d'exemple, mais nous en avons besoin dès maintenant pour déclarer et configurer les plugins.

Ajouter des plugins

Zach Leatherman, le créateur d'Eleventy, a souhaité dès le départ faire d'Eleventy un framework modulaire en externalisant les fonctionnalités avancées dans des plugins, plutôt qu'en les intégrant dans le package de base. Le noyau du framework reste ainsi léger, et chacun peut y greffer les plugins dont il a besoin. Nous allons voir ici comment ajouter le plugin @11ty/eleventy-img, quasi incontournable pour gérer facilement les images d'un site (une problématique complexe lorsqu'on n'a pas les bons outils).

Remarque : l'installation du package d'Eleventy installe aussi quelques plugins par défaut. Pour ces derniers, les 2 premières étapes qui suivent ne sont pas nécessaires.

Pour ajouter et configurer un plugin, il faut suivre 4 étapes.

Référencer le package du plugin dans le fichier packages.json :

"dependencies": {
	"@11ty/eleventy": "^3.1.2",
	"@11ty/eleventy-img": "^6.0.4"
}

Remarque : pour connaître la dernière version du package, on peut le rechercher dans le référentiel officiel des packages npm. Au moment où j'écris cet article, il s'agit de la version 6.0.4. L'accent circonflexe devant le 6 signifie qu'on pourra récupérer les mises à jour du package automatiquement tant que son numéro de version majeur (6) ne change pas.

Télécharger le plugin en lançant la commande npm install dans le terminal. Cette commande lit le fichier packages.json et télécharge les packages qui y sont référencés dans le dossier node_modules.
Importer le plugin dans le fichier de configuration eleventy.config.js que nous avons créé précédemment :

import { eleventyImageTransformPlugin } from "@11ty/eleventy-img";

On utilise ici la syntaxe ESM pour importer le plugin dans un objet nommé eleventyImageTransformPlugin (le nom est libre). C'est cet objet qui nous permet d'accéder à la configuration du plugin.

Configurer le plugin en ajoutant le code nécessaire dans le fichier de configuration. Voici un exemple commenté de configuration pour notre plugin de gestion d'images :

// Import functions of external libraries
import { eleventyImageTransformPlugin } from "@11ty/eleventy-img";
import path from "node:path";

export default async function (eleventyConfig) {
	// --- ADD PLUGINS and configure it ---

	// Config for the @11ty/eleventy-img plugin
	eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
		// Output images format
		formats: ["avif"],
		// Preserves original image widths and does not create other sizes
		widths: ["auto"],
		// Output files naming
		filenameFormat: function (id, src, width, format, options) {
			// extracts the file name, without extension, from its full path
			const name = path.basename(src, path.extname(src));
			return `${name}.${format}`;
		},
		// Lazy loading of images
		htmlOptions: {
			imgAttributes: {
				loading: "lazy",
				decoding: "async",
			}
		},
		// Options for the Sharp library used by the plugin to encode images in AVIF format
		sharpOptions: {
			animated: true,
		},
		sharpAvifOptions: {
			quality: 60,
			effort: 6,
			chromaSubsampling: "4:2:0",
			bitdepth: 8
		},      
	});
}

Remarque : beaucoup de plugins nécessitent une configuration bien plus simple et concise que celle-ci.

La configuration ci-dessus génère automatiquement des images au format AVIF à partir de fichiers sources au format PNG ou JPG. AVIF est un format moderne largement pris en charge par les navigateurs récents ; il permet de réduire sensiblement le poids des images, ce qui améliore les temps de chargement des pages, l'expérience utilisateur et le référencement naturel (SEO).

En complément, le plugin implémente également le chargement différé des images (lazy loading), ce qui permet à l'utilisateur de commencer à lire le contenu sans attendre la fin du téléchargement des images.

Nous pourrions aussi demander au plugin de générer une version de taille réduite de chaque image pour optimiser encore plus leur temps de chargement sur mobile. Mais cela n'a vraiment d'intérêt que pour des images lourdes ou nombreuses. Garder une seule taille d'image simplifie les choses. C'est d'ailleurs le choix que j'ai fait pour mon propre blog.

Par défaut, les images générées ont des noms sous forme de codes alphanumériques. Mais on peut spécifier une nomenclature plus explicite grâce au paramètre filenameFormat. Ici, on récupère simplement le nom de l'image d'origine, et on change son extension en avif.

Conclusion

Cet article t'a permis de voir comment mettre en place un projet Eleventy à partir de zéro, et comment ajouter des plugins.
Nous avons ainsi préparé le terrain pour la suite, qui consistera à créer notre mini-blog. Je te donne pour cela rendez-vous dans le prochain article, dans lequel tu verras notamment comment créer des templates de pages, organiser les fichiers du projet et compléter sa configuration.

Dis-moi en commentaire si cet article t'a aidé et si tu as des questions.