Générateurs de sites statiques à partir de zéro : vocabulaire, histoire et première création
Apprenez les termes que les documents SSG supposent que vous connaissez, la manière dont les maquettes, les composants partiels et le matériel de présentation s’assemblent, l’origine des générateurs, ainsi que la façon de choisir un générateur sans difficultés.
Les générateurs de sites statiques promettent une solution simple : écrire des articles en Markdown, conserver l’en-tête et le pied de page en un seul endroit, et obtenir un site rapide composé de fichiers ordinaires. Pour de nombreux débutants, la réalité se révèle être un mur de jargon inexplicable, une console qui affiche des traces d’erreur, ainsi que des documents qui supposent des années de connaissances préalables. Ce guide comble cette lacune en partant de zéro. Vous apprendrez quels compétences il faut posséder avant de commencer, ce que signifie réellement chaque terme récurrent dans la documentation des générateurs, comment les éléments d’un projet Eleventy typique s’assemblent, d’où proviennent ces outils, et quelles alternatives plus légères existent lorsque les solutions populaires semblent trop complexes.
Avant de choisir un générateur : les compétences nécessaires
Les ressources suivantes fonctionnent bien, plus ou moins dans cet ordre. Créez de petits sites temporaires au fur et à mesure plutôt que de considérer cette liste comme un devoir à terminer en premier.
- HTML : « HTML for People » est destiné aux lecteurs n’ayant aucune expérience en programmation. Lorsque vous souhaitez en savoir plus sur les éléments sémantiques et l’accessibilité, passez au module de MDN sur la structuration du contenu.
- CSS : Le module de base sur le stylisme de MDN aborde des concepts tels que le modèle de boîte et la mise en page. Si les exercices pratiques vous conviennent mieux, le cours de freeCodeCamp sur la conception responsive explique l’HTML, le CSS, l’accessibilité ainsi que la conception responsive (pratiquement adaptée aux appareils mobiles).
- JavaScript : Le module sur les scripts de MDN fait suite naturellement à ses contenus sur l’HTML et le CSS, tandis que le programme de JavaScript de freeCodeCamp offre une alternative interactive.
Si vous préférez un point central plutôt qu’une collection d’ressources, la section d’apprentissage de MDN couvre HTML, CSS, JavaScript ainsi que les bases des navigateurs dans un seul programme pédagogique. web.dev, The Odin Project et w3schools constituent d’autres options.
Gardez une perspective réaliste : un site personnel est généralement un projet amateur. Les solutions atypiques et les erreurs font partie du processus, et chaque petit site que vous terminez vous permet d’acquérir de nouvelles compétences que vous pourrez intégrer au suivant.
Le vocabulaire que les documents sur les sites statiques supposent que vous connaissez
La documentation des générateurs a tendance à utiliser une douzaine de termes comme s’il s’agissait de choses que tout le monde apprend dès la naissance. Cette section les définit en langage simple et les illustre à l’aide d’un petit fichier concret issu d’un projet Eleventy (11ty).
Balises, style et comportement : HTML, CSS et JavaScript
HTML (HyperText Markup Language) décrit la structure et le sens d’un document : titres, paragraphes, liens, images, listes. Ce n’est pas un langage de programmation. Il ne peut prendre aucune décision ni rien répéter de lui-même ; il se contente d’indiquer ce qui se trouve sur la page. La plus petite page utile comprend un doctype, une <head> contenant un ensemble de caractères et un titre, ainsi qu’une <body> contenant du contenu. Notez que rien ici ne contrôle les couleurs ou les polices, de sorte que le navigateur utilise ses styles par défaut.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My First Page</title>
</head>
<body>
<h1>Hello, world!</h1>
<p>This page has a <a href="https://brennan.day">link</a> and a list:</p>
<ul>
<li>HTML gives a page its structure.</li>
<li>There's no CSS yet, so this is all default styling.</li>
</ul>
</body>
</html>Copy
En enregistrant ce fichier sous le nom index.html et en l’ouvrant dans n’importe quel navigateur, vous obtenez une page web fonctionnelle, sans besoin de serveur. (Le Copy situé après la balise de fermeture est un reste d’un bouton de copie et ne fait pas partie du marquage.)
CSS (Feuilles de style en cascade) contrôle la manière dont cette structure est présentée : couleurs, espacements, typographie, ainsi que la façon dont le layout s’adapte à différentes tailles d’écran. Les règles suivantes définissent une police à empattements, limitent la largeur du texte pour que les lignes restent lisible, centrent la colonne avec des marges automatiques, et attribuent à la page un arrière-plan chaleureux ainsi que des couleurs de texte sombres. Le titre dispose quant à lui de sa propre règle de couleur.
body {
font-family: Georgia, serif;
max-width: 35rem;
margin: 2rem auto;
padding: 0 1rem;
background: #fff2ce;
color: #02005d;
}
h1 {
color: rebeccapurple;
}Copy
En plaçant ces règles à l’intérieur d’un élément <style> dans le <head> de la page précédente, on modifie son apparence sans changer un seul mot du HTML. Cette séparation du contenu de la présentation est un principe fondamental qui caractérise tous les générateurs de sites statiques.
JavaScript est le langage de programmation que les navigateurs exécutent. Il ajoute des fonctionnalités : réagir aux clics, modifier le contenu, récupérer des données. C’est aussi le moyen le plus simple de rendre une page simple lourde et lente ; par conséquent, pour un site personnel, il est préférable de l’utiliser uniquement là où son utilisation est clairement justifiée. Le fragment suivant trouve un élément ayant pour identifiant surprise, écoute les clics sur cet élément et remplace le texte du premier <h1> lorsqu’un clic a lieu.
const button = document.querySelector("#surprise");
button.addEventListener("click", () => {
document.querySelector("h1").textContent = "JavaScript did this!";
});Copy
Pour que cela fonctionne, la page doit disposer d’un <button id="surprise"> correspondant. Sans celui-ci, querySelector renvoie null et l’appel à addEventListener provoque une erreur, ce qui constitue souvent le premier bug rencontré.
JavaScript est également présent du côté du générateur, et non seulement dans le navigateur. De nombreux SSG sont eux-mêmes écrits en JavaScript et l’utilisent pour exécuter la compilation ou évaluer les templates. Eleventy permet même qu’un template entier soit un fichier JavaScript : la chaîne de caractères retournée par la fonction exportée devient alors le contenu de la page.
// hello.11ty.js
module.exports = function () {
return "<h1>Hello from JavaScript!</h1>";
};Copy
Cet exemple utilise CommonJS module.exports. Les versions récentes d’Eleventy prennent également en charge la syntaxe des modules ES (export default), il convient donc de vérifier quel style est utilisé dans la documentation de votre version installée.
Que signifient réellement « static », « build » et « output »
- Statique décrit la manière de livrer le contenu : le serveur transmet un fichier tel quel, sans générer de réponse nouvelle pour chaque visiteur. Une page statique peut tout de même contenir du JavaScript et être modifiée puis réutilisée. Ce terme ne signifie pas pour autant que la page est ennuyeuse ou figée à jamais.
- Dynamique signifie que quelque chose calcule la réponse au moment de la demande. Un système de gestion de contenu classique interroge une base de données et assemble une page à chaque visite. Un magasin en ligne en est un exemple typique, car les stocks et les paniers d’achat changent constamment.
- générateur de sites statiques est un programme qui lit du matériel source (contenu Markdown, modèles, paramètres de configuration, images et autres ressources) pour produire un ensemble prêt à l’emploi de fichiers HTML, CSS, JavaScript et images que n’importe quel hébergeur statique peut servir.
_site/, public/ ou dist/. Vous ne les modifiez généralement pas manuellement, car la prochaine construction les écrase.localhost:8000 et reconstitue souvent automatiquement le site dès que vous enregistrez un fichier source.Fichiers de configuration et données du site
- fichier de configuration contient des paramètres applicables à l’ensemble du site, tels que le nom du site, l’URL de base, les menus, le répertoire de sortie ou les options de flux. Les noms et les formats varient selon l’outil :
config.yml,hugo.toml,eleventy.config.jset d’autres. - YAML est un format de données convivial pour les humains, couramment utilisé en configuration et dans le front matter. Il permet d’exprimer des chaînes de caractères, des nombres, des listes ainsi que des correspondances clé-valeur. L’indentation a une signification précise, de sorte qu’un espace mal placé peut empêcher la compilation.
- paire clé-valeur correspond à une configuration composée d’un nom et d’une valeur, comme
title: Mon article. En YAML, un ensemble de ces paires est appelé une mise en correspondance. - paramètre ou une option est une configuration que l’on transmet à une commande ou que l’on insère dans un fichier. Le flag
--serveque vous rencontrerez plus tard en est un exemple.
Dans Eleventy, les fichiers situés dans le dossier _data deviennent des données globales accessibles à chaque template. Le fichier src/_data/site.json contient les informations affichées aux visiteurs : le nom du site, une brève description, l’auteur, l’URL publique et la langue.
{
"name": "My Cool Blog",
"description": "Where I write about whatever interests me.",
"author": "Your Name",
"url": "https://example.com",
"language": "en"
}
Chaque clé se transforme en variable de template. Un layout contenant {{ site.name }} affichera la valeur « My Cool Blog », ce qui signifie que pour changer le nom du site, il suffit de modifier une seule ligne ici au lieu de chercher sur chaque page. Jekyll conserve ce type d’informations dans config.yml et Hugo dans hugo.toml ; l’idée est identique, seuls les fichiers diffèrent. Notez que JSON est strict : une virgule à la fin après la dernière entrée constitue une erreur de syntaxe, détail qui deviendra important plus tard dans ce guide.
Layouts, parties partagées et génération de templates
- Un modèle est un fichier réutilisable qui définit la structure d’une page et contient des espaces réservés pour les éléments qui peuvent changer.
- layout est un modèle pour toute une page : la déclaration du langage, le
<head>, l’en-tête, la zone de contenu principale et le pied de page. - Un fragment est un petit élément réutilisable tel qu’une barre de navigation, un pied de page ou un bloc de métadonnées d’article. Une instruction include sert à intégrer un tel fragment dans un autre fichier.
- Un langage de modélisation est la syntaxe permettant d’afficher des variables, de parcourir des données et de prendre des décisions au sein des modèles. Liquid, Nunjucks et les modèles Go en sont des exemples courants.
- Une règle conditionnelle est une règle du type oui/non dans un modèle, par exemple « afficher l’image principale uniquement lorsque l’article en définit une ».
Le layout de base ci-dessous, _includes/layouts/base.njk, est écrit en Nunjucks. Le titre combine le titre propre de la page avec le nom global du site ; deux balises include insèrent les parties correspondant à l’en-tête et au pied de page, et le corps de la page rendu est affiché à l’intérieur de <main>.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ title }} | {{ site.name }}</title>
</head>
<body>
{% include "partials/header.njk" %}
<main>
{{ content | safe }}
</main>
{% include "partials/footer.njk" %}
</body>
</html>
Le filtre | safe est important. Nunjucks échappe automatiquement les données affichées, ce qui transformerait l’HTML d’une publication en balises visibles. En marquant content comme sûr, on indique au moteur que cette chaîne de caractères est fiable, c’est-à-dire de l’HTML déjà rendu. N’utilisez-le que pour du contenu que vous contrôlez.
Les fragments eux-mêmes ne sont que des morceaux d’HTML qui peuvent utiliser des variables et inclure d’autres fragments. L’en-tête renvoie à la page d’accueil en utilisant le nom du site et charge la navigation ; cette dernière est une simple liste de liens ; le pied de page affiche une ligne de droits d’auteur indiquant l’auteur provenant des données du site.
<!-- partials/header.njk -->
<header>
<a href="/">{{ site.name }}</a>
{% include "partials/nav.njk" %}
</header>
<!-- partials/nav.njk -->
<nav>
<a href="/">Home</a>
<a href="/archive/">Archive</a>
<a href="/about/">About</a>
</nav>
<!-- partials/footer.njk -->
<footer>
<p>© 2026 {{ site.author }}</p>
</footer>
Voici comment les éléments se connectent. Lorsqu’une publication indique layout: base.njk dans son contenu préliminaire, Eleventy rend la publication, puis place le résultat à l’endroit où se trouve {{ content | safe }} dans le layout, et chaque balise include est remplacée par son fragment correspondant. En modifiant la navigation une seule fois, toutes les pages du site l’adoptent lors de la prochaine compilation. Éliminer cette maintenance basée sur le copier-coller est la raison principale d’existence des SSG. Une petite précaution : l’année affichée dans le pied de page est codée en dur, donc elle ne s’actualisera pas automatiquement à moins de la remplacer par une variable.
Fichiers de contenu, Markdown et métadonnées en tête
- fichier de contenu est un fichier source pour une page ou une publication. Markdown est le format le plus courant, mais de nombreux générateurs acceptent également HTML, du texte brut ou d’autres formats.
- Markdown est un langage de balisage léger dans lequel la ponctuation représente la structure :
#pour les titres, des astérisques pour l’emphase, des tirets pour les listes. Le générateur le convertit en HTML. - Métadonnées en tête est un bloc de métadonnées situé tout en haut d’un fichier de contenu, généralement délimité par deux lignes composées de trois tirets. Il peut contenir un titre, une date, des étiquettes, le nom du layout ou un indicateur de brouillon.
- Métadonnées sont des informations descriptives concernant un contenu : titre, auteur, date de publication, étiquettes, description, URL canonique ou layout choisi.
Le fichier posts/my-first-post.md ci-dessous combine tout cela. Le front matter YAML définit un titre, une date, deux tags, un layout et un indicateur de brouillon. Le corps mélange du Markdown ordinaire avec une syntaxe de template de style Nunjucks qui affiche le titre et montre conditionnellement une phrase.
---
title: My First Post
date: 2026-09-22
tags:
- posts
- cats
layout: post.njk
draft: false
---
Welcome to my blog! This paragraph is **Markdown**.
This post is called "{{ title }}".
{% if draft %}
This sentence only appears while the post is a draft.
{% endif %}
Eleventy lit le front matter avant d’afficher quoi que ce soit. La clé layout sélectionne le modèle d’encadrement, l’étiquette posts ajoute le fichier à une collection nommée posts (que la page d’archive peut parcourir), et date définit l’ordre de tri adapté au blog. Tout ce qui se trouve après les tirets de fermeture constitue le corps du contenu. Comme draft vaut false ici, la phrase conditionnelle n’apparaît pas dans le résultat. Notez qu’une clé draft n’a pas de signification intégrée dans Eleventy ; l’exclusion des versions en brouillon d’une version finale relève de votre propre configuration.
Hébergement, backends et termes de déploiement
- Hébergement désigne le service ou la machine qui stocke vos fichiers de sortie et les rend accessibles sur Internet. Il s’agit d’une question distincte de l’écriture du site et du contrôle de version.
Gestion des versions en une seule page
- Gestion des versions : enregistre les modifications apportées aux fichiers au fil du temps afin de pouvoir consulter l’historique, comparer les versions, revenir en arrière et collaborer.
- Git est un programme de gestion des versions en particulier. Il fonctionne entièrement sur votre ordinateur et n’a pas besoin de service en ligne pour suivre l’historique.
- répertoire (repo) est un dossier de projet dont Git gère l’historique.
- commit est un instantané sauvegardé des modifications, généralement accompagné d’un message les décrivant.
- serveur distant est une autre copie du répertoire, souvent hébergée sur Codeberg, GitHub, GitLab ou votre propre serveur.
- Push envoie vos commits locaux vers un serveur distant ; pull récupère des commits depuis ce serveur et les fusionne avec votre copie locale.
- Les services de hébergement Git stockent les dépôts et ajoutent souvent un suivi des problèmes, une revue de code ainsi que des builds automatisés. Ils sont pratiques, mais ce ne sont pas Git lui-même, et Git fonctionne très bien sans eux.
Publier un nouveau post avec Git depuis la ligne de commande nécessite quatre commandes. La première s’exécute une seule fois par projet ; les trois autres forment le processus quotidien consistant à préparer un fichier, enregistrer une capture d’écran et l’envoyer vers le serveur distant.
git init # turn this folder into a repository (once)
git add posts/new-post.md # stage the file for your next commit
git commit -m "Add new post" # save a snapshot with a message
git push # copy your commits to the remoteCopy
En pratique, git push ne fonctionne que dopo avoir configuré un serveur distant, par exemple avec git remote add origin <url>, et le premier push d’une branche nécessite généralement git push -u origin main ou une commande similaire. Une fois cela configuré, un simple git push suffit.
D’où viennent les générateurs de sites statiques
Avec ce vocabulaire en place, l’histoire devient plus claire, car chaque nouvelle génération d’outils a ajouté l’un des concepts mentionnés ci-dessus.
La séparation de l’écriture du marquage existe bien avant l’expression « générateur de sites statiques ». HSC, pour « HTML Sucks Completely », était un préprocesseur HTML publié par Thomas Aglassinger en 1996. Il offrait déjà des fonctions d’inclusion, de conditions et de validation de liens, environ une décennie avant que cette catégorie n’ait un nom.
Pendant la fin des années 1990 et les années 2000, la plupart des personnes souhaitant créer un blog choisissaient des services dynamiques hébergés tels que Blogger, LiveJournal ou Open Diary, ou installaient des logiciels basés sur une base de données comme WordPress. Movable Type, une plateforme en Perl créée par Ben et Mena Trott en 2001, a emprunté une voie différente : chaque fois qu’on publiait via son interface web, le blog était régénéré sous forme de fichiers HTML statiques. Les utilisateurs n’avaient jamais affaire à une console, mais les lecteurs recevaient des pages statiques. Cela a permis aux personnes qui ne sauraient jamais taper une commande de compilation d’exploiter les avantages du format statique.
Nanoc est apparu en 2007, créé par Denis Defreyne après que les systèmes de gestion de contenu Ruby se soient révélés bien trop lents sur son serveur virtuel de 96 MB. Il a introduit des maquettes, des métadonnées par page, la prise en charge de Markdown et des plugins. En décembre 2008, Tom Preston-Werner, co-fondateur de GitHub, a publié Jekyll, motivé par son insatisfaction vis-à-vis des moteurs de blog lourds. Jekyll s’est inspiré des idées de Nanoc et a ajouté deux fonctionnalités clés : du front matter en YAML en tête de chaque fichier de contenu, ainsi que la possibilité d’utiliser directement des fichiers Markdown comme blog sans configuration supplémentaire. GitHub Pages a été lancé en même temps en tant que hébergement statique gratuit, et cette combinaison a contribué plus que tout autre facteur à populariser les SSG.
Presque tout ce qui a suivi n’a été qu’une réinterprétation du même modèle dans d’autres langages. Octopress, désormais abandonné, et Middleman ont poursuivi la lignée Ruby. Pelican est basé sur Python, tandis que Hyde s’appuie sur Laravel.
Steve Francia a lancé Hugo en juillet 2013, un programme écrit en Go distribué sous forme de binaire compilé unique. Contrairement à Jekyll, il n’y avait pas d’environnement Ruby à installer ni de versions de gem à synchroniser, et sa vitesse de compilation, mesurée en secondes même pour des sites comptant des milliers de pages, est devenue sa caractéristique principale.
Au cours de la fin de 2017, Zach Leatherman a publié Eleventy (11ty), une alternative flexible à Jekyll qui fonctionne avec JavaScript et s’installe via npm. Jekyll vous lie à Liquid ; Eleventy accepte une longue liste de formats de templates :
- Marcage et contenu : HTML brut (
.html), Markdown (.md) et MDX (.mdx)
.11ty.js, TypeScript (.ts), JSX (.jsx) et WebC (.webc).njk), Handlebars (.hbs), Mustache, EJS, Haml et Pug.scss)De nombreux générateurs dans ce répertoire n’ont pas connu de mise à jour depuis des années, ce qui est souvent acceptable pour un site personnel. Un site statique ne présente pas de code côté serveur ni de base de données accessibles aux visiteurs, ce qui élimine la surface d’attaque la plus courante des blogs dynamiques. Si une nouvelle version de votre générateur ajoute des fonctionnalités que vous n’aimez pas, vous pouvez continuer à utiliser l’ancienne, qui continuera de générer le même site. La précaution à prendre est que « pas d’actualisations » ne signifie pas « aucun risque » : les dépendances utilisées lors de la compilation, la machine qui exécute cette compilation ainsi que tout JavaScript tiers que vous intégrez méritent toujours une attention particulière, et un outil non entretenu pourrait finir par ne plus s’installer correctement sur un système d’exploitation ou un environnement de langage plus récent.
Git résout deux problèmes, mais vous n’en avez besoin d’aucun
Les guides destinés aux débutants vous conseillent presque toujours d’utiliser Git. Cela s’explique en partie par une habitude chez les développeurs, mais aussi par des raisons historiques : Jekyll, le premier SSG largement adopté, a vu le jour en tant que projet GitHub. Héberger sur GitHub, Codeberg ou GitLab répond à la question « Où se trouvent mes fichiers ? » par « Dans le répertoire ». Des services comme Neocities ou Nekoweb y répondent différemment : vous téléchargez vos fichiers via le site.
Au sein d’un hébergement basé sur Git, comme Codeberg Pages ou GitLab Pages, même les modifications effectuées via l’interface web deviennent des commits et sont envoyées en arrière-plan. Vous utilisez Git que vous tapiez ou non une commande Git.
Si vous hébergez le site vous-même, les fichiers se trouvent sur votre propre ordinateur, généralement dans un répertoire comme /var/www/html sous Linux. Sur une machine communautaire partagée telle qu’un serveur Tildeverse, ils se situent dans le dossier public de votre compte ; une méthode courante consiste à compiler localement puis à utiliser rsync pour copier le résultat sur l’ordinateur partagé, où il est servi automatiquement.
Il est utile de séparer les deux tâches effectuées par Git dans ces configurations :
- conserver un historique des versions, afin de pouvoir annuler une modification erronée et voir ce qui a changé et quand
- transférer les fichiers compilés à l’endroit d’où ils seront servis
Aucun de ces deux travaux ne requiert strictement Git. rsync, un client FTP ou un formulaire de téléchargement via un navigateur permettent tous de publier un site parfaitement bien, et des sauvegardes ordinaires peuvent suffire pour conserver l’historique dans un petit projet personnel. Git est populaire car il gère ces deux tâches en même temps, ne coûte rien et s’intègre à des hébergements gratuits, ce qui en fait le choix le plus simple plutôt qu’une exigence.
La différence entre le diagramme idéal et la mise en œuvre réelle
Sur le papier, l’architecture d’un générateur de blogs est presque ennuyeusement ordonnée :
- les articles sont des fichiers Markdown dans un dossier
posts/ - un modèle situé dans le dossier
layout/les affiche - cet modèle assemble des fragments HTML provenant de
partials/, tels queheader.htmletfooter.html
config.yml (ou équivalent) situé dans la racine du projet contient des paramètres applicables à l’ensemble du site, tels que le nom ou les couleurs"2024-03-14-my-post-title.md"La partie que le diagramme omet, c’est le mécanisme de fonctionnement. Pour transformer ces dossiers en un site affiché, par exemple dans _site/, il faut un environnement d’exécution de langage de programmation afin de faire fonctionner le générateur, et chaque maillon de cette chaîne représente un point où des problèmes peuvent survenir.
Les outils courants s’efforcent de cacher cela derrière une seule commande, comme hugo build ou npx @11ty/eleventy --serve. L’option --serve de la commande Eleventy lance un serveur de développement local et récompile le site chaque fois que vous enregistrez un fichier source, au lieu de se contenter d’une compilation unique puis de s’arrêter. Cet échange rapide de feedback est ce qui fait que modifier un site statique donne l’impression d’être presque aussi immédiat que modifier une page en ligne.
Les plateformes de déploiement appliquent la même logique au cloud. Netlify, ou Coolify qui peut être auto-hébergé, exécute votre construction sur une machine distante, détecte le générateur que vous utilisez, exécute la commande appropriée et publie le dossier de sortie à une adresse telle que yoursitename.netlify.app. Conceptuellement, c’est identique à l’envoi d’un HTML manuscrit sur Neocities pour obtenir yoursitename.neocities.org, à la différence que la construction a lieu sur leur machine. Des workflows similaires sont proposés par surge.sh, GitHub Pages, Vercel ainsi que par Cloudflare avec son produit Pages ; le choix dépend de l’importance que vous accordez à la facilité d’utilisation par rapport à l’indépendance vis-à-vis des grandes plateformes. Si vous souhaitez voir un flux de déploiement complet du début à la fin, notre guide sur l’envoi d’un petit site web vers Cloudflare présente un exemple concret.
Pourquoi une seule virgule en fin de ligne peut tout gâcher
Toutes ces commodités reposent sur des hypothèses : vos fichiers sont corrects, le moteur de langage est installé proprement, et vous vous sentez à l’aise dans un terminal. Les développeurs surestiment fréquemment la fréquence de cette dernière compétence, un point aveugle que cette bande dessinée XKCD illustre bien.
La compilation est également fragile. Une petite erreur de syntaxe dans un fichier important, aussi mineure qu’une virgule supplémentaire, peut empêcher complètement l’installation ou la compilation. Pire encore, le message d’erreur provient généralement du moteur de langage ou du parseur sous-jacent, et non du générateur, ce qui le rend formulé en termes de langage de programmation plutôt que de votre site. Exemple concret : un fichier JSON contenant une virgule en fin de ligne après sa dernière propriété provoque l’échec d’une compilation Netlify, avec un historique d’erreur du parseur qui ne mentionne jamais le fichier réel en termes accessibles aux débutants.
Face à un tel résultat, de nombreuses personnes décident raisonnablement d’écrire du HTML à la main, de passer à un CMS hébergé ou même d’abandonner l’idée d’avoir un site. Ce dernier scénario représente la véritable perte. Quelques habitudes permettent de réduire les risques d’y arriver :
- exécuter la compilation localement avec le serveur de développement avant de publier, afin que les erreurs apparaissent d’abord sur votre propre écran
- modifier une chose à la fois, de sorte que la dernière modification soit le suspect évident en cas de problème
- lire l’erreur du bas vers le haut et chercher un nom de fichier ainsi qu’un numéro de ligne, qui constituent généralement la véritable piste
- vérifier le JSON et le YAML à l’aide d’une extension d’édition ou d’un outil de linting, car ces formats causent une grande partie des erreurs de compilation chez les débutants
- faire des commits fréquemment pour conserver toujours accès à la dernière version fonctionnelle
Apprendre en modifiant un modèle de base
Une méthode éprouvée pour apprendre à utiliser un générateur consiste à prendre un modèle ou thème prêt à l’emploi, à commencer à le développer, puis à le modifier petit à petit jusqu’à bien comprendre chaque fichier. Finalement, vous en saurez suffisamment pour en créer un propre de zéro. De bons modèles à cette fin présentent plusieurs caractéristiques : une documentation claire, un petit nombre de fichiers, ainsi qu’un emplacement bien défini pour le contenu et les paramètres. Voici des exemples typiques :
- un modèle Hugo où les articles se trouvent dans
/postet où la personnalisation du site a lieu danshugo.toml, éventuellement avec des fonctionnalités IndieWeb telles que microformats2 et une carte h préconstruite - un modèle Eleventy où les articles se trouvent dans
/postset où les informations du site sont stockées dans un fichier de données commesite.js - un modèle Jekyll où les articles se trouvent dans
/_postset où les paramètres sont stockés dans_config.yml
Des starters délibérément simples constituent un avantage pour l’apprentissage. Lorsque le stylisme est minimal, la structure devient facile à comprendre, et tout le travail de conception vous est laissé pour que vous le réalisiez vous-même.
Générateurs minuscules avec presque aucune pièce mobile
Hugo, Eleventy et Jekyll sont les choix populaires, mais il existe toute une famille de générateurs très petits destinés à ceux qui souhaitent comprendre l’ensemble de l’outil en une après-midi.
- barf, abréviation de « blogs are really fun », est un script shell d’environ 170 lignes créé par btxx, issu de blog.sh de Karl Bartel. Il ne comporte ni en-tête ni système de templates. Vous écrivez des fichiers Markdown, exécutez
make build, puis téléchargez le dossierbuild/généré à l’aide de rsync. Des flux RSS sont générés automatiquement ; le script fonctionne nativement sur OpenBSD, macOS et Linux, et son feuille de style ne compte que quatre lignes. Le README ainsi qu’une démonstration en direct montrent à quoi ressemble le résultat.
bb.sh, composé d’environ 1 000 lignes et ne nécessitant aucune dépendance en dehors des outils standards Unix tels que date, grep, sed et head. Carlos Fenollosa a écrit la première version en 2011 et a expliqué sa méthode dans un article de blog à l’époque ; il était encore maintenu au moment où ce texte a été rédigé. Une fois bb.sh placé dans le répertoire public de votre serveur, l’instruction ./bb.sh post crée une nouvelle entrée. Les brouillons, les étiquettes, le format Markdown et RSS fonctionnent sans aucune étape d’installation. Une branche communautaire, bashblog-ng, ajoute davantage de fonctionnalités.Quelques autres outils à connaître :
- ssg est un script shell conforme à POSIX développé par Roman Zolotarev, qui a inspiré plusieurs outils de cette liste ; pyssg en est une réécriture en Python.
- sw, écrit en C, est un framework web délibérément minimaliste, et sa branche simple-static le réduit encore davantage à ce que son README décrit comme le générateur de sites statiques le plus simple que son mainteneur puisse imaginer.
- makesite.py est l’équivalent Python de barf et bashblog, comptant moins de 130 lignes, créé par Sunaina Pai sur le principe que le code lui-même constitue la documentation. Il n’y a pas de couche de configuration ; on lit le script et on le modifie directement.
Aucun d’eux n’approche l’ensemble de fonctionnalités de Hugo ou Eleventy, et c’est justement le but. Ce qu’ils sacrifient en termes de plugins et de formats de templates, ils le compensent par la transparence : lorsque quelque chose ne fonctionne pas, tout le programme tient sur votre écran.
Si vous êtes prêt à sortir complètement du web, publier sur le protocole Gemini constitue une autre option. Les pages Gemini utilisent un format de texte simple servi tel quel, il n’y a donc souvent rien à générer du tout.
Points clés
- Apprenez d’abord à écrire une page manuellement ; un générateur automatise des tâches répétitives que vous devriez déjà maîtriser.
- La plupart des confusions liées aux SSG proviennent du vocabulaire. Une fois que la source, le résultat, la construction, le layout, les parties partielles et le front matter sont clairs, la documentation de chaque outil se lit de manière similaire.
- Les layouts, les parties partielles et les fichiers de données globaux existent pour que tout changement effectué une fois apparaisse partout lors de la prochaine construction.
- Git fournit un historique et une voie de publication, mais rsync, FTP ou le téléchargement via un navigateur constituent des alternatives valables pour un site personnel.