Journal Eleventy, présentation et mini-tutoriel

Sommaire

• • Présentation
  • Un peu vocabulaire spécifique à 11ty (ou aux SSG).
• Alors comment ca s'utilise en pratique ?
  • Pré-requis
  • Installation
  • Mise en place
  • Allez ca suffit là, on affiche quelque chose maintenant
  • Le premier layout
  • Usage du layout
  • Une page en plus
  • Du style
  • Mise en ligne
  • Ouf, c'est fini ?

Présentation

Eleventy, de son petit nom 11ty, est un générateur statique de site web (SSG - Static Site Generator).

Générateur statique car l'ensemble des pages du site est généré en une fois avant d'être déployées sur le serveur web. C'est un logiciel écrit en javascript prévu pour s'exécuter dans l'environnement comme NodeJS. Les pages sont générées à l'aide de divers moteurs de template (comme Liquid ou Nunjucks) qui s'exécutent sur des données structurée et des contenus en HTML ou markdown. Il est également possible d'utiliser directement du javascript au lieu des moteurs de template. L'intéret d'Eleventy est de combiner ces outils ensembles.

Le projet Eleventy est principalement développé par Zach Leatherman avec l'aide de la communauté. En ce moment Zach est rémunéré par Font Awesome.

Quelques mots sur les autres SSG, le plus connu est probablement Jekyll. À un moment donné, le couple Jekyll et GitHub Pages était un grand classique pour les sites web perso ou pro des développeurs. On peut également citer Hugo ainsi que Astro, même si ce dernier n'est pas seulement un SSG (il fait également du SSR - Server-Side Rendering).

Eleventy est connu pour être rapide et avoir une liste réduite de dépendance JS/NPM. Un soin particulier est donné à cela, par exemple pour la v3, le nombre de dépendance a significativement baissé par rapport à la version v2.0.1 (voir la Release note. Il est également connu pour être unopinionated, c'est à dire que l'utilisateur a un large choix quand à la façon d'utiliser Eleventy. Une douzaine de moteur de template sont gérés de base et on peut en ajouter des customs. Un ensemble de plugins officiels est disponible pour les besoins plus spécifiques.

Un peu vocabulaire spécifique à 11ty (ou aux SSG).

Les fichiers de contenu (de pages, de billets, etc) sont appelés les template. C'est à dire que c'est ce qui va générer une page web par l'application d'un moteur de template sur des données ou des contenus textuels.

Les Collection permettent d'organiser les templates (et donc les pages web) entre elles. Typiquement cela permet de d'organiser la suite de billets d'un blog, les catégories de pages et donc les menus d'un site web.

Les layout servent à factoriser les différentes parties communes entre les pages (comme les menu, en-tête ou pied de page). Il sont également gérés par un moteur de template.

Le Front Matter Data est un entête qu'on peut placer dans n'importe quelle fichier de contenu (un template donc). En général au format YAML, il permet de définir des données structurées qui seront ensuite utilisées lors de la génération. C'est très pratique pour écrire des templates efficaces.

En fait, Eleventy peut utiliser toutes sortes de sources de données : les Front Matter donc, mais aussi des fichiers JSON ainsi que des données distantes depuis des API (on peut le relier à un headless CMS par exemple) et plus généralement d'importe quel résultat d'exécution de javascript. La façon dont les données sont récupérée, générées et fusionnées s'appelle la data cascade. C'est un point central à comprendre pour utiliser Eleventy.
En particulier, il faut avoir en tête que chaque template va avoir accès à un ensemble différent de données (selon sa place dans les répertoires, sa place dans les collections, son front matter, les layouts qu'il utilise).

Alors comment ca s'utilise en pratique ?

Personnellement, j'aime beaucoup le projet mais j'ai eu du mal à rentrer dedans. Je n'ai pas trouvé la documention particulièrement accueillante. C'est déjà du au fait qu'il y a beaucoup de manières différentes d'utiliser Eleventy et qu'évidement il faut connaitre les technologies web (ce qui devient de plus en plus compliqué).

Il n'y a pas vraiment de tutoriel officiel. Il y a beaucoup du tutoriels communautaire mais ont est tout de suite perdu dans la diversitée. En fait, on est en plein dans le modèle du bazar, c'est sympa, j'aime beaucoup la liberté qu'on y trouve, mais on s'y perd un peu.
Je ne suis pas le seul à le penser d'ailleur, voir le ticket Consider adding content to help new users with an opinionated guide to building a site..

Une autre chose à comprendre, c'est qu'Eleventy utilise beaucoup de bibliotheques tierces. En particulier aucun des moteurs de template n'a été créé pour Eleventy, le projet va simplement réutiliser ce qui a été fait ailleurs. Donc, et par exemple, si on souhaite écrire des templates avec Nunjucks aller voir la documentation Eleventy dédiée n'apporte pas grand chose. Il faut plutot aller voir la page officielle de Mozilla. En fait Eleventy est principalement un moteur qui va orchestrer le calcul de la data cascade et l'exécution d'outils tierces.

Il ne suffit donc pas juste apprendre Eleventy, mais Eleventy et l'ensemble des langague et outils qu'on a choisi pour son projet.

Pré-requis

Il vous faudra NodeJS. Personnellement je vous conseille de prendre la dernière LTS (c'est à dire la v22 au moment où j'écris ces lignes). J'ai eu des soucis avec la v18 qui est recommandée par Eleventy et qui est dispo dans les paquets Debian stable.

Pour cela, je vous propose d'utiliser Node Version Manager. Voir leur documentation, mais globalement il faut faire ceci (si vous acceptez d'exécuter un script bash téléchargé) :

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
nvm install --lts

Il vous faudra évidement un éditeur de texte. N'importe lequel conviendra mais si vous voulez être à la mode cool kids in town et avoir accès à toutes les extensions du moment prenez vscode. Alors évidement c'est pas terrible niveau philosophie du libre (j'ai pas encore essayé VSCodium).

Installation

Maintenant qu'on a l'environnement, il suffit des commandes ci-dessous pour installer Eleventy (localement dans un répertoire). Voir la doc 11ty pour plus d'info.

mkdir my_great_site && cd "$_"
npm init -y
npm pkg set type="module"
npm install @11ty/eleventy

Alors petite chose à savoir, là on a configuré le projet avec ESM le nouveau standard de module JavaScript (celui avec import() et pas des require). C'est un peu pénible car il existe encore beaucoup de documentation sur le Net avec l'ancienne syntaxe.

Mise en place

On va configurer quelques petites choses. Créez un fichier eleventy.config.js avec le contenu ci-dessous. J'ai configuré les répertoires et j'ai choisi le moteur de template nunjucks pour les fichiers markdown et html.

export const config = {
    // Directory configuration
    dir: {
        input: "content",          // default: "."
        includes: "../_includes",  // default: "_includes" (`input` relative)
        data: "../_data",          // default: "_data" (`input` relative)
        output: "_site"
    },

    // Pre-process *.md files with nunjucks (default: `liquid`)
    markdownTemplateEngine: "njk",

    // Pre-process *.html files with nunjucks (default: `liquid`)
    htmlTemplateEngine: "njk",

};

export default async function (eleventyConfig) {

    // Copy the contents of the `public` folder to the output folder
    // For example, `./public/css/` ends up in `_site/css/`
    eleventyConfig
        .addPassthroughCopy({
            "./public/": "/"
        })

};

Et créez les répertoires correspondants :

mkdir _data _includes content public public/{css,img}

On va aussi préparer l'usage de git. Créez le fichier .gitignore avec le contenu suivant.

node_modules
_site
.cache

On se retrouve normalement avec ceci :

├── content     # Ici c'est les pages web (les templates)
├── _data       # là les donnéess structurées (typiquement en JSON)
├── _includes   # les layouts
└── public
    ├── css     # les feuilles de style CSS
    └── img     # et les images (qui doivent déjà être
                #  optimisée pour le web)

Allez ca suffit là, on affiche quelque chose maintenant

Donc, ouvrons un fichier index.md dans le répertoire content avec quelque lignes de textes dedans. Comme par exemple :

Bonjour le monde !

Ca y est, vous y êtes ? Alors maintenant la commande magique :

npx @11ty/eleventy --serve

Et normalement vous voyez vos lignes à l'adresse http://localhost:8080/. C'est un serveur de développement. Il est intégré à Eleventy et mise à jour le site automatiquement à chaque changement de fichiers.

Le premier layout

Donc pour le moment, on a pas encore d'HTML complet mais seulement un <p>Bonjour le monde !</p> qui provient de la transcription du fichier mardown index.md.

Ouvrez donc, un fichier base.njk dans le répertoire _includes avec le contenu suivant

<!doctype html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="{{ eleventy.generator }}">
    <title>{{title }}</title>
</head>
<body>
{{content | safe }}
</body>
</html> 

Ce fichier est écrit dans un mélange d'HTML et de Nunjucks (extension de fichier .njk). Les parties en Nunjucks sont encadrée {{comme ça}} (cette syntaxe en "moustache" est commune a plusieurs moteur de template). Ici on a :

• {{title}} qui sera remplacé par le contenu de la variable title
• {{content | safe }} idem mais sans échappement du HTML contenu
• et j'ai ajouté un petit meta pour dire que votre site dise au monde entier qu'il utilise Eleventy (mais avec discretion et classe)

Usage du layout

Pour utiliser ce layout, on va ajouter un entête Front Matter Data. Modifiez donc votre template index.md pour qu'il ressemble à ceci.

---
title: Hello
layout: base.njk
---

Bonjour le monde !

C'est assez simple, mais il faut remarquer que l'entête en YAML est transformé en donnée javascript qui sont ensuite utilisable dans le layout. La ligne layout a une signification particulière et indique quel fichier de layout doit être utilisé pour rendre ce template. Le contenu du fichier mardown est tranformé en HTML et est disponible dans la variable content de la data cascade.

Une page en plus

Pour faire bonne mesure rajoutons une page. Ouvrez un fichier blague.md avec le contenu suivant.

---
title: Une blague
layout: base.njk
---

Comment vas-tu yau de poêle ?

Dans le fichier index.md ajoutez la ligne.

Allez voir [mon autre page](blague).

Petite remarque : avec cette façon de faire on utilise des URLS de la forme http://localhost:8080/blague/ plutot que http://localhost:8080/blague.html.

Je vous laisse méditer sur les avantages et implications de cela.

Du style

Ajoutons un fichier de style CSS. Ouvrez donc style.css dans le répertoire public/css avec le contenu suivant.

body {
    font-family: Helvetica, Arial, sans-serif;
    background-color: cadetblue;
    max-width: 80ch;
    text-wrap: pretty;
    margin-inline: auto;
}

h1, h2, h3 {
  text-wrap: balance;
}

h1 {
  text-align: center;
}

Et il faut évidement ajouter la ligne suivante dans le head de base.njk

<link rel="stylesheet" href="/css/style.css">

Mise en ligne

Maintenant il faut mettre cela en ligne, le déployer quoi.

La méthode old-school consiste à générer les fichiers puis à les téléverser sur un serveur web. Pour cela, lancez la commande suivante.

npx @11ty/eleventy

et votre site web se retrouve dans le répertoire _site/. Cela peut être pas mal de vider ce répertoire avant car des anciens fichiers générés peuvent s'y trouver (si vous avez renommé ou déplacé des choses par exemple).

À partir de là, on peut téléverser avec FTP, Rsync etc.

Mais bon, nous on est moderne ! On fait du Jamstack, yeah ! Avec cette approche, les sources sont placées dans un dépôt git (souvent sur github) et le site est construit automatiquement lorsqu'on push sur le dépot. Les fournisseurs serverless pour ce genre de service sont typiquement netlify ou Vercel ou encore sur cloudfare page (ce dernier est plus un CDN qui fait aussi du serverless). C'est souvent gratuit jusqu'a une certaine limite de temps de build et de quantité de données servies.

Évidement, tout cela est au État-unis. Par les temps qui cours, ca peut être instructif d'aller faire un tour sur European Alternatives. J'ai choisi d'essayer statichost, que je connaissais pas avant.

Donc, il va falloir expliquer à statichost qu'on veut utiliser Eleventy, pour cela créez le fichier statichost.yml avec le contenu suivant.

image: node:22
command: npm install && npx @11ty/eleventy
public: _site

Ici on configure :

• l'usage d'un conteneur docker pour nodejs en version 22
• la commande pour générer le site web
• et le répertoire ou se trouve le résultat

Je vous laisse créer le dépot git et le pousser sur github ou ailleurs. Là j'ai plus le courage de détailler.

Ensuite il suffit de créer un compte sur le fournisseur serveur que vous avez choisi et de créer un site en lui fournissant l'URL du dépot git.

Et voilà !

Pour référence, mon dépot sur trouve là : https://github.com/joris-r/my_great_site.git

Ouf, c'est fini ?

C'est tout pour le tutoriel, je pense que c'est le minimum à savoir pour bien commencer avec Eleventy.

Pour un site "normal", il y a encore un peu de travail. Vous pouvez jeter un oeil sur Starter Projects Base Blog fait par le créateur d'Eleventy. Il sert souvent de référence en matière de bonne pratique.

Sinon, vous pouvez explorer les tutoriels de la communautées ou le contenu aggrégé sur 11tybundle.

J'ai appliqué ce tutoriel sur lui-même et le résultat est sur mon site, je le mettrai peut être à jour là-bas.