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 contrôlez le pipeline de construction. Une fois que vous le personnalisez, Silex arrête d'écraser votre configuration.

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
Build awesome traite les fichiers — en appliquant les plugins, en optimisant les assets
Le résultat est déployé sur GitLab Pages

Le .gitlab-ci.yml par défaut ressemble à ceci :

# silexOverwrite: true
image: node:20
pages:
  stage: deploy
  environment: production
  script:
    - npx @11ty/eleventy@v3.0.0-alpha.20 --input=public --output=_site
    - mkdir -p public/css public/assets && cp -R public/css public/assets _site/
    - rm -rf public && mv _site public
    - echo "The site will be deployed to $CI_PAGES_URL"
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_TAG'

Le flag silexOverwrite¶

La première ligne — # silexOverwrite: true — contrôle si Silex écrase ce fichier à chaque publication.

true (par défaut) : Silex remplace le fichier à chaque publication. Bien quand vous n'avez pas besoin de personnalisation.
false : Silex laisse votre fichier tranquille. Requis lors de l'ajout de plugins.

Changez-le en false avant de personnaliser quoi que ce soit, sinon vos modifications seront perdues à la prochaine publication.

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 .gitlab-ci.yml), 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 .gitlab-ci.yml¶

Définissez silexOverwrite sur false et ajoutez npm i avant la commande de construction :

# silexOverwrite: false
image: node:20
pages:
  stage: deploy
  environment: production
  script:
    - npm i
    - npx @11ty/eleventy@v3.0.0-alpha.20 --input=public --output=_site
    - mkdir -p public/css public/assets && cp -R public/css public/assets _site/
    - rm -rf public && mv _site public
    - echo "The site will be deployed to $CI_PAGES_URL"
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_TAG'

Le changement clé : npm i installe les dépendances de votre package.json avant que la construction ne s'exécute.

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¶

Oublier de définir silexOverwrite sur false. Vos personnalisations sont écrasées à la prochaine publication.
Oublier npm i dans le script CI. 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é le fichier CI, publiez et vérifiez le pipeline dans GitLab (CI/CD → Pipelines) pour voir s'il réussit.

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
Configuration CI GitLab — personnalisation avancée du CI
Pipeline de publication — guide développeur pour la configuration de build awesome

Quiz¶

Q1 : Vous avez personnalisé .gitlab-ci.yml pour ajouter un plugin, mais après la publication il est revenu aux valeurs par défaut. Que s'est-il passé ?

A) Le plugin n'était pas compatible
B) silexOverwrite était encore défini sur true
C) Vous avez oublié d'exécuter npm i

Réponse

B) silexOverwrite était encore défini sur true — Silex écrase le fichier CI à chaque publication lorsque ce flag est vrai. Définissez-le sur false avant de personnaliser.

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. Le script CI exécute npm i pour installer 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