Zensical

tu--- title: Zensical, Static Site Generator tags: - docs - SSG

Zensical est un site static generator (SSG). Il vous permet de générer un site statique à partir de fichier markdown. Il devrait à terme prendre en charge le standard CommonMark. L'équipe derrière le projet possède une dizaine d'années d'expérience sur les problématiques de SSG. Combiné avec un développement en Rust, l'équipe a toutes les chances de mettre en oeuvre un moteur robuste et efficace.

A l'origine de Zensical¶

En novembre 2025¹ l'auteur Martin Donath de material for mkdocs annonce la sortie de Zensical. Suite aux déboires de la maintenance de mkdocs². Les développeurs de material y ont vu une opportunité de s'affranchir du moteur mkdocs afin de lever toutes les contraintes qu'ils subissaient jusqu'à présent. Il est né du besoin d'offrir une expérience de documentation moderne et cohérente — comparable à celle fournie par Material for MkDocs — sans rester lié à l'écosystème MkDocs. Cependant, afin de financer leur travail, ils proposent du support commercial avec leur offre Zensical Spark pour faciliter la migration.

Quote

Our new approach distills a decade of experience maintaining Material for MkDocs, allowing us to professionalize and scale our efforts from a small team to a fully organized operation, while keeping the software free and open to everyone.

Viabilité¶

Commaunauté¶

Le projet material for mkdocs possède une grosse communauté. Le projet Zensical s'appuie sur cette base communautaire en facilitant la migration de mkdocs vers ce nouveau site générateur. Ce choix stratégique permet d'éviter une fuite de la communauté vers d'autres sites générateurs. Globalement des différentes discussions des projets devant migrer et de l'historique des stars github, la communauté à l'air de suivre.

Historique des Stars de material for mkdocs et Zensical avec une échelle log

Licence OpenSource¶

Au première abord, on pourrait douter sur la question du modèle économique de l'entreprise Zensical. Cependant, à la différence d'une startup qui débarque de nul part, Martin Donath a maintenu pendant 10 ans en licence MIT son projet material à travers des dons (200K/an³ à la fin). Zensical semble suivre le même état d'esprit. De la roadmap, Zensical cherche a mettre en oeuvre toutes les fonctionnalités présentes dans l'écosystème mkdocs et material for mkdocs. De mon avis, la stratégie est d'assécher les forks potentiels et l'éclatement de l'écosystème. L'équipe a recruté le développeur de mkdocstring⁴ pour porter le plugin critique. A partir de cette base solide, il est possible que Zensical passe avec un modèle Open Core si le financement ne suit pas suffisamment. Ils pourraient pivoter en se financant auprès des acteurs économiques par le développement d'extension payante pour des intégrations avec des solutions maison.

Le sujet est à surveiller mais je suis plutôt confiant que dans 6-12 mois, la licence sera toujours permissive et que l'on est à disposition la très grande majorité des fonctionnalités.

Démarrer un projet avec Zensical¶

Créons un projet de zéro avec uv¶

uv

Afin d'avoir un venv dynamique, de gérer les dépendances, je détaille le mode opératoire avec uv. Vous pouvez reproduire avec pip.⁵

créons le squelette d'un projet (on supprime le main.py)

mkdir mydemo;
cd mydemo;
uv init --name mydemo;
rm main.py

Installer Zensical:
```
uv add zensical
uv sync
```

Initialiser docs et tester un site d'exemple :

uv run zensical new
uv run zensical serve  # --port 8000

Vérifier la sortie dans votre navigateur localhost:8000

A ce stade, vous avez votre première démo d'un site statique opérationnel en local. Vous pouvez modifier les pages, elles seront rechargés dans le navigateur à la volée.

docs: Dossier source des pages Markdown (documentation à éditer).
pyproject.toml: Configuration du projet Python (métadonnées et dépendances).
README.md: Présentation du projet, instructions d'installation et usage.
site: Site statique généré (HTML/CSS/JS — sortie de build) à ajouter en .gitignore
uv.lock: Lockfile géré par uv — enregistre versions/dépendances.
zensical.toml: Configuration spécifique à Zensical (paramètres du SSG/site).

groupe de dépendance par uv

Dans le cas où votre doc cohabite avec votre code, il est judicieux de déclarer la librairie dans un groupe tiers exemple : docs. Cela optimisera le temps de build et simplifiera l'expérience de démarrage de vos tech writers si vous utilisez des lib exotiques dépendantes du hardware.

On peut déjà tirer une première conclusion, que la mise en place est d'une simplicité déconcertante. Je peux modifier l'index.md et avoir un premiere boucle feedback.

Fonctionnalités disponibles¶

zensical.toml¶

Le coeur des modifications de votre site vont être centraliser dans le zensical.toml. Certaines configurations vont suivre la pratique de convention over configuration ce qui permet d'avoir certains effets magique comme la détection automatique des nouvelles pages ajoutées appréciable pour démarrer.

navigation des pages

Cependant, tôt ou tard, il faudra déclarer l'option nav pour gérer finement l'ordre d'affichage des pages. L'ordre alphabétique a des limites si vous ne l'avez pas pris en compte par design.

contenu d'une page¶

Jusqu'à présent, vous avez probablement modifié des Readme avec un rendu par github ou gitlab.

l'interprétation markdown

a savoir que le format markdown possède plusieurs spécifications. Un Readme github n'a pas le même comportement que sur gitlab. Une spécification CommonMarkdown a émergé pour stopper les divergences. Des dissonances sont donc à prévoir si vous cherchez allier les deux mondes, lecture sur SSG et github.

Lorsque vous rédigez une page, vous devez ajouter une première section metadata de votre page. Elle vous sera très pratique à long terme. Elle vous permet de personnaliser l'expérience.

---
title: my first page
tags:
hide:
---

## my chapter
(...)

Templates, inclusions et layouts
Rebuild incrémental / mode watch

Points forts (exemples)¶

Simplicité d'usage pour les rédacteurs
Intégration des bonnes pratiques UX héritées de Material
Convention over configuration (si applicable)

Limitations¶

Écosystème de plugins plus réduit que les grands SSG
Fonctionnalités spécifiques manquantes pour sites très complexes

Annexes¶

Liens : dépôt officiel, documentation, changelog.