Nunjucks est un moteur de templates léger, efficace et parfaitement adapté à la génération de pages HTML statiques maintenables. Dans cet article, je vous explique pourquoi il peut devenir un atout majeur dans vos projets web, notamment si vous souhaitez éviter les CMS tout en gardant une structure claire et modulaire.
💡 1. Pourquoi un moteur de templates en 2025 ?
En 2025, le développement web évolue dans un écosystème très contrasté. D’un côté, les CMS (WordPress, Drupal…) restent omniprésents, avec leur lot de fonctionnalités et de plug-ins. De l’autre, on observe une remontée en puissance des sites statiques, portés par des besoins croissants en performance, sécurité et contrôle du code source.
Si vous avez déjà géré un site avec plusieurs pages HTML, vous avez probablement été confronté à ce dilemme : gagner du temps avec un CMS… au prix d’un empilement de couches techniques, ou conserver la légèreté du HTML statique, tout en sacrifiant la maintenabilité.
⚠️ Les limites d’un CMS dans un contexte moderne
Un CMS offre une interface pratique, mais il devient vite inadapté dans certains contextes professionnels, notamment :
- si vous souhaitez versionner le contenu dans Git,
- intégrer votre site dans une chaîne CI/CD,
- ou garder un contrôle total sur la structure et la sécurité.
Ces plateformes sont souvent lourdes à sécuriser, difficiles à faire évoluer proprement, et mal intégrées aux workflows des développeurs.
🧱 Le HTML statique : simple mais rigide
À l’inverse, le HTML statique est rapide, léger, sécurisé et facilement hébergeable. Mais cette simplicité a une contrepartie : la duplication de code devient vite un cauchemar. Un changement de menu ? Il faut éditer chaque fichier. Une mise à jour de pied de page ? Même chose.
💡 C’est ici que Nunjucks intervient, en proposant une solution intermédiaire idéale : le confort du HTML statique, la maintenabilité d’un système modulaire.
🧰 2. Qu’est-ce que Nunjucks ?
Nunjucks est un moteur de templates JavaScript développé par Mozilla, inspiré de Jinja2 (Python). Il permet de générer du HTML modulaire, avec des blocs réutilisables et une logique simple, tout en restant très léger.
Il peut s’utiliser côté serveur avec Node.js, ou intégré dans des outils de génération statique comme Gulp, Webpack ou Eleventy.
🧠 Une syntaxe claire et expressive
Nunjucks propose une syntaxe élégante, proche de nombreux langages de templates :
{{ variable }}
pour injecter des valeurs,{% include %}
,{% block %}
et{% extends %}
pour la structure,{% if %}
,{% for %}
pour la logique.
{% extends "base.njk" %}
{% block content %}
<h1>Bienvenue</h1>
<p>{{ message }}</p>
{% endblock %}
⚖️ Comparatif avec d’autres moteurs
Nunjucks se situe à mi-chemin entre des moteurs très simples comme Handlebars, et des solutions plus intégrées comme Twig ou Liquid. Nous verrons plus loin une comparaison détaillée selon les contextes d’usage (Java, Node.js, PHP, statique/dynamique…).
En résumé, Nunjucks est un compromis efficace : assez léger pour les sites statiques, mais suffisamment puissant pour structurer des pages complexes.
🔧 3. Mon cas d’usage : Osmodev
Au départ, le site Osmodev reposait sur une seule page HTML, simple et suffisante pour présenter mon activité. Mais avec l’arrivée de nouveaux besoins – comme proposer une formation complète – j’ai dû progressivement ajouter des pages :
- 📩 une page d’inscription à la newsletter,
- 🎓 une page de préinscription à la formation,
- ℹ️ une page à propos,
- 📁 une page de références ou portfolio,
- 🌍 et leurs équivalents en anglais.
Très vite, j’ai été confronté à plusieurs difficultés :
- chaque nouvelle page nécessitait de dupliquer des blocs HTML (menu, footer, balises meta…)
- il fallait penser à insérer manuellement les bons scripts Matomo pour le suivi analytique
- et tout était à refaire pour chaque version linguistique
Il devenait clair qu’une approche plus structurée s’imposait. C’est à ce moment-là que j’ai intégré Nunjucks pour modulariser mon HTML, centraliser les données et automatiser la génération de toutes les variantes de chaque page.
💡 Objectif : rester sur du HTML… mais modulaire
Je ne voulais pas installer un CMS ni complexifier mon architecture avec un framework complet. En revanche, je voulais :
- centraliser les blocs communs (
header
,footer
,meta tags
, etc.), - intégrer mes propres données YAML (URL, titres, configurations spécifiques),
- automatiser la génération des fichiers HTML finaux sans m’éloigner de Git.
Nunjucks s’est imposé naturellement grâce à sa syntaxe simple, sa compatibilité Node.js, et sa facilité d’intégration dans mon workflow.
🧪 Exemple concret : pour chaque page, je déclare unprefix
(ex.newsletter
,preinscription
), et Nunjucks va chercher automatiquement les URL correspondantes dans mon fichierurls.yml
. Cela me permet de générer dynamiquement la balise<link rel="canonical">
et les versionshreflang
FR/EN sans copier-coller.
🛠️ Workflow de génération
Voici comment je l’ai intégré dans mon environnement :
- 🗂️ Structure des fichiers :
templates/base.njk
: layout principal avec blocs modifiablespartials/
: composants réutilisables (ex. formulaire, menu, bloc CTA…)pages/*.njk
: pages à compiler
- 📦 Compilation via
nunjucks.render
dans un script Node.js personnalisé - 🧾 Données spécifiques chargées via des fichiers
.yml
(par page) - 📤 Intégration à mon système de build (avec Make et rsync sur mon VPS)
Ce système reste extrêmement léger : pas de serveur, pas de base de données, tout est généré en local et mis en ligne via un simple rsync
ou un dépôt Git.
📌 Résultats obtenus
Avant | Après avec Nunjucks |
---|---|
HTML dupliqué entre les pages | Blocs partagés via {% include %} |
Erreurs fréquentes dans les URLs & balises SEO | Balises générées dynamiquement depuis urls.yml |
Difficulté à maintenir la version anglaise | Version multilingue gérée par prefix + conditions |
Aucune automatisation de publication | Script de compilation + déploiement avec Make |
En résumé : Nunjucks m’a permis de construire une structure HTML propre, modulaire et facilement maintenable, sans complexifier ma stack technique. C’est un outil qui fait parfaitement le lien entre simplicité statique et organisation professionnelle.
⚙️ 4. Mise en place simple avec Nunjucks
Si vous souhaitez intégrer Nunjucks dans un projet HTML statique, la mise en place est à la fois rapide et souple. Vous n’avez pas besoin d’un framework complet ou d’un environnement complexe. Un simple projet Node.js suffit.
📁 Structure de base recommandée
.
├── pages/
│ └── index.njk
├── templates/
│ ├── base.njk
│ └── header.njk
├── partials/
│ └── footer.njk
├── data/
│ └── urls.yml
└── build.js
Cette organisation permet de séparer :
- les layouts (
templates/
) - les composants réutilisables (
partials/
) - les pages finales à générer (
pages/
) - les données dynamiques (
data/
)
🧪 Exemple de template de base
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="UTF-8">
<title>{{ title }}</title>
<link rel="canonical" href="{{ canonicalUrl }}">
</head>
<body>
{% include "partials/header.njk" %}
<main>
{% block content %}{% endblock %}
</main>
{% include "partials/footer.njk" %}
</body>
</html>
Vos pages spécifiques (par exemple index.njk
) peuvent ensuite étendre ce layout :
{% extends "templates/base.njk" %}
{% block content %}
<h1>Bienvenue sur Osmodev</h1>
<p>Ce site a été généré avec Nunjucks.</p>
{% endblock %}
🔧 Script de génération HTML
Un script Node.js très simple permet de compiler toutes les pages :
// build.js
const nunjucks = require("nunjucks");
const fs = require("fs");
nunjucks.configure(["pages", "templates", "partials"], { autoescape: true });
const pages = ["index.njk"];
pages.forEach(page => {
const rendered = nunjucks.render(page, {
title: "Page d’accueil",
canonicalUrl: "https://www.osmodev.fr/"
});
fs.writeFileSync(`dist/${page.replace(".njk", ".html")}`, rendered);
});
Ce script peut bien sûr être enrichi pour charger dynamiquement des fichiers YAML, boucler sur tous les fichiers `.njk`, gérer des variables d’environnement (locale, mode prod/dev), etc.
🔁 Intégration dans un workflow automatisé
Une fois en place, vous pouvez inclure cette génération dans votre processus de build ou de déploiement :
- Git pour le versioning
- Makefile ou npm scripts pour l’automatisation
- Rsync, SCP ou Jenkins pour le déploiement automatisé
💡 Mon scriptbuild.js
peut aussi, selon les options, déclencher un déploiement automatique viarsync
vers mon serveur distant. Cela me permet de tout faire en une ligne :node build.js --deploy
.
En résumé : Nunjucks vous permet de garder un environnement HTML statique, versionné, mais structuré et automatisé. L’entrée en matière est rapide, et l’outil reste suffisamment souple pour s’adapter à vos projets existants.
🎥 Bientôt en vidéo
Je prépare une courte vidéo dans laquelle je vous montre concrètement comment j’ai installé Nunjucks sur mon VPS, mis en place l’arborescence des fichiers, et automatisé la génération de mes pages HTML.
Vous y verrez notamment le contenu de base.njk
, d’un fichier partials
, d’un YAML, ainsi que l’exécution complète du script build.js
.
Cette démonstration sera bientôt disponible sur osmodev.fr et sur la chaîne YouTube associée.
🚀 5. Les avantages dans mon workflow
L’un des principaux intérêts de Nunjucks, au-delà de sa syntaxe claire, réside dans sa capacité à s’intégrer facilement à un environnement de travail moderne et automatisé. Il s’adapte aussi bien aux petits projets qu’à des workflows plus complexes utilisés en production ou en formation.
🔄 Moins de duplication, plus de fiabilité
Grâce à l’utilisation des {% include %}
, {% block %}
et {% macro %}
, j’ai pu éliminer presque toute la duplication de code dans mes pages HTML.
Résultat : des pages plus cohérentes, plus faciles à maintenir, et une réduction drastique des erreurs manuelles.
🌐 Internationalisation simplifiée
J’ai structuré mes pages pour prendre en compte plusieurs langues (français, anglais), en me basant sur un prefix
(déjà mentionné un peu plus tôt) (ex. newsletter
, preinscription
), ce qui me permet d’automatiser :
- la génération des balises
hreflang
, - les balises
canonical
etx-default
, - les URL alternées (via
urls.yml
).
🧪 Exemple : il me suffit de définir une seule entrée commenewsletter:
dans mon fichierurls.yml
avec ses variantes FR, EN et x-default. Ensuite, grâce à un petit bloc Nunjucks conditionnel, toutes les balises<link rel="alternate">
sont générées automatiquement dans le HTML final, sans duplication de code.
Pour chaque page structurante comme newsletter.njk
, je prévois un fichier de données YAML par langue :
fr/newsletter.yml
pour la version française, et en/newsletter.yml
pour la version anglaise.
Ainsi, le contenu est séparé de la structure, et chaque version peut être générée dynamiquement avec les bonnes données.
🔒 Compatible avec un workflow Git + CI/CD
Contrairement à un CMS classique, tous les fichiers utilisés par Nunjucks sont des fichiers texte versionnables : HTML, YAML, JS. Cela me permet :
- de suivre chaque modification dans Git,
- d’automatiser la génération via
make
,npm
ou un outil d’intégration continue comme Jenkins, - et de publier mes pages sans dépendance à une base de données ou un backend.
⚙️ Lien direct avec mon environnement de développement
Je peux tester une nouvelle landing page, ajuster un bloc, changer une URL ou un style CSS… en local, avec un simple node build.js
.
En quelques secondes, je visualise le résultat sans serveur, sans déploiement, sans délai.
📈 Un outil qui évolue avec moi
Au fil des projets, j’ai pu enrichir progressivement ma bibliothèque de blocs réutilisables (formulaires, teasers, CTA, tableaux comparatifs, encadrés de citation, etc.), ce qui me permet aujourd’hui de produire rapidement des pages cohérentes et élégantes.
En résumé : Nunjucks s’intègre naturellement dans un environnement de travail moderne, versionné, automatisé, et orienté productivité. C’est un outil qui offre une grande souplesse sans renoncer à la rigueur ou à la performance.
Mais si Nunjucks s’intègre parfaitement à mon usage, il est important de rester lucide sur ses limites et de connaître les outils alternatifs selon les cas de figure.
🧭 6. Limites et alternatives
Comme tout outil, Nunjucks n’est pas une solution universelle. Il est important d’en connaître les limites afin de l’utiliser dans les contextes pour lesquels il est réellement adapté.
⛔ Ce que Nunjucks ne fait pas
- Ce n’est pas un CMS : il ne fournit aucune interface de gestion de contenu accessible à des non-développeurs.
- Il ne fonctionne pas nativement côté client : il est pensé pour être exécuté lors du build, pas dans le navigateur.
- Il ne propose pas de système de routing ou de serveur intégré (contrairement à Next.js, Eleventy, etc.).
En d’autres termes, Nunjucks est idéal si vous :
- gérez un site statique généré en local ou en CI,
- versionnez tout votre contenu dans Git,
- maîtrisez vos propres outils de déploiement.
🛠️ Alternatives selon les usages
Outil | Langage | Cas d’usage principal | Limites |
---|---|---|---|
Nunjucks | JavaScript (Node.js) | Sites statiques personnalisés, modulaires | Pas d’interface utilisateur |
Eleventy | JavaScript | Générateur de site complet, extensible | Plus complexe à configurer |
Handlebars | JavaScript | Templates simples, rapide à prendre en main | Syntaxe limitée |
Thymeleaf | Java | Applications web côté serveur (Spring Boot) | Couplé au backend, pas adapté aux sites statiques |
Twig | PHP | Sites avec back-end Symfony, Drupal | Requiert un serveur PHP |
Liquid | Ruby | Compatible GitHub Pages, Jekyll | Syntaxe rigide, peu évolutive |
🎯 Quand éviter Nunjucks
Si vous développez un site pour un client non technique qui souhaite modifier son contenu en ligne, ou si vous avez besoin d’une API dynamique, il vaut mieux vous tourner vers :
- un CMS statique comme Netlify CMS, Sanity, ou Directus,
- un framework dynamique comme Next.js ou Astro (avec composants réactifs),
- ou une solution hybride comme Eleventy avec CMS en backend headless.
En résumé : Nunjucks excelle dans les projets où le contrôle du code, la simplicité du déploiement, et la modularité priment sur l’édition en ligne ou la logique métier dynamique. Il faut l’envisager comme un moteur de templating puissant et minimaliste, parfaitement adapté à une approche développeur-first.
🧾 7. Conclusion
Dans un contexte où la simplicité, la sécurité et la maintenabilité sont devenues des exigences de premier ordre, Nunjucks s’impose comme une solution efficace pour structurer et générer des pages HTML statiques de manière modulaire et professionnelle.
Il permet de sortir du dilemme classique entre CMS lourds et code HTML dupliqué, en proposant une alternative élégante, légère, et parfaitement intégrable dans un workflow de développement moderne.
Dans mes projets, Nunjucks m’a permis :
- d’automatiser la génération de pages multilingues,
- de maintenir des blocs communs sans duplication,
- d’intégrer le tout à un processus Git + CI/CD minimaliste et fiable.
💡 Si vous êtes développeur ou formateur, que vous gérez vous-même vos pages HTML ou que vous souhaitez automatiser une documentation, une série de landing pages ou un site vitrine, Nunjucks vous fera gagner un temps précieux.
Il n’est pas un CMS, ni un générateur de site complet, mais il vous permet de garder le contrôle total sur vos fichiers, votre structure et vos données, tout en introduisant un vrai confort de développement.
Et surtout, il s’intègre dans vos outils habituels : Node.js
, YAML
, Make
, Git
, ou vos éditeurs comme IntelliJ ou VS Code.
📘 À venir
Dans un prochain article, je vous montrerai comment j’ai intégré Matomo, une alternative libre à Google Analytics, au sein de ces pages générées avec Nunjucks, tout en respectant une politique de sécurité stricte (CSP, cookies, RGPD, etc.).
👉 Rester informé des prochains articles