11ty: So nutzen Sie das Image-Plugin für responsive Bilder in CSS
Ich wollte das Eleventy-Plugin verwenden, um ein Bild zu verarbeiten und als div-Hintergrund zu setzen.
Mein erster Ansatz bestand darin, den folgenden Eleventy-Shortcode und CSS zu verwenden:
{% image "bg.png", "photo", [300, 600], "(min-width: 30em) 50vw, 100vw" %}
.background-container {
background-image: url('/public/bg.png');
}Ich konnte es zum Laufen bringen, indem ich das Bild und CSS in ein öffentliches addPassthroughCopy-Verzeichnis legte, aber dieser Ansatz ermöglichte keine automatische Konvertierung meiner Bilder. Ich suchte nach einer eleganteren Lösung.
Automatische Bildverarbeitung mit dem Eleventy-Plugin
"Gibt es eine Möglichkeit, dieses Bild vom Eleventy-Plugin verarbeiten zu lassen und als div-Hintergrund zu setzen? Der einzige (komplizierte) Weg, den ich hinbekommen habe, war, das Bild und das CSS in ein öffentliches addPassthroughCopy-Verzeichnis zu legen."
<style>
.background-container {
background-image: url('/public/bg.png');
}
</style>
<div class="background-container">...</div>Aankhen & Darth_Mall aus dem Discord-Hilfeforum haben mich in die richtige Richtung geschubst.
In unserem Gespräch haben wir erforscht, wie man Eleventys eleventy-img Plugin nutzt, um dynamisch responsive Hintergrundbilder zu generieren. Ich bekam einen detaillierten Ansatz gezeigt, der folgende Schritte umfasste:
- Eleventy konfigurieren: Eleventy so einrichten, dass es Bildverarbeitung übernimmt und CSS direkt in die Templates einbindet.
- Nunjucks-Templates erstellen: Templates definieren, um responsive Bilder zu generieren und einzubinden.
- Fehlerbehandlung: Debugging und sicherstellen, dass Pfade und Konfigurationen korrekt gesetzt sind.
Die ersten Versuche beinhalteten mehrere Anpassungen und Korrekturen, um sicherzustellen, dass die Konfiguration richtig funktionierte.
Nach mehreren Iterationen mit ChatGPT umfasste die finale Lösung:
- eleventy.config.js einrichten: Konfigurationen für eleventy-img und benutzerdefinierte Nunjucks-Filter einbinden.
- Hintergrund-Template erstellen (background.njk): Ein Nunjucks-Template zur Generierung von responsivem CSS.
- HTML-Seite erstellen (post.njk): Ein HTML-Template zur Verwendung des generierten CSS für responsive Hintergrundbilder.
Die finale funktionierende Lösung wurde gründlich dokumentiert und im Markdown-Format geteilt, um sicherzustellen, dass sie leicht geteilt und verstanden werden kann.
Dokumentationsinhalt
Diese Dokumentation erklärt, wie man Eleventy konfiguriert, um responsive Hintergrundbilder mit dem eleventy-img-Plugin zu verwenden. Du lernst, wie man Nunjucks-Templates definiert, um Bilder in verschiedenen Größen und Formaten zu generieren und sie dann mit den entsprechenden Styles in deine Seiten einzubinden.
Voraussetzungen: Node 18+ ist für Eleventy v3 und die in diesem Guide verwendete ESM-Syntax erforderlich.
Update (2026): Eleventy v3 wird jetzt mit
eleventyImageTransformPluginausgeliefert, das automatisch alle<img>-Tags in deiner HTML-Ausgabe transformiert — kein Shortcode nötig. Siehe den entsprechenden Abschnitt unten für Details. Allerdings behandelt dieses Plugin keine CSSbackground-image— hier bleibt der benutzerdefinierte Filter-Ansatz aus diesem Artikel unverzichtbar.
eleventy.config.js konfigurieren (oder eleventy.config.images.js)
Erstelle oder aktualisiere deine eleventy.config.js-Datei mit der folgenden Konfiguration:
// 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"];
// Eleventy Image shortcode
// 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);
}
);
// Custom filter to generate CSS with media queries
// This is the key part — eleventyImageTransformPlugin does NOT handle CSS backgrounds
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(
`Error: No metadata found for format ${formats[0]} and size index ${index}`
);
return "";
}
})
.join("\n");
callback(null, css);
}
);
}Die moderne Alternative: eleventyImageTransformPlugin
Ab Eleventy v3 gibt es einen einfacheren Weg, um Standard-<img>-Tags zu handhaben — kein Shortcode erforderlich. Das eleventyImageTransformPlugin verarbeitet automatisch alle Bilder, die in deiner HTML-Ausgabe gefunden werden:
// 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",
},
});
}Schreibe einfach normale <img>-Tags in deine Templates und das Plugin erledigt den Rest — generiert mehrere Formate und Größen, umhüllt sie mit <picture> und fügt die richtigen Attribute hinzu.
Wichtige Einschränkung: Dieses Plugin verarbeitet nur <img>-Tags in der HTML-Ausgabe. Es behandelt keine CSS background-image-Eigenschaften. Für responsive CSS-Hintergründe benötigst du immer noch den benutzerdefinierten imageCSS-Filter, der oben beschrieben wird — und genau das macht diesen Guide wertvoll über die offizielle Dokumentation hinaus.
Templates erstellen
1. Hintergrund-Template (background.njk)
Erstelle eine Datei _includes/layouts/background.njk mit folgendem Inhalt:
{% set sizes = [300, 600, 1200] %}
{% set formats = ["jpeg"] %}
{% set imagePath = imagebg %}
{{ imagePath | imageCSS(sizes, formats) | safe }}
2. HTML-Seite (post.njk)
Erstelle eine Datei post.njk mit folgendem Inhalt:
---
title: CSS background
description: CSS bg
layout: layouts/post.njk
tags: posts
backgroundImage: "my-bg.png"
---
<!DOCTYPE html>
<html lang="en">
<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>YES</p>
<input type="text" placeholder="Ask your question here" />
<button>Submit</button>
</div>
</body>
</html>Fazit
Wenn du diese Schritte befolgst, hast du Eleventy so konfiguriert, dass es responsive Hintergrundbilder verwendet.
Die Konfiguration ermöglicht es dir, verschiedene Größen und Formate von Bildern zu generieren und sie mit Media Queries in das CSS einzubinden für optimale Darstellung auf verschiedenen Geräten.
Verifikation
-
Pfade und Berechtigungen prüfen:
- Stelle sicher, dass der public/img-Ordner existiert und die Berechtigungen korrekt gesetzt sind.
- Überprüfe, dass die Bilder tatsächlich in das Ausgabeverzeichnis
_site/imgkopiert werden.
-
Debugging und Logs:
- Verwende die von eleventy.config.js generierten Logs, um zu überprüfen, dass Bilder korrekt generiert werden und Pfade stimmen.
- Bei Problemen nutze Fehlermeldungen und Logs, um Konfigurations- oder Pfadzugriffsfehler zu identifizieren und zu beheben.
Was ich aus dieser Erfahrung gelernt habe
Aus dieser Erfahrung habe ich die Wichtigkeit gelernt, Eleventys Flexibilität und Plugins zu nutzen, um effizientere und elegantere Lösungen zu schaffen. Anfangs stand ich vor der Herausforderung, Bilder automatisch zu verarbeiten und zu konvertieren, während ich sie als responsive Hintergrundbilder in mein Projekt integrierte.
Die Reise beinhaltete das Verstehen und Implementieren des eleventy-img Plugins, das Konfigurieren benutzerdefinierter Nunjucks-Filter und das Schreiben von Templates, die dynamisch das notwendige CSS für verschiedene Viewport-Größen generieren.
Die wichtigsten Erkenntnisse aus diesem Prozess sind:
- Eleventy-Plugins konfigurieren: Ein tieferes Verständnis dafür entwickeln, wie man Plugins wie eleventy-img für automatische Bildverarbeitung einrichtet und konfiguriert.
- Template-Erstellung: Lernen, wie man Nunjucks-Templates erstellt, die dynamisch CSS- und HTML-Inhalte generieren können.
- Responsive Design: Responsive Design-Techniken mit Media Queries und dynamisch generiertem CSS für verschiedene Bildgrößen implementieren.
- Debugging und Fehlerbehandlung: Konfigurations- und Syntaxfehler effektiv handhaben, um das reibungslose Funktionieren des Projekts sicherzustellen.
Diese Erfahrung hat auch den Wert von Community-Support (danke Aankhen & Darth_Mall) und Dokumentation verstärkt. Der Austausch mit der Eleventy-Community und das Heranziehen verschiedener Beispiele und Dokumentationen lieferte entscheidende Einsichten und Orientierung während des gesamten Prozesses.
Ein Wort zu Eleventy
Eleventy ist ein hochflexibler und mächtiger Static Site Generator, der eine großartige Balance zwischen Einfachheit und Funktionalität bietet. Seine Fähigkeit, nahtlos mit verschiedenen Templating-Engines wie Nunjucks zu arbeiten, und sein umfangreiches Plugin-Ökosystem machen es zu einer exzellenten Wahl für Entwickler, die schnelle, effiziente und hochgradig anpassbare Websites erstellen möchten.
Eleventys minimalistischer Ansatz ermöglicht es Entwicklern, Projekte mit minimaler Konfiguration zu erstellen und bietet dennoch die Power, komplexe Anforderungen zu bewältigen. Egal ob du ein erfahrener Entwickler bist oder gerade erst anfängst, Eleventys intuitiver und unkomplizierter Workflow macht es zu einer Freude, damit zu arbeiten.
Insgesamt war diese Erfahrung sowohl lehrreich als auch bereichernd und zeigt das wahre Potenzial von Eleventy beim Erstellen dynamischer und responsiver Web-Lösungen.
PS: Ohne ChatGPT hätte ich das nie geschafft. Dank dieser Erfahrung kann sogar ein Nicht-Entwickler wie ich jetzt komplexe Aufgaben bewältigen und meine Fähigkeiten verbessern.
Wöchentlich teile ich Produktions-Insights von Entwicklern, die echte KI-Tools bauen — nicht nur Tutorials, sondern knallharte Praxis-Learnings.