Aller au contenu

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 (propulsé par Eleventy, version épinglée 3.1.6) transforme public/ en _site/, et c'est _site/ qui est déployé.

L'étape de build lance deux 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 écrit aussi public/public.11tydata.js à chaque publication, pour tous les sites. Ce fichier indique à Eleventy comment traiter vos pages :

  • Sur un site sans source de données, il définit un permalink et templateEngineOverride: false. Vos pages sont copiées telles quelles : about.html reste about.html, et la syntaxe de template n'est pas touchée.
  • Sur un site avec une source de données, il vaut export default {}. Chaque page porte alors son propre front matter, et Eleventy rend les pages comme des templates Liquid.

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, ou lancez le pipeline à la main depuis l'interface de la plateforme.

Ajouter un plugin

Un plugin Eleventy ajoute des fonctionnalités au build : coloration syntaxique, optimisation d'images, flux, et bien d'autres. En ajouter un demande trois fichiers dans le dépôt de votre site.

1. package.json, à la racine du dépôt, avec le plugin en dépendance :

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

2. eleventy.config.js, à la racine du dépôt lui aussi, à côté de package.json :

import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight"

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight)
}

3. build.json, pour installer les dépendances avant le build :

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

Publiez à nouveau, et le plugin est actif. 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 vont avec les sources de données. Ce sont des balises de template, lues au moment du build, sur les pages qu'Eleventy rend comme des templates. Un site avec une source de données a ce type de pages, les shortcodes y fonctionnent donc. Un site sans source de données est publié en fichiers simples, la syntaxe de template n'est pas touchée, et un shortcode n'a rien pour s'exécuter.

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 le panneau des réglages, 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/.
  • public/public.11tydata.js.
  • 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

Mon shortcode apparaît en texte sur la page publiée

La page a été copiée, pas rendue. Cela arrive sur un site sans source de données. Les shortcodes ont besoin d'une source de données.

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. Ouvrez ensuite le log du job sur votre plateforme d'hébergement, ou lancez sh build.sh dans un clone de votre dépôt pour obtenir le même build en local.

Voir aussi

Éditer cette page sur GitLab