Eleventy

J'en ai parlé dans l'article précédent, dans cet article je vais présenter Eleventy (ou désormais Awesome Build), un générateur de site web statique qui a l'avantage d'être simple et c'est avec cet outil que j'ai re-travaillé intégralement mon site web.

Le but ici n'est pas de présenter les fonctionnalités mais plutôt d'explorer rapidement la façon dont j'ai pu contruire le site avec combiné aux autres frameworks utilisés.

C'est quoi Eleventy ?

Comme expliqué plus haut, c'est un générateur de site web statique donc le but étant de mettre en place plusieurs source de données (informations, articles, etc) dans différents formats qui vont être appliqués à un template générant ainsi une page HTML sans code serveur PHP ou autre.

L'avantage est ainsi qu'avoir quelque chose de simple à maintenir et que le serveur web pourra distribuer très rapidement. Cela n'empêche pas d'avoir quelque chose de riche mais ne sera forcément pas très adapté à tous les besoin, dans le cas d'un site personnel qui sert en même temps de blog par contre c'est très adapté.

Autre point important que j'ai avancé plus haut c'est la simplicité, on y vient...

Comment ça marche ?

Je vais décrire mon cas d'usage même si à priori il y a pas mal de moyens de l'utiliser que vais rester assez spécifique pour ne pas trop dériver.

Il faut d'abord avoir d'installé NodeJS et NPM, puis lancer les commandes de setup de base.

# Initialization du projet
npm init

# On ajoute la dépendence à Eleventy
npm install @11ty/eleventy --save-dev

Puis on édite le fichier package.json :

{
  // ...
  "scripts": {
    // Pour pouvoir générer tous les fichiers HTML
    "build": "eleventy",
    // La même chose mais en plus on lance un serveur web local qui écoute
    // les modifications dans les sources et les appliquent aux fichiers
    // générés.
    "serve": "eleventy --serve",
  }
  // ...
}

Ensuite on crée un fichier .eleventy.js :

module.exports = function(eleventyConfig) {
    // Copy les fichiers dans "src/assets" vers un dossier "assets" de la destination
    eleventyConfig.addPassthroughCopy({
        "src/assets": "assets"
    });

    // La config
    return {
        dir: {
            // Dossier où se trouvent nos données, templates, etc...
            input: "src",
            // Un dossier explicitement defini pour des includes de templates
            includes: "_includes",
            // Le dossier de destination des fichiers générés
            output: "dist"
        }
    };
};

Plus qu'à créer la hiérarchie de base :

node_modules/
dist/
src/
  _data/
  _includes/
  assets/
.eleventy.js
package.json
...

Et à partir de là il y a tout ce qu'il faut pour démarrer.

Les templates Nunjucks

Maintenant qu'on a la base on définit des pages grâce à des templates Nunjucks. Ce n'est pas le seul langage de templates utilisable (la liste est accéssible ici) mais c'est ce que j'ai utilisé est quand même assez intuitif.

Voici un exemple de base :

<!-- index.njk -->
<html lang="{{ lang | default('fr') }}">
<head>
    <meta charset="utf-8">
    <title>{{ title }}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/assets/css/style.css">
</head>
<body>
    {% include "navbar.njk" %}
    <main class="container">
        {% block inner %}
            {{ content | safe }}
        {% endblock %}
    </main>
    {% include "footer.njk" %}
</body>
</html>

Le template peut utiliser des variables avec {{ ma_variable }}, des blocks HTML entiers avec {% block <nom_du_block> %}<contenu>{% endblock %} qui peuvent être overridés dans des sous-templates, des blocks conditionnels comme des if, for, etc.. ou d'autres fonctionnalités en fonction des besoins.

Les sources de données

Eleventy fourni automatiquement au moteur de templates des variables et blocks à partir de différents fichiers dans les sources. Par exemple dans le dossier _data j'ai placé des fichiers JSON qui sont accessibles depuis tous les templates :

// src/_data/site.json
{
    "title": "Mon site",
    // ...
}

Ainsi dans le template je pourrais accéder à la variable comme ça :

<!-- src/index.njk -->
<html>
<head>
    <title>{{ site.title }}</title>
    <!-- ... -->
</head>
<!-- ... -->
</html>

On peut aussi en définir dans une en-tête YAML du fichier source (.njk, .md, etc). Exmple d'un fichier markdown :

---
title: Ma page
...
---

# Ma page

...

Puis dans un fichier .njk dans lequel on pourra accéder à la variable title de l'en-tête, ainsi qu'au contenu du markdown converti en HTML (pour des articles de blog par exemple) avec la variable content :

<!-- src/index.njk -->
<html>
<head>
    <title>{{ title }}</title>
    <!-- ... -->
</head>
<body>
    <main class="container">
        {{ content | safe }}
    </main>
</body>
</html>

Cet ensemble de mécanismes combinés permet de gérer des choses assez complexes comme de la pagination d'articles, du multilangage, etc...

Compléments

Vu que l'on est sur de la génération de site statique, il est possible d'ajouter un certain nombre de sur-couches par dessus Eleventy pour aggrémenter le site généré. Déjà il y a la possibilité d'utiliser des composants React via des modules supplémentaires ce que j'ai essayé un peu mais n'ai finalement pas utilisé en fin de compte. Ensuite il est possible de générer en amont un certain nombre de données qui vont être ensuite inclus dans le build d'Eleventy aggrémentant ainsi le site, dans mon cas il s'agit de synchroniser via un script C# les pages d'articles écrits uniquement dans une seule langue pour ne pas se retrouver sur une page non trouvée dès que l'on va vouloir changer de langue (même si c'est simplement pour afficher un message indiquant que l'article n'est pas disponible dans cette langue).

Conclusion

Voilà pour le petit tour d'horizon sur Eleventy, il y a beaucoup de choses à dire dessus mais encore une fois ce n'est pas le but de cet article. Je laisse quelques liens vers de la documentation et à bientôt.