Plugins build awesome¶

Build awesome (propulsé par Eleventy) s'exécute au moment de la construction lorsque vous publiez votre site. Les plugins étendent les capacités de la construction — optimiser les images, générer des sitemaps, ajouter la recherche, et plus encore.

Deux choses à retenir :

Les plugins s'exécutent pendant la construction, pas dans l'éditeur. Vous ne verrez pas leurs effets avant de publier.
Vous personnalisez la construction dans build.json. Ce fichier à la racine de votre dépôt est à vous — Silex ne l'écrase jamais. Le fichier CI (.gitlab-ci.yml) et le script de build (build.sh) sont générés par Silex ; ne les éditez pas.

Comment fonctionne la construction¶

Lorsque vous cliquez sur Publier, voici ce qui se passe :

Silex génère les fichiers de votre site (HTML, CSS, assets)
Les fichiers sont commités dans votre dépôt GitLab
Le fichier .gitlab-ci.yml déclenche un pipeline CI/CD, qui exécute sh build.sh
build.sh exécute les étapes listées dans votre build.json — la construction build awesome (propulsée par Eleventy) plus vos commandes personnalisées, en appliquant les plugins et en optimisant les assets
Le résultat (le dossier _site/) est déployé sur GitLab Pages

Le fichier build.json¶

build.json à la racine de votre dépôt liste les étapes de construction dans l'ordre. Le fichier par défaut, créé par Silex à la première publication, contient juste la construction standard :

[
  { "type": "build" }
]

{ "type": "build" } — la construction Silex standard (build awesome compile public/ vers _site/). Elle suit automatiquement les mises à jour de Silex.
{ "type": "sh", "value": "<commande shell>" } — n'importe quelle commande shell, avant ou après la construction.

Silex n'écrase jamais ce fichier : vos personnalisations survivent à chaque publication. build.sh est régénéré depuis build.json à chaque publication — c'est pourquoi vous éditez build.json, jamais build.sh ni .gitlab-ci.yml.

Migrer depuis l'ancien système

Avant build.json, on personnalisait la construction en éditant .gitlab-ci.yml et en passant sa première ligne à # silexOverwrite: false. Ces fichiers fonctionnent toujours — Silex n'y touche jamais. Pour migrer : mettez vos commandes personnalisées dans un nouveau build.json, repassez la première ligne de .gitlab-ci.yml à # silexOverwrite: true, et publiez. Voir Personnaliser le build.

Ajouter un plugin : étape par étape¶

Voyons comment ajouter un plugin en utilisant l'optimisation d'images comme exemple.

Étape 1 : Créer un package.json¶

Dans votre dépôt GitLab (à la racine, à côté de build.json), créez un package.json :

{
  "dependencies": {
    "@11ty/eleventy-img": "^1.0.0"
  }
}

Étape 2 : Créer un eleventy.config.js¶

Au même niveau, créez eleventy.config.js :

const Image = require("@11ty/eleventy-img");

module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("image", async function (src, alt, widths = [300, 600], sizes = "100vh") {
    let metadata = await Image(src, {
      widths,
      formats: ["avif", "jpeg"],
    });

    let imageAttributes = {
      alt,
      sizes,
      loading: "lazy",
      decoding: "async",
    };

    return Image.generateHTML(metadata, imageAttributes);
  });
};

Cela génère des versions avif et jpeg de vos images aux largeurs de 300px et 600px.

Étape 3 : Mettre à jour build.json¶

Ajoutez une étape npm i avant l'étape de construction dans build.json (créez le fichier à la racine de votre dépôt s'il n'existe pas encore) :

[
  { "type": "sh", "value": "npm i" },
  { "type": "build" }
]

Le changement clé : npm i installe les dépendances de votre package.json avant que la construction ne s'exécute. Ne touchez ni à .gitlab-ci.yml ni à build.sh — Silex les génère.

Optimisation d'images avec @11ty/eleventy-img¶

C'est le plugin le plus utile pour la plupart des sites. Il transforme vos images au moment de la construction pour servir le fichier le plus petit possible à chaque visiteur.

Ce qu'il fait¶

Génère plusieurs formats : avif, webp, jpeg, png, svg, gif
Génère plusieurs tailles à partir d'une seule image source
Ne redimensionne jamais au-delà des dimensions originales
Ajoute les attributs width et height appropriés pour réduire le décalage de mise en page
Récupère et met en cache les images distantes localement

L'approche par transformation HTML (recommandée)¶

Au lieu d'utiliser des shortcodes, vous pouvez laisser le plugin traiter automatiquement toutes les balises <img> :

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

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    formats: ["avif", "webp", "jpeg"],
    widths: ["auto"],
    htmlOptions: {
      imgAttributes: {
        loading: "lazy",
        decoding: "async",
      },
    },
  });
};

C'est l'approche la plus simple pour les sites Silex — chaque image que vous ajoutez dans l'éditeur est optimisée automatiquement pendant la construction.

Surcharges par image¶

Vous pouvez contrôler l'optimisation par image en utilisant des attributs HTML (dans les Element settings (icône engrenage)) :

eleventy:widths="200,600" — générer des largeurs spécifiques
eleventy:formats="webp" — utiliser uniquement des formats spécifiques
eleventy:ignore — ignorer cette image entièrement

Conseils de performance pour la construction¶

L'optimisation d'images ajoute du temps de construction. Pour garder les constructions rapides :

Limitez les formats. avif produit les fichiers les plus petits mais est le plus lent à générer. Commencez avec ["webp", "jpeg"] et ajoutez avif seulement si vous en avez besoin.
Utilisez "auto" pour les largeurs sauf si vous savez que vous avez besoin de tailles spécifiques.
Mettez en cache les images distantes. Si vos images proviennent d'un CMS, préservez le dossier .cache entre les constructions pour éviter de les re-télécharger.

Autres plugins utiles¶

Recherche¶

Ajoute la recherche en texte intégral à votre site publié. Les utilisateurs peuvent chercher dans toutes les pages sans serveur.

Sitemap¶

Génère un sitemap XML (sitemap.xml) que les moteurs de recherche utilisent pour découvrir vos pages. Essentiel pour le SEO.

Pagination / Saut de page¶

Divise le contenu long sur plusieurs pages physiques avec une navigation précédent/suivant. Différent des pages de collection, qui génèrent une page par élément de données.

RSS¶

Génère un flux RSS pour que les visiteurs puissent s'abonner à votre contenu. Utile pour les blogs.

eleventy-plugin-concat¶

Un plugin Silex Labs qui concatène plusieurs fichiers CSS et JavaScript en fichiers uniques, réduisant les requêtes HTTP.

Erreurs courantes¶

Éditer .gitlab-ci.yml ou build.sh au lieu de build.json. Ces fichiers sont générés par Silex et vos modifications sont écrasées à la prochaine publication. Seul build.json est à vous.
Oublier l'étape npm i dans build.json. Sans cela, les dépendances de votre package.json ne sont pas installées et la construction n'utilise aucun plugin.
Ajouter trop de formats d'image. Chaque format multiplié par chaque largeur multiplié par chaque image s'accumule. Commencez petit.
Ne pas tester la construction. Après avoir modifié build.json, publiez et vérifiez le pipeline dans GitLab (CI/CD → Pipelines) pour voir s'il réussit — ou lancez sh build.sh en local dans un clone de votre dépôt.

En savoir plus¶

Répertoire des plugins build awesome — parcourir les plugins disponibles
Documentation @11ty/eleventy-img — référence complète du plugin d'images
Personnaliser le build — la référence build.json, le test en local, la migration depuis l'ancien système
Pipeline de publication — guide développeur pour la configuration de build awesome

Quiz¶

Q1 : Vous avez ajouté votre commande personnalisée dans build.sh, mais après la publication elle avait disparu. Que s'est-il passé ?

A) La commande n'était pas compatible
B) build.sh est généré par Silex — les personnalisations vont dans build.json
C) Vous avez oublié d'exécuter npm i

Réponse

B) build.sh est généré par Silex — il est régénéré depuis build.json à chaque publication, tout comme le fichier CI. Mettez vos étapes personnalisées dans build.json : Silex n'écrase jamais ce fichier.

Q2 : Vous souhaitez que toutes les images de votre site soient optimisées automatiquement sans changer votre design Silex. Quelle approche devriez-vous utiliser ?

A) L'approche par shortcode — ajouter des shortcodes à chaque image
B) L'approche par transformation HTML — elle traite automatiquement toutes les balises img
C) Optimiser manuellement les images avant de les télécharger

Réponse

B) L'approche par transformation HTML — elle traite automatiquement chaque balise <img> dans la sortie de construction. Aucun changement nécessaire dans l'éditeur.

Q3 : Votre construction est lente. Vous générez avif, webp, jpeg et png pour 5 largeurs différentes. Que devriez-vous essayer en premier ?

A) Réduire le nombre de formats — supprimer avif et png
B) Ajouter plus de minutes de construction à GitLab
C) Utiliser des images sources plus petites

Réponse

A) Réduire le nombre de formats — avif est le plus lent à générer. Commencez avec webp + jpeg et n'ajoutez avif que si vous avez besoin de la compression supplémentaire.

Q4 : Quel fichier devez-vous créer pour ajouter des dépendances de plugins ?

A) plugins.json
B) package.json
C) .eleventy.js

Réponse

B) package.json — c'est le fichier standard de dépendances Node.js. Une étape npm i dans build.json installe les packages qui y sont listés.

Q5 : Quelle est la différence entre le plugin Saut de page et les pages de collection ?

A) Aucune différence, ils font la même chose
B) Saut de page divise un design sur plusieurs pages ; les pages de collection génèrent une page par élément de données
C) Les pages de collection sont pour les blogs, Saut de page est pour le e-commerce

Réponse

B) Saut de page divise un design sur plusieurs pages ; les pages de collection génèrent une page par élément de données — ils servent des objectifs différents. Saut de page est pour le contenu long, les pages de collection sont pour les données dynamiques.

Éditer cette page sur GitLab