Aller au contenu

Personnaliser le build

Personnalisez le build exécuté à la publication de votre site — ajoutez des outils comme Pagefind, installez des paquets npm, ou lancez n'importe quelle commande shell.

Aperçu

Quand vous publiez un site Silex vers un hébergement basé sur Git (GitLab Pages, Codeberg/Forgejo Pages, SourceHut Pages), Silex génère les fichiers qui construisent et déploient votre site sur la CI de la plateforme :

Fichier Propriétaire Règle
build.json Vous Créé avec [{ "type": "build" }] s'il n'existe pas, puis jamais touché par Silex — c'est ici que vous personnalisez le build
build.sh Silex Régénéré depuis build.json à chaque publication — ne pas éditer
Fichier CI (.gitlab-ci.yml, .forgejo/workflows/pages.yml, .build.yml) Silex Immuable : il ne fait que lancer sh build.sh — ne pas éditer
public/public.11tydata.js Silex Publié à chaque publication, configure le build Eleventy

Le build lui-même est toujours le même, pour les sites statiques comme dynamiques : build awesome (propulsé par Eleventy, version épinglée — actuellement 3.1.6) construit le dossier public/ vers _site/, qui est ce qui est déployé. Pour un site purement statique, le fichier public/public.11tydata.js généré rend ce build une copie à l'identique, octet pour octet — mêmes noms de fichiers, mêmes URLs, syntaxe de template laissée intacte.

Pour personnaliser le build, éditez build.json — pas le fichier CI, et pas build.sh.

Le fichier build.json

build.json, à la racine du dépôt de votre site, est un tableau ordonné d'étapes :

[
  { "type": "build" }
]

Deux types d'étapes sont disponibles :

  • { "type": "build" } — le build Silex standard (Eleventy compile public/ vers _site/). Il est résolu à chaque publication, donc il suit les mises à jour de Silex (montées de version d'Eleventy, améliorations du build) sans que vous ayez rien à changer.
  • { "type": "sh", "value": "<commande shell>" } — n'importe quelle commande shell. Placez-la avant ou après l'étape de build selon vos besoins.

Silex crée build.json à la première publication s'il n'existe pas, et ne l'écrase jamais ensuite. Vos personnalisations sont préservées d'une publication à l'autre.

Exemple : ajouter la recherche avec Pagefind

Pagefind indexe votre site après le build et ajoute une recherche côté client :

[
  { "type": "build" },
  { "type": "sh", "value": "npx -y pagefind@1.4.0 --site _site" }
]

Notez le --site _site : la sortie du build va dans le dossier _site/, donc les commandes qui post-traitent le site construit doivent cibler _site.

Exemple : installer des dépendances npm

Si votre build a besoin de paquets d'un package.json (par exemple des plugins Eleventy), installez-les avant l'étape de build :

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

Tester le build en local

build.sh est un simple script shell : vous pouvez lancer exactement le même build que la CI sur votre machine. Clonez le dépôt de votre site, puis :

sh build.sh

Le site construit est dans _site/. C'est le moyen le plus rapide de déboguer un pipeline qui échoue.

Variables d'environnement CI

Vos étapes sh s'exécutent dans le job CI de la plateforme, donc les variables CI y sont disponibles. Sur GitLab, définissez-les dans votre projet sous Settings → CI/CD → Variables, puis utilisez-les dans une étape :

[
  { "type": "build" },
  { "type": "sh", "value": "curl -X POST \"$DEPLOY_HOOK_URL\"" }
]

Codeberg/Forgejo (dépôt Settings → Actions → Secrets) et SourceHut (build secrets) offrent des mécanismes équivalents.

Redirections d'URL

GitLab Pages prend en charge un fichier _redirects à la racine du site publié, avec la même syntaxe que les redirections Netlify. C'est utile pour :

  • Préserver les anciennes URLs quand vous réorganisez votre documentation ou vos pages
  • Rediriger des URLs courtes vers des chemins complets
  • Gérer le contenu déplacé sans casser les favoris ni les liens des moteurs de recherche

Créez un fichier _redirects à la racine de votre dépôt :

# _redirects
/ancienne-page    /nouvelle-page    301
/blog/:slug  /articles/:slug  301

Chaque ligne a trois champs séparés par des espaces : l'ancien chemin, le nouveau chemin, et le code HTTP (301 pour une redirection permanente, 302 pour une temporaire).

Le fichier doit se retrouver dans _site/ après le build — ajoutez une étape de copie dans votre build.json :

[
  { "type": "build" },
  { "type": "sh", "value": "cp _redirects _site/" }
]

Voir la documentation des redirections GitLab Pages pour la syntaxe complète (règles splat, paramètres de requête, redirections forcées).

Migrer depuis l'ancien système (.gitlab-ci.yml personnalisé)

Avant l'existence de build.json, personnaliser le build voulait dire éditer .gitlab-ci.yml directement et passer sa première ligne à # silexOverwrite: false pour que Silex ne l'écrase pas.

Les sites dans cette situation ne sont jamais touchés par Silex et continuent de fonctionner tels quels — aucune urgence à migrer. Pour faire passer un tel site au nouveau système :

  1. Créez build.json à la racine du dépôt, avec vos commandes personnalisées en étapes { "type": "sh" } autour de l'étape { "type": "build" }. Attention : la sortie du build est maintenant _site/ (les anciens scripts se terminaient souvent par rm -rf public && mv _site public — supprimez cette ligne, et faites pointer vos commandes vers _site).
  2. Repassez la première ligne de votre .gitlab-ci.yml à # silexOverwrite: true.
  3. Publiez depuis Silex — Silex remplace le fichier CI par le standard et génère build.sh depuis votre build.json.

Dépannage

Le pipeline échoue

Ouvrez le log du job sur votre plateforme d'hébergement (GitLab : CI/CD → Pipelines). Puis reproduisez en local avec sh build.sh — vous obtenez le même build, avec des itérations plus rapides.

Mes modifications de .gitlab-ci.yml ou build.sh disparaissent

Ces deux fichiers sont générés par Silex à chaque publication. Mettez vos personnalisations dans build.json — ce fichier est le vôtre et n'est jamais écrasé.

Ma commande de post-traitement n'a aucun effet

Vérifiez qu'elle cible _site/ (la sortie du build), pas public/ (l'entrée du build), et qu'elle s'exécute après l'étape { "type": "build" } dans build.json.

Voir aussi

Éditer cette page sur GitLab