Configuration de build awesome¶

Comment le build se déroule quand vous publiez, et ce que vous pouvez y ajouter : des plugins Eleventy et des shortcodes.

Comment fonctionne le build¶

Silex publie votre site web dans un dépôt Git, puis la CI de la plateforme d'hébergement construit le site. Silex écrit les fichiers du site dans le dossier public/ du dépôt, et génère le script de build. build awesome (le nouveau nom d'Eleventy, version épinglée 3.1.6) transforme public/ en _site/, et c'est _site/ qui est déployé.

L'étape de build lance ces commandes :

npx @11ty/eleventy@3.1.6 --input=public --output=_site
cp -R public/css public/assets _site/ 2>/dev/null || true

Il n'y a pas de fichier de configuration Eleventy dans cette commande. Eleventy est lancé avec des options en ligne de commande, et il cherche un fichier de configuration à la racine du dépôt (voir Ajouter un plugin ci-dessous).

Silex ajoute un front matter en haut de chaque page, avec ou sans source de données. Il fixe le permalink de la page : index.html est publiée en /index.html, et about.html en /about/index.html. Eleventy rend ensuite chaque page comme un template Liquid. Un texte de vos pages qui ressemble à du Liquid, comme {{ ... }} ou {% ... %}, est lu comme du Liquid.

Sur un site avec une source de données, une page qui utilise des données reçoit aussi un fichier <page>.11tydata.mjs à côté d'elle, qui charge ces données au moment du build.

Le build ne démarre qu'à la publication

Le pipeline CI se lance quand Silex crée un tag nommé _silex_<timestamp>, ce qui arrive à chaque publication. Il se lance aussi sur un pipeline de type trigger, api, web ou schedule. Il ne se lance pas sur un push normal. Si vous modifiez build.json directement sur la forge et que vous poussez, rien n'est construit : publiez depuis Silex. Silex réécrit alors build.sh à partir de votre build.json. Un pipeline lancé à la main depuis l'interface de la plateforme utilise le build.sh de la dernière publication.

Ajouter un plugin¶

Pas besoin d'être développeur pour ajouter un plugin. Il suffit de trois petits fichiers à copier-coller dans le dépôt de votre site sur GitLab, depuis votre navigateur. Cette section explique ce qui se passe, puis donne toutes les étapes pour un plugin : les images optimisées.

Eleventy et le build GitLab, en mots simples¶

Eleventy est l'outil qui fabrique votre site final à partir des fichiers que Silex publie. Silex envoie vos pages, vos styles et vos images sur GitLab. Eleventy les lit et écrit le site final. Eleventy a maintenant un nouveau nom : Build Awesome. Vous voyez les deux noms, dans Silex et sur le site d'Eleventy.

Un plugin Eleventy ajoute une tâche de plus à Eleventy. Par exemple, il rend vos images plus légères pendant qu'il fabrique votre site. Les plugins sont des paquets gratuits, partagés sur npm, la bibliothèque de paquets de JavaScript. Un plugin Eleventy n'est pas un plugin Silex : il tourne dans le build sur GitLab, pas dans l'éditeur Silex. Les plugins Silex sont sur la page Utiliser des plugins.

Le build GitLab est l'endroit où Eleventy tourne. À chaque publication depuis Silex, GitLab lance tout seul les commandes du build, sur ses propres serveurs. C'est ce qu'on appelle un pipeline. Quand le pipeline est terminé, GitLab met le résultat en ligne avec GitLab Pages. Dans votre projet sur GitLab, Build → Pipelines montre l'état de chaque pipeline : en cours, réussi ou en échec.

Pour se former¶

Ces documentations sont en anglais.

Documentation d'Eleventy : ce qu'est Eleventy et comment il fonctionne.
Plugins Eleventy : les plugins officiels et ceux de la communauté.
Get started with GitLab CI/CD : ce qu'est un pipeline, pour débuter.
Tutorial: Create and run your first GitLab CI/CD pipeline : un premier pipeline, pas à pas, pour comprendre les pipelines. Ne modifiez pas le .gitlab-ci.yml de votre site Silex.
CI/CD pipelines : voir vos pipelines, et les jobs qu'ils contiennent.
Web Editor : créer et modifier un fichier de votre dépôt dans votre navigateur. Les étapes ci-dessous l'utilisent.
Web IDE : un autre éditeur dans le navigateur, pour modifier plusieurs fichiers en un seul commit.

Avant de commencer¶

Publiez votre site depuis Silex sur GitLab au moins une fois. La première publication crée le fichier build.json.
Sur GitLab, ouvrez votre projet et sélectionnez Code → Repository. Vous voyez les fichiers de votre site, parmi lesquels le dossier public, build.json, build.sh et .gitlab-ci.yml. Cette liste, c'est la racine du dépôt.

Tous les fichiers de cette section vont à la racine du dépôt, à côté de build.json. Jamais dans le dossier public.

Les libellés de GitLab sont donnés ici en anglais, la langue par défaut de son interface.

Pas à pas : images optimisées¶

Ce plugin crée des versions plus légères des images de votre site, en WebP et dans leur format d'origine. C'est le plugin d'images officiel d'Eleventy, Eleventy Image. Seules les images ajoutées comme éléments image changent. Les images de fond, réglées dans le panneau Style, ne changent pas.

Étape 1. Créer package.json. Ce fichier indique au build quel plugin télécharger.

Sur GitLab, ouvrez votre projet, puis Code → Repository. Restez à la racine, n'ouvrez pas le dossier public.
À côté du nom du dossier, au-dessus de la liste des fichiers, sélectionnez l'icône plus (+), puis New file.
Dans le champ du nom de fichier, tapez package.json.

Copiez ce contenu et collez-le dans l'éditeur :

{
  "type": "module",
  "dependencies": {
    "@11ty/eleventy-img": "^7.1.1"
  }
}

Sélectionnez Commit changes. Écrivez un court Commit message, par exemple Ajout du plugin images. Gardez la branche main. Ne créez pas de nouvelle branche. Puis sélectionnez de nouveau Commit changes.

Étape 2. Créer eleventy.config.js. Ce fichier indique à Eleventy d'utiliser le plugin, et comment.

Revenez dans Code → Repository, à la racine.
Sélectionnez l'icône plus (+), puis New file.
Dans le champ du nom de fichier, tapez eleventy.config.js.

Copiez ce contenu et collez-le dans l'éditeur :

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

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    formats: ["webp", "auto"],
    widths: [600, 1200, "auto"],
    htmlOptions: {
      imgAttributes: {
        sizes: "100vw",
        loading: "lazy",
        decoding: "async",
      },
    },
  })
}

Sélectionnez Commit changes, écrivez un message, gardez la branche main, et sélectionnez de nouveau Commit changes.

Étape 3. Modifier build.json. Ce fichier liste les étapes du build. La nouvelle étape, npm i, télécharge le plugin avant le build.

Dans Code → Repository, sélectionnez build.json.
Sélectionnez Edit, puis Edit single file.

Effacez tout le contenu du fichier. Copiez ce contenu et collez-le :

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

Sélectionnez Commit changes, écrivez un message, gardez la branche main, et sélectionnez de nouveau Commit changes.

Étape 4. Publier depuis Silex. Vos commits sur GitLab ne lancent pas le build. Revenez dans Silex et publiez votre site. À ce moment, Silex réécrit aussi build.sh à partir de votre nouveau build.json. Un pipeline lancé à la main sur GitLab ne le fait pas : publiez depuis Silex. Si Silex affiche une erreur sur build.json, ou une erreur comme is not valid JSON, vérifiez le texte collé à l'étape 3.

Étape 5. Vérifier le pipeline.

Sur GitLab, dans votre projet, sélectionnez Build → Pipelines. Le pipeline le plus récent est en haut.
Attendez que son statut soit Passed. Cette fois, le build prend un peu plus de temps : il télécharge d'abord le plugin.
Si le statut est Failed, sélectionnez le pipeline, puis le job nommé pages. Son log affiche l'erreur, vers la fin. Voir Dépannage plus bas.

Étape 6. Voir le résultat.

Ouvrez votre site. Son adresse se trouve dans Deploy → Pages.
Ouvrez une page avec des images et affichez son code source : faites un clic droit sur la page et choisissez d'afficher le code source.
Chaque image se trouve maintenant dans un élément <picture>, et utilise des fichiers du dossier /img/, comme /img/kCGub5O_3U-600.webp.

Ce que le plugin fait de vos images¶

Ce que fait le build d'une image comme <img src="/assets/photo.jpg"> :

Il écrit de nouveaux fichiers dans _site/img/ : en WebP et en JPEG, en 600 px de large, en 1200 px et à la largeur d'origine. "auto" dans formats garde le format d'origine : une image PNG donne des fichiers PNG. Il ne crée jamais de fichier plus large que l'image d'origine.
Il remplace la balise <img> par un élément <picture> qui liste ces fichiers. La balise <img> à l'intérieur garde son id, sa class et son alt, et reçoit width, height, srcset, sizes, loading="lazy" et decoding="async".
Les fichiers d'origine sont toujours copiés dans _site/assets/.
Une image avec une adresse complète, comme https://…, par exemple une image d'un CMS, est téléchargée à chaque build, puis changée de la même façon. Ses nouveaux fichiers vont à la racine de _site/, pas dans _site/img/. Si le build ne peut pas la télécharger, voir Le build échoue à cause d'une image.

Chaque largeur et chaque format fait un fichier de plus pour chaque image. Sur un site avec beaucoup d'images, le build est plus long : commencez avec peu de largeurs et de formats.

Vérifiez votre mise en page

La balise <img> se trouve maintenant dans un élément <picture>. Si un style suppose que l'image est un enfant direct de son parent, par exemple dans un conteneur flex ou grid, vérifiez la page publiée.

Réglages pour une seule image¶

Vous pouvez changer ce que fait le plugin pour une seule image, avec un attribut sur cette image dans Silex :

Sélectionnez l'image.
En haut du panneau de droite, ouvrez Settings (icône d'engrenage).
Dans la section Attributes, sélectionnez +. Tapez le nom de l'attribut, par exemple eleventy:widths, et validez.
Dans le champ du nouvel attribut, tapez la valeur, par exemple 200,400.
Publiez.

Ces attributs fonctionnent :

eleventy:widths avec la valeur 200,400 : seulement ces largeurs, en pixels, pour cette image.
eleventy:formats avec la valeur webp : seulement ce format pour cette image.
eleventy:ignore avec la valeur true : le plugin ne change pas cette image.

Ajouter un autre plugin¶

Tous les plugins utilisent les mêmes trois fichiers. La documentation du plugin donne deux choses : le nom de son paquet npm, pour package.json, et les lignes pour eleventy.config.js.

Fonction	Paquet npm	Remarques
Images optimisées	`@11ty/eleventy-img`	Plugin officiel d'Eleventy. Sa transformation HTML modifie chaque `<img>` de vos pages au moment du build. Exemple ci-dessus.
Sitemap	`@quasibit/eleventy-plugin-sitemap`	Le plugin de sitemap pour Eleventy le plus utilisé sur npm. Sa dernière version, la 2.2.0, date de septembre 2022.
Flux RSS	`@11ty/eleventy-plugin-rss`	Plugin officiel d'Eleventy.
Coloration syntaxique	`@11ty/eleventy-plugin-syntaxhighlight`	Plugin officiel d'Eleventy. Colore les exemples de code de vos pages. Exemple ci-dessous.

Pour le sitemap et le flux RSS, suivez la mise en place décrite dans la documentation du plugin.

Vous avez déjà un package.json et un eleventy.config.js ? N'en créez pas un deuxième. Ajoutez le nouveau plugin dans les mêmes fichiers. Par exemple, avec le plugin d'images et le plugin de coloration syntaxique :

package.json :

{
  "type": "module",
  "dependencies": {
    "@11ty/eleventy-img": "^7.1.1",
    "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2"
  }
}

eleventy.config.js :

import { eleventyImageTransformPlugin } from "@11ty/eleventy-img"
import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight"

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    formats: ["webp", "auto"],
    widths: [600, 1200, "auto"],
    htmlOptions: {
      imgAttributes: {
        sizes: "100vw",
        loading: "lazy",
        decoding: "async",
      },
    },
  })
  eleventyConfig.addPlugin(syntaxHighlight)
}

build.json ne change pas : une seule étape npm i installe tous les plugins de package.json. Voir Personnaliser le build pour la référence complète de build.json.

Trois choses à savoir :

Le fichier de configuration doit être à la racine du dépôt, pas dans public/. Un fichier de configuration placé dans public/ est ignoré, et votre build échoue dès qu'une page utilise quelque chose que le plugin devrait fournir.
Silex ne crée jamais d'étape npm i pour vous. Sans elle, votre package.json n'est pas installé et le plugin n'est jamais chargé.
Le nom à utiliser est eleventy.config.js. L'ancien nom .eleventy.js fonctionne encore, et il l'emporte si les deux fichiers existent. N'en créez qu'un seul.

N'importez pas @11ty/eleventy dans votre fichier de configuration

Eleventy est lancé via npx, il n'est donc pas installé dans votre dépôt. Une ligne comme import { HtmlBasePlugin } from "@11ty/eleventy" arrête le build avec Cannot find package '@11ty/eleventy'. N'importez que vos propres plugins, ceux qui sont listés dans votre package.json.

Shortcodes¶

Les shortcodes sont des balises de template, lues au moment du build. Eleventy rend chaque page comme un template Liquid : les shortcodes fonctionnent donc sur tous les sites, avec ou sans source de données.

Un shortcode appelle une fonction, définie dans votre eleventy.config.js, et le build remplace la balise par ce que la fonction retourne. Les plugins fournissent souvent des shortcodes : le plugin syntaxhighlight ci-dessus vous donne un shortcode highlight.

Poser le bloc¶

Dans l'éditeur, ouvrez le panneau des blocs et cherchez le bloc Shortcode, marqué {%, dans le dernier groupe. Glissez-le dans votre page.

Sélectionnez-le, ouvrez les réglages de l'élément (icône engrenage), et remplissez les deux champs :

Shortcode name : le nom du shortcode, par exemple highlight.
Shortcode attributes : les paramètres, par exemple js ou param1, "example param 2".

Le bloc écrit la balise pour vous. Vide, il écrit une balise simple :

{% highlight js %}

Avec d'autres blocs à l'intérieur, il écrit une balise appairée, et votre contenu reste entre les deux balises :

{% highlight js %}
  ... vos blocs ...
{% endhighlight %}

Définir le shortcode¶

Le build doit connaître le shortcode. Il vient soit d'un plugin que vous avez installé, soit de votre propre eleventy.config.js :

export default function (eleventyConfig) {
  eleventyConfig.addShortcode("year", () => new Date().getFullYear())

  eleventyConfig.addPairedShortcode("callout", (content, type = "info") => {
    return `<div class="callout callout-${type}">${content}</div>`
  })
}

À la publication¶

Silex publie la page avec la balise à l'intérieur, et le build remplace la balise par le résultat. Si le shortcode n'est défini nulle part, le build échoue avec tag "<nom>" not found et rien n'est déployé.

Ce que vous ne pouvez pas personnaliser¶

Silex possède plusieurs fichiers et les réécrit à chaque publication. Les modifications que vous y faites sont perdues :

L'arborescence de publication. Silex écrit vos pages, votre CSS et vos assets dans public/.
Le front matter en haut de chaque page, et les fichiers .11tydata.mjs à côté des pages.
build.sh, généré à partir de votre build.json.
Le fichier CI (.gitlab-ci.yml et son équivalent sur les autres plateformes), qui ne fait que lancer sh build.sh.

Ce qui est à vous : build.json, et tout fichier que vous ajoutez à la racine du dépôt, comme package.json et eleventy.config.js.

Dépannage¶

Le build échoue avec `tag "..." not found`¶

Le nom du shortcode n'est pas connu du build. Vérifiez l'orthographe dans le champ Shortcode name, et vérifiez que le shortcode est bien défini dans votre eleventy.config.js, ou fourni par un plugin que vous avez installé.

Mon plugin n'a aucun effet¶

Vérifiez les trois points de Ajouter un plugin : eleventy.config.js à la racine du dépôt, le plugin dans package.json, et une étape npm i avant l'étape de build dans build.json. Publiez à nouveau depuis Silex. Ouvrez ensuite le log du job sur votre plateforme d'hébergement (GitLab : Build → Pipelines, puis le job pages), ou lancez sh build.sh dans un clone de votre dépôt pour obtenir le même build en local.

Silex affiche une erreur sur `build.json` à la publication¶

Le texte de build.json n'est pas valide, souvent à cause d'une erreur de copier-coller : une virgule ou un crochet manquant. Silex arrête la publication avant d'envoyer quoi que ce soit, et affiche l'erreur dans la fenêtre de publication. Par exemple ... is not valid JSON, ou build.json step 0 must be { "type": "build" } or { "type": "sh", "value": "..." }. Ouvrez build.json sur GitLab, collez de nouveau le contenu de l'étape 3, faites le commit, et publiez à nouveau.

Le build échoue à cause d'une image¶

Avec le plugin d'images, le build échoue quand il ne peut pas lire une image : un fichier absent de votre site, ou une image d'un autre site que le build ne peut pas télécharger. Dans le log du job, vous voyez ENOENT: no such file or directory pour un fichier absent, ou Bad response for https://... pour une image d'un autre site.

Corrigez ou retirez cette image dans Silex. Ou demandez au plugin d'ignorer les images qu'il ne peut pas lire, avec l'option failOnError: false. Remplacez le contenu de eleventy.config.js par :

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

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(eleventyImageTransformPlugin, {
    failOnError: false,
    formats: ["webp", "auto"],
    widths: [600, 1200, "auto"],
    htmlOptions: {
      imgAttributes: {
        sizes: "100vw",
        loading: "lazy",
        decoding: "async",
      },
    },
  })
}

Le build garde alors ces images telles quelles, et optimise les autres.

Voir aussi¶

Personnaliser le build — build.json, étapes de build personnalisées, test en local
Documentation Eleventy — référence complète
Transformateurs de publication : tournent dans Silex au moment de publier, avant le build
Build Awesome Plugins — votez pour une intégration plus simple des plugins 11ty/build awesome

Éditer cette page sur GitLab