Prise en main de Zensical
Depuis un peu moins d'un an, j'utilise MkDocs avec le plugin Material for MkDocs pour mon site web, mon blog et mes supports de cours. Après avoir passé quelques semaines à tester une flopée de moteurs de documentation, j'ose affirmer haut et fort que Material for MkDocs constitue sans doute la meilleure solution pour publier de la documentation technique sur le web.
Sous le capot, Material for MkDocs est une extension au moteur MkDocs, qui s'est transformé en véritable framework puissant et bien documenté au fil des années. Le souci, c'est que le moteur MkDocs sur lequel repose Material for MkDocs fait partie de ces projets Open Source maintenus avec les pieds, qui ignore les rapports de bug et adopte une attitude hostile envers les projets tiers. Si vous voulez en savoir plus, jetez un œil à cet article.
MkDocs est mort, vive Zensical
Martin Donath - le créateur de Material for MkDocs - en a eu ras le bol de l'attitude erratique et ouvertement hostile du projet MkDocs sur lequel repose son extension. Il a décidé de tout casser pour recommencer à zéro. Ce qui est une excellente nouvelle, parce qu'il fait ça très bien. Au passage, il en a profité pour en faire un projet 100 % libre, puisque Material for MkDocs était publié sous double licence.
Zensical est un framework de documentation propre et extrêmement bien documenté. Il se suffit à lui tout seul, c'est-à-dire qu'il vient remplacer la combinaison MkDocs + Material for MkDocs. Au moment où j'écris ces lignes, on en est à la version 0.0.36. C'est officiellement une application en version alpha, mais ne vous laissez pas induire en erreur par la version. Il manque certes une poignée de fonctionnalités pour atteindre une rétro-compatibilité totale avec Material for MkDocs, mais dans l'état actuel des choses, Zensical offre une base solide pour tous vos projets de documentation.
Grise, cher ami, est toute théorie
Pour vous présenter Zensical, j'ai décidé de vous rédiger un petit tuto de prise en main par la pratique. Concrètement, je vais utiliser Zensical pour créer un site de HOWTOs techniques publié sur GitLab Pages, en partant de zéro. Suivez le guide.
Installation
Pour installer Zensical et toutes ses dépendances dans des versions compatibles, je passe par un environnement virtuel Python :
$ python3 -m venv ~/.venv/zensical
$ source ~/.venv/zensical/bin/activate
(zensical) $ pip install --upgrade pip
(zensical) $ pip install zensical
Vu qu'il y a des nouvelles versions très régulièrement, c'est bien de savoir faire la mise à jour :
Voici la commande pour quitter l'environnement virtuel :
À chaque fois qu'on voudra travailler avec Zensical, il faudra réactiver l'environnement :
Et si jamais vous souhaitez supprimer votre installation, c'est très simple aussi :
Initialiser un projet
Je me connecte à GitLab et je crée un dépôt howtos :
Je récupère ce dépôt :
J'initialise un projet Zensical :
$ zensical new .
$ ls -lA
total 36
drwxrwxr-x 2 kikinovak kikinovak 4096 26 avril 08:13 docs
drwxrwxr-x 8 kikinovak kikinovak 4096 26 avril 08:11 .git
drwxrwxr-x 3 kikinovak kikinovak 4096 26 avril 08:13 .github
-rw-rw-r-- 1 kikinovak kikinovak 6005 26 avril 08:11 README.md
-rw-rw-r-- 1 kikinovak kikinovak 14843 26 avril 08:13 zensical.toml
Zensical génère le site statique dans un répertoire site/ à la racine du
projet. Je crée un fichier .gitignore pour exclure d'emblée cette
arborescence :
GitHub vs. GitLab
Le répertoire .github nouvellement créé contient la configuration toute faite
du pipeline pour GitHub :
Pour ma part, j'ai une préférence marquée pour GitLab pour toute une série de raisons.1 Je vais donc me débarrasser de cette arborescence inutile :
À ce stade je peux déjà ajouter les nouveaux fichiers :
TOML vs. YAML
Material for MkDocs utilisait le fichier mkdocs.yml pour centraliser la
configuration. Zensical adopte le langage TOML (Tom's Obvious Minimal
Language), qui est bien documenté ici.
Le fichier zensical.toml est amplement documenté. Avant de modifier quoi que
ce soit, je vais en faire une copie de sauvegarde et générer un fichier par
défaut sans les commentaires :
$ cp -v zensical.toml zensical.orig
'zensical.toml' -> 'zensical.orig'
$ grep -Ev '^#|^$|[ ]{4}#' zensical.orig > zensical.toml
$ cp -v zensical.toml zensical.bak
'zensical.toml' -> 'zensical.bak'
$ git add zensical.*
$ git commit -m "Configuration par défaut"
$ git push
Keep It Simple Stupid
Cette dernière manipulation n'est pas vraiment nécessaire et correspond
juste à ma manière de faire les choses. Rien ne vous empêche d'éditer
directement le fichier zensical.toml avec les commentaires.
Je lance le serveur de développement local :
$ zensical serve
Serving /home/kikinovak/GitLab/howtos/site on http://localhost:8000
Build started
+ /markdown/
+ /
J'ouvre le site local à l'adresse http://localhost:8000 :
Publier le projet sur GitLab Pages
Avant d'aller plus loin dans le peaufinage du projet, on va publier le projet
tel quel sur GitLab Pages. Pour commencer, je crée un fichier .gitlab-ci.yml
à la racine du projet :
pages:
stage: deploy
image: python:latest
script:
- pip install zensical
- zensical build --clean
pages:
publish: site
rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
J'ajoute ce fichier à mon projet et je valide :
Il reste une petite modification à faire sur GitLab. J'ouvre le projet, je vais dans Deploy > Pages > Domains & settings et je décoche Use unique domain pour éviter de me retrouver avec une URL un peu baroque :
Ensuite, je clique sur Build > Pipelines dans le menu à gauche et je vérifie si le déploiement s'est bien déroulé :
Partant de là, à chaque commit vers la branche par défaut (en l'occurrence
main), le site statique est automatiquement construit et déployé.
Dorénavant, les pages de mon projet s'affichent à l'adresse https://kikinovak.gitlab.io/howtos.
Configuration de base
J'ai le choix entre les deux thèmes classic et modern :
Le thème classic est une réimplémentation du thème par défaut de Material
for MkDocs.
Je configure le nom du site :
La description du site apparaîtra dans l'en-tête HTML du site généré :
Ce n'est pas une mauvaise idée de spécifier explicitement l'URL du site :
L'auteur du site, c'est moi :
J'ajoute une mention légale :
Voici ma configuration pour l'instant :
[project]
site_name = "HOWTOs"
site_description = "Ma documentation technique sous forme de HOWTOs"
site_url = "https://kikinovak.gitlab.io/howtos/"
site_author = "Nicolas Kovacs"
copyright = "© 2026 Nicolas Kovacs"
[project.theme]
variant = "modern"
language = "en"
...
À ce stade, je peux déjà jeter un œil sur tous les réglages que j'ai modifiés par rapport à la configuration originale :
$ diff zensical.bak zensical.toml
2,7c2,6
< site_name = "Documentation"
< site_description = "A new project generated from the default template project."
< site_author = "<your name here>"
< copyright = """
< Copyright © 2026 The authors
< """
---
> site_name = "HOWTOs"
> site_description = "Ma documentation technique sous forme de HOWTOs"
> site_url = "https://kikinovak.gitlab.io/howtos/"
> site_author = "Nicolas Kovacs"
> copyright = "© 2026 Nicolas Kovacs"
8a8
> variant = "modern"
J'enregistre les modifications :
J'ouvre le projet sur GitLab, je me rends dans Build > Pipelines et je surveille le déploiement de ce commit :
Une fois que le statut bascule vers Passed, je peux ouvrir https://kikinovak.gitlab.io/howtos pour voir les changements.
Définir la palette utilisée
Zensical supporte deux palettes de couleurs :
-
default(clair) -
slate(sombre)
Repérez le petit bouton en haut de la page juste à côté du champ de recherche. Il permet de basculer entre les deux modes. Son fonctionnement est défini dans cette partie du fichier de configuration :
[[project.theme.palette]]
scheme = "default"
toggle.icon = "lucide/sun"
toggle.name = "Switch to dark mode"
[[project.theme.palette]]
scheme = "slate"
toggle.icon = "lucide/moon"
toggle.name = "Switch to light mode"
Pour ma part, j'ai une préférence marquée pour le mode clair. Je peux donc désactiver le mode sombre comme ceci :
En français s'il vous plaît
Le projet Zensical est disponible dans toutes les langues courantes et moins courantes. Pour afficher le site en français, il suffit de régler le paramètre correspondant :
Ajouter un logo
Pour ajouter un logo personnalisé, je crée d'abord un répertoire qui recevra les images :
Je range le logo de mon entreprise dans ce répertoire :
$ ls -lh docs/img/
total 8,0K
-rw-rw-r-- 1 kikinovak kikinovak 5,5K 26 avril 10:47 microlinux-logo.png
Zensical me permet d'utiliser ce logo dans l'en-tête comme ceci :
En temps normal le logo dans l'en-tête est un lien vers la page d'accueil
définie dans site_url. Je peux changer ce comportement :
Ajouter une icône de favori
Pour compléter la personnalisation de mon site, j'ajoute une icône de favori (favicon) dans mes fichiers :
$ ls -l docs/img/
total 24
-rw-r--r-- 1 kikinovak kikinovak 15406 11 janv. 11:34 favicon.ico
-rw-rw-r-- 1 kikinovak kikinovak 5609 26 avril 10:47 microlinux-logo.png
Je définis son utilisation comme ceci :
Voici mon logo et mon icône de favori dans l'en-tête du site :
Configurer la navigation
Pour expliquer la navigation par la pratique, il nous faut d'abord un peu de
contenu. Admettons que je veuille publier cette documentation sous forme d'une
série de HOWTOs succincts. Pour ce faire, je vais créer une série de pages et
les ranger dans le répertoire docs :
-
Installation :
installation.md -
Initialiser un projet :
initialisation.md -
Publier sur GitLab Pages :
gitlab-pages -
Configuration de base :
configuration.md
$ tree docs/
docs/
├── configuration.md
├── gitlab-pages.md
├── img
│ ├── favicon.ico
│ └── microlinux-logo.png
├── index.md
├── initialisation.md
├── installation.md
└── markdown.md
2 directories, 8 files
Pour l'instant je renseigne uniquement le titre de chaque page. Je m'occuperai du contenu en temps et en heure. Voilà ce que ça donne :
J'en conclus que dans la configuration par défaut, Zensical crée un menu de navigation en se basant sur la structure des fichiers et en les classant par ordre alphabétique. Ce n'est pas vraiment ce que je veux.
Un peu d'ordre dans tout ça
Pour avoir un peu plus de contrôle sur la navigation, je peux définir une structure explicite dans la configuration :
[project]
nav = [
"index.md",
"markdown.md",
"installation.md",
"initialisation.md",
"gitlab-pages.md",
"configuration.md"
]
C'est déjà mieux, puisque les pages apparaissent dans l'ordre voulu. Pour l'instant, Zensical définit les entrées de menu en se basant sur le titre de chaque page.
Peaufiner les titres du menu
La prochaine étape consiste à définir les titres du menu comme ceci :
[project]
nav = [
{"Accueil" = "index.md"},
{"Markdown en 5 minutes" = "markdown.md"},
{"Installation de Zensical" = "installation.md"},
{"Initialiser un projet" = "initialisation.md"},
{"Publier sur GitLab Pages" = "gitlab-pages.md"},
{"Configuration de base" = "configuration.md"}
]
Ajouter des icônes
Les entrées de menu des deux pages par défaut arborent des petites icônes assez sympathiques. Comment faire pour obtenir la même chose pour nos propres pages ?
Zensical permet de fournir des méta-informations dans l'en-tête de chaque page, notamment pour définir l'icône censée symboliser la page. Voici à quoi ça peut ressembler :
Ou encore :
---
icon: simple/gitlab
---
Publier le projet sur GitLab Pages
==================================
Où trouver toutes ces icônes ?
Zensical intègre des milliers d'icônes librement utilisables. Pour en savoir plus, jetez un œil à la documentation officielle. Par ailleurs, la documentation de Material for MkDocs offrait un moteur de recherche pour icônes assez pratique, et que j'utilise encore très régulièrement pour mes publications.
Voilà mon nouveau menu dans toute sa splendeur :
C'est déjà pas mal. Il ne me reste plus qu'à résoudre un problème. Mon site de HOWTOs ne sera pas uniquement dédié au framework Zensical. Avec le temps, je compte ajouter tout un tas de HOWTOs dans des domaines aussi variés que les distributions Linux, la programmation shell, la virtualisation et les conteneurs, etc. Comment faire pour organiser tout ça de manière à ce que ça reste lisible ?
Ajouter une section
Pour commencer, je vais ranger toute ma documentation sur Zensical dans un répertoire nouvellement créé à cet effet :
$ tree docs/
docs/
├── img
│ ├── favicon.ico
│ └── microlinux-logo.png
├── index.md
├── markdown.md
└── zensical
├── configuration.md
├── gitlab-pages.md
├── initialisation.md
└── installation.md
3 directories, 8 files
Je modifie ma configuration pour refléter cette nouvelle organisation :
[project]
nav = [
{"Accueil" = "index.md"},
{"Markdown en 5 minutes" = "markdown.md"},
{"Zensical" = [
{"Installation" = "zensical/installation.md"},
{"Initialiser un projet" = "zensical/initialisation.md"},
{"Publier sur GitLab Pages" = "zensical/gitlab-pages.md"},
{"Configuration de base" = "zensical/configuration.md"}
]}
]
C'est déjà beaucoup mieux, et cette solution peut convenir parfaitement à des projets de documentation de petite envergure.
En revanche, si votre documentation compte plusieurs dizaines voire même des centaines de pages, il faudra trouver une autre solution pour garder un peu de lisibilité.
Les onglets de navigation
Ici, Zensical nous facilite la tâche avec les onglets de navigation prêts à l'emploi. Il suffit de l'activer dans la configuration :
[project.theme]
features = [
"announce.dismiss",
"content.code.annotate",
"content.code.copy",
"content.code.select",
"content.footnote.tooltips",
"content.tabs.link",
"content.tooltips",
"navigation.footer",
"navigation.indexes",
"navigation.instant",
"navigation.instant.prefetch",
"navigation.path",
"navigation.sections",
"navigation.tabs",
"navigation.top",
"navigation.tracking",
"search.highlight",
]
À présent, la section apparaît dans un nouvel onglet de navigation en haut de la page.
Et maintenant ?
Vous disposez à présent d'une base solide pour rédiger et publier votre propre documentation. Certes, je ne vous ai pas fait un exposé exhaustif de toutes les fonctionnalités de Zensical, mais c'est déjà un bon point de départ.
Pour aller plus loin, j'ai trois conseils à vous prodiguer :
-
Zensical utilise le Markdown sous le capot, un langage de balisage que tout le monde utilise mais que peu de gens connaissent vraiment. Prenez le temps de bien apprendre le Markdown.
-
Zensical offre des possibilités de mise en forme qui vont bien au-delà de ce que propose le Markdown classique. Pour en avoir un premier aperçu, jetez un œil à la page
index.mdgénérée par défaut dans notre projet. -
Toutes ces possibilités sont décrites en détail dans l'excellente documentation officielle de Zensical. Lisez-la.
-
Pour deux raisons très exactement : c'est libre et ça n'appartient pas à Microsoft. ↩
La rédaction de cette documentation demande du temps et des quantités significatives de café espresso. Vous appréciez ce blog ? Offrez un café au rédacteur en cliquant sur la tasse.
