11ty: Cómo usar el plugin de imágenes para generar imágenes responsivas en CSS

Quería usar el plugin de Eleventy para procesar una imagen y establecerla como fondo de un div.

Mi enfoque inicial involucró usar el siguiente shortcode de Eleventy y CSS:

{% image "bg.png", "photo", [300, 600], "(min-width: 30em) 50vw, 100vw" %}

.background-container {
    background-image: url('/public/bg.png');
}

Logré que funcionara colocando la imagen y el CSS en un directorio público addPassthroughCopy, pero este enfoque no permitía la conversión automática de mis imágenes. Buscaba una solución más eficiente.

Procesamiento automático con el plugin de imágenes de Eleventy

"¿Hay alguna manera de que esta imagen sea procesada por el plugin de Eleventy y establecida como fondo de un div? La única forma (complicada) que logré hacerlo es poniendo la imagen y el CSS en un directorio público addPassthroughCopy."

<style>
.background-container {
    background-image: url('/public/bg.png');
}
</style>

<div class="background-container">...</div>

Aankhen & Darth_Mall del foro de ayuda de discord me orientaron en la dirección correcta.

A través de nuestra conversación, exploramos cómo usar el plugin eleventy-img de Eleventy para generar dinámicamente imágenes de fondo responsivas. Me proporcionaron un enfoque detallado para lograr esto, que involucra:

1. Configurar Eleventy: Configurar Eleventy para manejar el procesamiento de imágenes e incluir CSS directamente en las plantillas.
2. Crear Plantillas Nunjucks: Definir plantillas para generar e incluir imágenes responsivas.
3. Manejar Errores: Depurar y asegurar que las rutas y configuraciones estuvieran correctamente establecidas.

Los intentos iniciales incluyeron varios ajustes y correcciones para asegurar que la configuración funcionara correctamente.

Después de varias iteraciones con chatGPT, la solución final involucró:

1. Configurar eleventy.config.js: Incluir configuraciones para eleventy-img y filtros personalizados de Nunjucks.
2. Crear Plantilla de Fondo (background.njk): Una plantilla Nunjucks para generar CSS responsivo.
3. Crear Página HTML (post.njk): Una plantilla HTML para usar el CSS generado para imágenes de fondo responsivas.

La solución final funcionando fue documentada exhaustivamente y compartida en formato Markdown para asegurar que pudiera ser fácilmente compartida y entendida.

Contenido de la Documentación

Esta documentación explica cómo configurar Eleventy para usar imágenes de fondo responsivas con el plugin eleventy-img. Aprenderás cómo definir plantillas Nunjucks para generar imágenes en diferentes tamaños y formatos, y luego incluirlas en tus páginas con los estilos apropiados.

Prerrequisitos: Se requiere Node 18+ para Eleventy v3 y la sintaxis ESM usada a lo largo de esta guía.

Actualización (2026): Eleventy v3 ahora incluye eleventyImageTransformPlugin, que transforma automáticamente todas las etiquetas <img> en tu salida HTML — no se necesita shortcode. Ve la sección dedicada abajo para detalles. Sin embargo, este plugin no maneja CSS background-image — ahí es donde el enfoque de filtro personalizado en este artículo sigue siendo esencial.

Configurar eleventy.config.js (o eleventy.config.images.js)

Crea o actualiza tu archivo eleventy.config.js para incluir la siguiente configuración:

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

La Alternativa Moderna: eleventyImageTransformPlugin

Comenzando con Eleventy v3, hay una forma más simple de manejar etiquetas <img> estándar — no se requiere shortcode. El eleventyImageTransformPlugin procesa automáticamente todas las imágenes encontradas en tu salida 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",
    },
  });
}

Solo escribe etiquetas <img> regulares en tus plantillas y el plugin se encarga del resto — generando múltiples formatos y tamaños, envolviendo en <picture>, y agregando los atributos correctos.

Limitación importante: este plugin solo procesa etiquetas <img> en la salida HTML. No maneja propiedades CSS background-image. Para fondos CSS responsivos, aún necesitas el filtro personalizado imageCSS descrito arriba — y eso es exactamente lo que hace valiosa esta guía más allá de la documentación oficial.

Creando Plantillas

1. Plantilla de Fondo (background.njk)

Crea un archivo _includes/layouts/background.njk con el siguiente contenido:

{% set sizes = [300, 600, 1200] %}
{% set formats = ["jpeg"] %}
{% set imagePath = imagebg %}

{{ imagePath | imageCSS(sizes, formats) | safe }}

2. Página HTML (post.njk)

Crea un archivo post.njk con el siguiente contenido:

---
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>SÍ</p>
        <input type="text" placeholder="Haz tu pregunta aquí" />
        <button>Enviar</button>
    </div>
</body>
</html>

Conclusión

Siguiendo estos pasos, habrás configurado Eleventy para usar imágenes de fondo responsivas.

La configuración te permite generar diferentes tamaños y formatos de imágenes e incluirlas en el CSS con media queries para una visualización óptima en varios dispositivos.

Verificación

1. Verificar Rutas y Permisos:

   • Asegúrate de que la carpeta public/img exista y los permisos estén configurados correctamente.
   • Verifica que las imágenes sean realmente copiadas al directorio de salida _site/img.

2. Depuración y Logs:

   • Usa los logs generados por eleventy.config.js para verificar que las imágenes se generen correctamente y las rutas sean precisas.
   • En caso de problemas, usa mensajes de error y logs para identificar y corregir errores de configuración o acceso a rutas.

Lo Que Aprendí de Esta Experiencia

De esta experiencia, aprendí la importancia de aprovechar la flexibilidad y plugins de Eleventy para crear soluciones más eficientes y optimizadas. Inicialmente, enfrenté el desafío de procesar y convertir imágenes automáticamente mientras las integraba como imágenes de fondo responsivas en mi proyecto.

El viaje involucró entender e implementar el plugin eleventy-img, configurar filtros personalizados de Nunjucks, y escribir plantillas que generan dinámicamente el CSS necesario para diferentes tamaños de viewport.

Las lecciones clave de este proceso incluyen:

• Configurar Plugins de Eleventy: Obtener un entendimiento más profundo de cómo configurar plugins como eleventy-img para el procesamiento automático de imágenes.
• Creación de Plantillas: Aprender cómo crear plantillas Nunjucks que pueden generar dinámicamente contenido CSS y HTML.
• Diseño Responsivo: Implementar técnicas de diseño responsivo usando media queries y CSS generado dinámicamente para diferentes tamaños de imagen.
• Depuración y Manejo de Errores: Manejar errores de configuración y sintaxis efectivamente para asegurar el funcionamiento fluido del proyecto.

Esta experiencia también reforzó el valor del apoyo comunitario (gracias Aankhen & Darth_Mall) y la documentación. Interactuar con la comunidad de Eleventy y referirse a varios ejemplos y documentación proporcionó insights cruciales y orientación a lo largo del proceso.

Unas Palabras sobre Eleventy

Eleventy es un generador de sitios estáticos altamente flexible y poderoso que proporciona un gran equilibrio entre simplicidad y funcionalidad. Su capacidad de trabajar sin problemas con varios motores de plantillas como Nunjucks, y su extenso ecosistema de plugins, lo convierten en una excelente opción para desarrolladores que buscan crear sitios web rápidos, eficientes y altamente personalizables.

El enfoque minimalista de Eleventy permite a los desarrolladores construir proyectos con configuración mínima mientras aún ofrece el poder para manejar requisitos complejos. Ya seas un desarrollador experimentado o recién comenzando, el flujo de trabajo intuitivo y directo de Eleventy lo hace un placer para trabajar.

En general, esta experiencia ha sido tanto educativa como gratificante, mostrando el verdadero potencial de Eleventy en la creación de soluciones web dinámicas y responsivas.

PD: Sin ChatGPT, nunca lo habría logrado. Gracias a esta experiencia, incluso alguien que no es desarrollador como yo ahora puede lograr tareas complejas y mejorar mis habilidades.

---

Descubre cómo transformar imágenes de fondo en Eleventy con un enfoque profesional, directo desde la trinchera del desarrollo web.

→ Únete a la newsletter de desarrollo