Choix d'un générateur de sites statiques

2024-08-02 dev | tags : 11ty ssg zola

Introduction

J'ai l'impression que l'envie de tenir un site personnel, sous la forme d'un blog ou d'un wiki, revient souvent, mais une fois l'outil mis en place, je passe plus de temps à le configurer qu'à réellement créer du contenu. En février 2018 (il y a 6 ans...) j'avais commencé à rédiger un article sur le choix d'un générateur de site statique (SSG). Je vais reprendre une partie dans une section historique, puis donner l'évolution aujourd'hui dans mes choix.

Historique

Le 19 février 2018

J'ai décidé de créer un blog. Celui-ci a d'abord pour objectif de faire office de bloc-note : mettre en forme toute sorte de recherches, sur l'informatique et les mathématiques majoritairement. Savoir que l'on peut être relu force à peaufiner le contenu et sa mise en forme.

Les sites statiques sont assez en vogue comme le signale cet article de Smashing Magazine d'août 2016, ou ce post plus récent (février 2018) de dareboost. L'argument en faveur des sites statiques qui a fait pencher la balance est la sérénité du déploiement : on peut héberger ce genre de site sur github ou gitlab, et l'oublier (pas de stress quant à la sécurité, pas de risque de tentative d'intrusion). Celui-ci est hébergé sur l'instance gitlab framagit de framasoft (les Gitlab Pages ont été portées vers l'édition communautaire de gitlab fin 2016).

Dans ce post, je décris ma démarche sur la recherche d'un outil générant des sites statiques, suivi d'une description de la solution choisie.

Recherche d'outils

Pelican

Un premier frein a été le choix de logiciel permettant de générer des sites statiques. Cherchant un générateur en python, le premier apparaissant sur staticgen est pelican. J'ai eu pas mal de difficultés à comprendre comment fonctionnait Pélican. Même après avoir vu que auteur avait réalisé diagramme Use Case et un diagramme de classe, disponible via la page report de la documentation. Pelican est très simple à mettre en place, et founit de base un système de tags et de catégories, une création de flux rss. Un site recense divers thèmes créés par la communauté. La création de thème est d'ailleurs accessible : on peut utiliser les templates jinja du thème simple, n'offrant qu'une structure html rendant le blog fonctionnel. La customisation se fait via l'utilisation de plugins : ceux-ci fonctionnent à l'aide de signaux placés tout au long du processus de génération du contenu, la liste des signaux est également présente sur le site, avec une brève description. J'ai trouvé le détail des signaux insuffisant, ne dispensant pas la lecture du code (ni de s'inspirer de l'implémentation de la large collection de plugins existants).

Comme l'a décrit l'auteur, pelican est à l'origine un outil personnel, qui hérité de l'ajout de nombreuses fonctionnalités, mais qui n'a pas été pensé, à la base, pour être un outil de blog aussi généraliste (l'analyse réalisée via le diagramme UML en témoigne).

Cactus

Trois autres outils m'ont fait du pieds. Le premier est Cactus, basé sur Django. Utilisé un outil se basant sur une technologie existante et approuvée est un plus lorsqu'on la connaît déjà. Un avantage que j'ai trouvé, est la présence de plugins déjà implémentés lors de la création d'un nouveau projet (il suffit de renommer le plugin en supprimant disabled de son nom). On peut donc s'inspirer de ce qui est existe déjà pour élargir les fonctionnalités de l'outil. En revanche, un frein est le manque d'activité du projet, et l'obsolescence de la version de django utilisée (Django>=1.6,<1.7 dans le fichier requirements.txt). Bien qu'il ne s'agisse en rien d'une faille de sécurité (même si la version de Django utilisée n'est plus mise à jour, la modification du site n'a lieu qu'en local), on doit renoncer aux nouvelles fonctionnalités existantes (nouveaux filtres par exemples), ainsi qu'aux extensions.

Si on apprécie Django, on peut aussi se tourner vers django-bakery ou wagtail-bakery : on héberge notre cms django, en le rendant accessible uniquement aux personnes responsables de l'édition de contenu (dans un intranet propre à une école ou une pme par exemple), on génère ensuite une version statique du site, qui elle sera hébergée et accessible sur le web.

Nikola et Lektor

J'ai également jeté un coup d'oeil à Nikola. La liste des fonctionnalités est impressionnante et en fait un outil très complet. Il a été conçu pour être extensible, l'ensemble de ses fonctionnalités sont basés sur des plugins, et une page décrit comment en créer de nouveaux. Le programme semble assez bien actif, je ne savais pas que le wxPython était rendu par Nikola, comme pas mal d'autres sites. Il semble être un outil intéressant, comme doit l'être également lektor, trouvé après une recherche. Il se veut être un framework entièrement pensé pour générer des sites statiques. Les modèles sont présents sous la forme de fichiers .ini, comme on peut le voir sur la page présentant le modèle servant à créer un blog. Contrairement aux autres outils présentés, ce dernier a l'avantage de permettre un mode d'édition via une page admin. Il est également extensible, mais j'avoue avoir été rebuté par le le code source du plugin lektor_tags ; il s'agit vraiment d'une framework à part entière, le temps d'apprentissage est donc plus long, mais peut sûrement permettre d'être plus productif par la suite.

Outils dans d'autres langages

Je me suis bien sûr intéressé à jekyll. La critique qui revenait le plus lors de recherches est le temps de génération des pages, ce qui ne me dérange pas étant donné la taille du blog. J'avais regardé à l'époque la vidéo sur jekyll de grafikart. Le problème est ma méconnaissance du langage Ruby, qui, malgré la présence innombrables de plugins créés par la communauté, m'effraie sur le long terme si le besoin d'une fonctionnalité spécifique se faisait ressentir.

Le problème avec Hugo reste le même, l'inconnu du langage et le manque de temps destiné à m'y consacrer. Deux autres ont retenu mon attention, il s'agit de hexo et nuxt. J'ai bien aimé Nuxt, il facilite en fait la gestion des routes avec vue : celles-ci sont définies selon les fichiers créés. Je ne sais pas s'il possible ensuite de générer statiquement le site, pour ne pas, si l'on souhaite coder en markdown, générer le rendu côté client. Hexo dispose d'un nombre impressionnant de plugins, mais à ce stage de la recherche, j'avais décidé d'utiliser un outil peut-être beaucoup moins avancé, demandant plus de code, mais moins haut niveau, pouvant être pris en main directement.

Le choix retenu

C'est ce post de James Hardin qui m'a enfin sorti de l'impasse : il présente comment créer un site ou un blog statique, avec Flask, grâces aux extensions (brièvement décrites) suivantes :

Frozen Flask : L'extension la plus utile, elle génère des pages html, en parcourant les routes définies avec Flask, et également les appels à la fonction url_for.
Flat Page : Extension lisant tous les fichiers d'une certaine extension dans un dossier donné, et y applique la méthode render (customisable). Sur ces fichiers, elle lit les méta-données : ceux-ci sont sous format yaml, en début des fichiers plats.

L'avantage de cette option est d'avoir un outil adapté (uniquement?) à ses besoins. Il faut néamoins se construire son propre environnement de travail, chaque fonctionnalité devant être implémentée par ses propres soins.

Choix retenus (en 2024)

La suite du précédant détaillait le développement du générateur de site, comprenant les gestions des tags, catégories, des brouillons, de la gestion du latex dans les articles, et d'autres. Au final, je n'ai publié que très peu d'articles, étant donné qu'à chaque fois je souhaitais rajouter de nouvelles fonctionnalités. Avec le recul, j'ai pu mieux percevoir quels étaient mes besoins, que voici:

Utiliser markdown ou org pour gérer le contenu.
Pouvoir créer un thème en utilisant un moteur de template ressemblant à jinja2.
Ne pas avoir de trop de fichiers de templates à créer pour pouvoir commencer à styliser mon blog.
Avoir une gestion des taxonomies me permettant de définir des tags, catégories, ou autres, sans ajout d'extension ou autre.

J'avais utilisé hexo, son moteur de blog est nunjucks, bien inspiré de jinja2, mais la gestion des taxonomies est fastidieuse. Hugo est le générateur de statique proposant de base bon nombre de fonctionnalités, mais c'est plutôt le moteur de template qui m'a rebuté. J'ai retenu deux choix, que j'utilise dans diverses situation: 11ty et Zola.

Zola

Ce générateur de site statique répond à tous mes besoins spécifiés ci-haut. Ce que je trouve intéressant dans ce programme:

Il est fourni comme un seul exécutable, sans aucun système de plugin.
L'arborescence du dossier est sobre et claire.
```
.
├── config.toml
├── content
├── sass
├── static
├── templates
└── themes
```
Les fichiers (en markdown principalement) seront dans le dossier content. Tout les fichiers stockés dans le dossier static seront copiés dans le public tels quels.

On a un dossier template qui permet de surcharger un thème choisi. En zola, un thème est juste un projet zola, cela signifie qu'il a la même structure que ce qui est présenté ci-haut, avec les templates dans le dossier du même nom. Si on veut créer un thème personnalisé pour son site, on peut donc placer les fichiers html dans le dossier template simplement, et n'utiliser aucun thème.

Zola précompile tous les fichiers sass/scss qu'il trouve dans le dossier sass, et les places à la racine de public.

Enfin un fichier config.toml, assez simple également.
Il gère de base des taxonomies personnalisées. Il ne vient donc pas avec des tags ou des categories, mais si on veut un système de tags, on a juste à rajouter taxonomies = [ { name = "tags" } ] dans le fichier config.toml. Par contre, Zola suppose qu'une taxonomie peut toujours contenir un ou plusieurs élément. Donc si on veut créer, comme dans Pelican, un système de catégorie ou chaque article n'appartient qu'à une catégorie, c'est possible. On définit: taxonomies = [ { name = "category" } ], puis dans les métadonnées on ne définit qu'une catégorie, donc une liste avec un seul élément:
```
+++
[taxonomies]
category = ["lecture"]
+++
```
Dans les fichiers html de template, on ne récupérera que le premier élément d'une categorie: page.taxonomies.category.0. Dans ce cas, le générateur n'affichera aucun avertissement si plusieurs catégories sont précisées, mais seule la première sera prise en considération.
Au niveau rendu, chaque sous-dossier de content/ sera une section, définie par le fichier _index.md dont le template est section.html par défaut. Une variable section.pages permet de récupérer toutes fichiers markdown de ce sous-dossier. Pour ces fichiers markdown, le template par défaut est page.html, et la page d'accueil est définie par index.html. En gros, trois templates suffisent pour créer notre site. On peut évidemment changer le fichier de template dans les metadonnées des fichiers markdown.
Zola utilise le moteur de rendu tera, dont la syntaxe est inspirée de jinja2. Zola est livré avec des fonctions prédéfinies, peu nombreuses mais réfléchies.
Il gère, en plus des pages html: des flux rss, un fichier sitemap.xml et un fichier robots.txt.
Comme les autres SSG, il dispose de la possibilité de définir des shortcodes, en html comme en markdown.
Un plus non négligeable et assez inattendu: Zola permet de récupérer des données depuis un fichier plat en toml, json, csv, bibtex, yaml, ou xml, mais également un requête GET ou POST. Ce qui permet donc de généré un site web avec Zola combiné à un headless cms.

En conclusion, je dirais que Zola:

✓ Est simple à installer et à mettre en place,
✓ dispose de tout ce dont j'ai besoin, sans extensions,
✕ n'est pas customisable,
✕ ne permet la génération de documents html uniquement.

Ces deux derniers points ne sont pas forcément des inconvénients. La customisation est chronophage et la dernière est un choix, voir cette discussion. Ça ne me déplaît pas d'utiliser un programme dont le but est clair, parfois l'auteur doit savoir dire non.

Donc, comme précisé dans les commentaires, avec Zola, il n'est pas possible de générer un site compatible avec le protocol gemini. Ou bien de générer des fichiers .htaccess qui permettraient de créer des urls raccourcies via le un RewriteRule d'Apache. On pourrait également vouloir exporter son contenu au format .json. Tout ceci, Zola ne le fait pas. Il s'agit de cas spécifiques et non indispensables à création d'un site web. Pour ce faire, on peut utiliser eleventy.

11ty

Eleventy, noté 11ty, est un SSG pensé plutôt comme outil donnant les bases pour créer son propre site statique, sans obliger à adopter une structure particulière dans nos contenus. Il gère donc plein de formats de fichiers de contenus, et également de templates. D'ailleurs, tout est customisable: on peut facilement rajouter un format. Le point d'entrée de 11ty est le fichier .eleventy.js.

Il n'y a pas de gestion automatique des taxonomies, comme je le souhaites. Mais 11ty permet de créer facilement des collections. Le seul mot-clé harcodé est slug, on peut récupérer des articles ayant un certain slug assez facilement. Mais on peut créer une collections d'articles ayant, par exemple, une certaines catégorie. Il suffit d'utiliser la Collection API; ceci demande du code, mais permet d'avoir un site complètement adapté à ses besoins.

L'inconvénient, selon moi, est d'utiliser 11ty pour un site web dont les besoins sont satisfaits par ce que propose Zola. Si l'on souhaite une gestion des taxonomies, on doit l'implémenter. On le fait sans doute de manière moins générique que Zola, mais du code doit être créé.

Une autre version de ce blog était généré avec 11ty. Même si j'ai aimé ce sentiment de pouvoir satisfaire l'ensemble de mes besoins, je passais plus de temps à le configurer qu'à rédiger du contenu.

Malgré tout, un site en zola peut être, sans trop de peine, converti en un site généré via 11ty. Ce dernier gère nativement le moteur de template nunjunks, et peut s'adapter à l'arborescence imposée par zola.

En conclusion, je dirai que 11ty:

✓ Fournit un outil puissant pour créer un site hautement customisable,
✕ Nécessite un plus grand investissement au départ pour gérer la base, comme un sitemap, un flux rss, une taxonomie basique.

Article publié le 2 août 2024.