11ty : comment utiliser le plugin image pour générer des images responsives en CSS
Transformer une image en arrière-plan responsive avec Eleventy ? Voici comment j'ai dompté le plugin eleventy-img pour générer du CSS automatiquement.
Je voulais utiliser le plugin Eleventy pour traiter une image et l'utiliser comme arrière-plan d'une div.
Ma première approche impliquait l'utilisation du shortcode Eleventy suivant et du CSS :
{% image "bg.png", "photo", [300, 600], "(min-width: 30em) 50vw, 100vw" %}
.background-container {
background-image: url('/public/bg.png');
}J'ai réussi à faire fonctionner cette approche en plaçant l'image et le CSS dans un répertoire public addPassthroughCopy, mais cette méthode ne permettait pas la conversion automatique de mes images. Je cherchais une solution plus élégante.
Traitement automatique avec le plugin Eleventy image
« Y a-t-il un moyen de faire traiter cette image par le plugin Eleventy et de l'utiliser comme arrière-plan d'une div ? La seule façon (compliquée) que j'ai trouvée est de mettre l'image et le CSS dans un répertoire public addPassthroughCopy. »
<style>
.background-container {
background-image: url('/public/bg.png');
}
</style>
<div class="background-container">...</div>Aankhen & Darth_Mall du forum d'aide Discord m'ont orienté dans la bonne direction.
À travers notre conversation, nous avons exploré comment utiliser le plugin eleventy-img d'Eleventy pour générer dynamiquement des images d'arrière-plan responsives. On m'a fourni une approche détaillée pour y parvenir, impliquant :
- Configuration d'Eleventy : Paramétrer Eleventy pour gérer le traitement d'images et inclure le CSS directement dans les templates.
- Création de templates Nunjucks : Définir des templates pour générer et inclure des images responsives.
- Gestion des erreurs : Déboguer et s'assurer que les chemins et configurations étaient correctement définis.
Les premières tentatives ont nécessité plusieurs ajustements et corrections pour s'assurer que la configuration fonctionnait correctement.
Après plusieurs itérations avec chatGPT, la solution finale impliquait :
- Configuration d'eleventy.config.js : Inclure les configurations pour eleventy-img et des filtres Nunjucks personnalisés.
- Création du template d'arrière-plan (background.njk) : Un template Nunjucks pour générer du CSS responsive.
- Création de la page HTML (post.njk) : Un template HTML pour utiliser le CSS généré pour les images d'arrière-plan responsives.
La solution finale fonctionnelle a été documentée minutieusement et partagée au format Markdown pour qu'elle puisse être facilement partagée et comprise.
Contenu de la documentation
Cette documentation explique comment configurer Eleventy pour utiliser des images d'arrière-plan responsives avec le plugin eleventy-img. Vous apprendrez comment définir des templates Nunjucks pour générer des images en différentes tailles et formats, puis les inclure dans vos pages avec les styles appropriés.
Prérequis : Node 18+ est requis pour Eleventy v3 et la syntaxe ESM utilisée dans ce guide.
Mise à jour (2026) : Eleventy v3 est maintenant livré avec
eleventyImageTransformPlugin, qui transforme automatiquement toutes les balises<img>dans votre sortie HTML — aucun shortcode nécessaire. Voir la section dédiée ci-dessous pour plus de détails. Cependant, ce plugin ne gère pas lesbackground-imageCSS — c'est là que l'approche par filtre personnalisé de cet article reste essentielle.
Configurer eleventy.config.js (ou eleventy.config.images.js)
Créez ou mettez à jour votre fichier eleventy.config.js pour inclure la configuration suivante :
// eleventy.config.js (ESM — Eleventy v3+)
import path from "path";
import eleventyImage from "@11ty/eleventy-img";
function relativeToInputPath(inputPath, relativeFilePath) {
let split = inputPath.split("/");
split.pop();
return path.resolve(split.join(path.sep), relativeFilePath);
}
function isFullUrl(url) {
try {
new URL(url);
return true;
} catch (e) {
return false;
}
}
export default function (eleventyConfig) {
const formats = ["avif", "webp", "auto"];
// Shortcode Eleventy Image
// https://www.11ty.dev/docs/plugins/image/
eleventyConfig.addAsyncShortcode(
"image",
async function imageShortcode(src, alt, widths, sizes) {
const input = isFullUrl(src)
? src
: relativeToInputPath(this.page.inputPath, src);
const metadata = await eleventyImage(input, {
widths: widths || ["auto"],
formats,
outputDir: "./dist/img/",
});
const imageAttributes = {
alt,
sizes,
loading: "lazy",
decoding: "async",
};
return eleventyImage.generateHTML(metadata, imageAttributes);
}
);
// Filtre personnalisé pour générer du CSS avec media queries
// C'est la partie clé — eleventyImageTransformPlugin ne gère PAS les arrière-plans CSS
eleventyConfig.addNunjucksAsyncFilter(
"imageCSS",
async function (src, sizes, formats, callback) {
const input = isFullUrl(src)
? src
: path.resolve(".", src);
const metadata = await eleventyImage(input, {
widths: sizes,
formats: formats,
outputDir: "./dist/img/",
});
let css = sizes
.map((size, index) => {
if (metadata[formats[0]][index]) {
return `@media (min-width: ${size}px) {
.background-container {
background-image: url('${metadata[formats[0]][index].url}');
}
}`;
} else {
console.error(
`Erreur : Aucune métadonnée trouvée pour le format ${formats[0]} et l'index de taille ${index}`
);
return "";
}
})
.join("\n");
callback(null, css);
}
);
}L'alternative moderne : eleventyImageTransformPlugin
À partir d'Eleventy v3, il existe un moyen plus simple de gérer les balises <img> standard — aucun shortcode requis. Le eleventyImageTransformPlugin traite automatiquement toutes les images trouvées dans votre sortie HTML :
// eleventy.config.js
import { eleventyImageTransformPlugin } from "@11ty/eleventy-img";
export default function (eleventyConfig) {
eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
extensions: "html",
formats: ["avif", "webp", "auto"],
widths: ["auto"],
defaultAttributes: {
loading: "lazy",
decoding: "async",
},
});
}Il suffit d'écrire des balises <img> classiques dans vos templates et le plugin s'occupe du reste — génération de multiples formats et tailles, encapsulation dans <picture>, et ajout des bons attributs.
Limitation importante : ce plugin ne traite que les balises <img> dans la sortie HTML. Il ne gère pas les propriétés CSS background-image. Pour les arrière-plans CSS responsives, vous avez toujours besoin du filtre personnalisé imageCSS décrit ci-dessus — et c'est exactement ce qui rend ce guide précieux au-delà de la documentation officielle.
Création des templates
1. Template d'arrière-plan (background.njk)
Créez un fichier _includes/layouts/background.njk avec le contenu suivant :
{% set sizes = [300, 600, 1200] %}
{% set formats = ["jpeg"] %}
{% set imagePath = imagebg %}
{{ imagePath | imageCSS(sizes, formats) | safe }}
2. Page HTML (post.njk)
Créez un fichier post.njk avec le contenu suivant :
---
title: CSS background
description: CSS bg
layout: layouts/post.njk
tags: posts
backgroundImage: "my-bg.png"
---
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title }}</title>
<style>
.background-container {
background-size: cover;
background-position: center;
width: 100%;
height: 100vh;
display: flex;
flex-direction: column;
justify-content: center;
align-items: center;
color: white;
font-size: 2em;
}
.background-container p,
.background-container input,
.background-container button {
margin: 10px;
}
.background-container input {
padding: 10px;
font-size: 1em;
}
.background-container button {
padding: 10px 20px;
font-size: 1em;
cursor: pointer;
}
{% set imagebg = backgroundImage %}
{% include "layouts/background.njk" %}
</style>
</head>
<body>
<div class="background-container">
<p>OUI</p>
<input type="text" placeholder="Posez votre question ici" />
<button>Envoyer</button>
</div>
</body>
</html>Conclusion
En suivant ces étapes, vous aurez configuré Eleventy pour utiliser des images d'arrière-plan responsives.
La configuration permet de générer différentes tailles et formats d'images et de les inclure dans le CSS avec des media queries pour un affichage optimal sur divers appareils.
Vérification
-
Vérifier les chemins et permissions :
- Assurez-vous que le dossier public/img existe et que les permissions sont correctement définies.
- Vérifiez que les images sont effectivement copiées dans le répertoire de sortie
_site/img.
-
Débogage et logs :
- Utilisez les logs générés par eleventy.config.js pour vérifier que les images sont générées correctement et que les chemins sont précis.
- En cas de problèmes, utilisez les messages d'erreur et les logs pour identifier et corriger les erreurs de configuration ou d'accès aux chemins.
Ce que j'ai appris de cette expérience
De cette expérience, j'ai appris l'importance de tirer parti de la flexibilité d'Eleventy et de ses plugins pour créer des solutions plus efficaces et rationalisées. Au départ, j'étais confronté au défi de traiter et convertir automatiquement les images tout en les intégrant comme images d'arrière-plan responsives dans mon projet.
Le parcours a impliqué la compréhension et l'implémentation du plugin eleventy-img, la configuration de filtres Nunjucks personnalisés, et l'écriture de templates qui génèrent dynamiquement le CSS nécessaire pour différentes tailles d'écran.
Les points clés à retenir de ce processus incluent :
- Configuration des plugins Eleventy : Acquérir une compréhension plus approfondie de la façon de configurer et paramétrer des plugins comme eleventy-img pour le traitement automatique d'images.
- Création de templates : Apprendre à créer des templates Nunjucks qui peuvent générer dynamiquement du contenu CSS et HTML.
- Design responsive : Implémenter des techniques de design responsive en utilisant des media queries et du CSS généré dynamiquement pour différentes tailles d'images.
- Débogage et gestion d'erreurs : Gérer efficacement les erreurs de configuration et de syntaxe pour assurer le bon fonctionnement du projet.
Cette expérience a également renforcé la valeur du support communautaire (merci Aankhen & Darth_Mall) et de la documentation. Échanger avec la communauté Eleventy et consulter divers exemples et documentations a fourni des insights cruciaux et des conseils tout au long du processus.
Un mot sur Eleventy
Eleventy est un générateur de sites statiques très flexible et puissant qui offre un excellent équilibre entre simplicité et fonctionnalité. Sa capacité à fonctionner parfaitement avec divers moteurs de templates comme Nunjucks, et son écosystème de plugins étendu, en font un excellent choix pour les développeurs cherchant à créer des sites web rapides, efficaces et hautement personnalisables.
L'approche minimaliste d'Eleventy permet aux développeurs de construire des projets avec une configuration minimale tout en offrant la puissance nécessaire pour gérer des exigences complexes. Que vous soyez un développeur expérimenté ou débutant, le workflow intuitif et direct d'Eleventy en fait un plaisir à utiliser.
Dans l'ensemble, cette expérience a été à la fois éducative et enrichissante, démontrant le véritable potentiel d'Eleventy pour créer des solutions web dynamiques et responsives.
PS : Sans ChatGPT, je n'aurais jamais réussi. Grâce à cette expérience, même un non-développeur comme moi peut maintenant accomplir des tâches complexes et améliorer ses compétences.
Découvrez comment transformer vos images d'arrière-plan en CSS responsive avec Eleventy, directement depuis la production d'un développeur senior qui construit des outils avec AI.