Héberger et publier de la doc avec Zensical

Zensical

Zensical est un générateur de sites de documentation statiques. Il est développé par l'équipe qui a créé Material for MkDocs, passé en mode maintenance fin 2025 au profit de Zensical. Il transforme vos fichiers Markdown en un site web (HTML, CSS, JavaScript) que n'importe quel serveur web peut afficher, sans base de données ni langage serveur : la surface d'attaque est quasi nulle.

Compatibilité avec MkDocs

Zensical lit directement un fichier de configuration mkdocs.yml. Un projet MkDocs Material existant peut donc être construit avec Zensical sans réécrire sa configuration, à condition de ne pas dépendre de plugins non pris en charge.

Fonctionnalités principales

• Simplicité : quelques commandes suffisent pour créer, prévisualiser et construire un site.
• Markdown : le contenu s'écrit dans des fichiers .md, simples et lisibles.
• Personnalisation : palettes de couleurs, icônes, mode clair et sombre.
• Recherche : moteur de recherche intégré, qui fonctionne côté visiteur.
• Navigation : sans section nav dans la configuration, le menu est généré à partir de vos fichiers et dossiers.
• Extensions : coloration syntaxique, boîtes d'information, onglets, emojis, extraits de code.

Ne confondez pas deux choses qui portent le même nom. theme: name: material, ci-dessous, désigne le thème natif de Zensical : l'équipe a délibérément gardé le nom material pour rester compatible avec les extensions de thème existantes. Ce n'est pas un appel à l'ancien paquet mkdocs-material, qui lui atteint sa fin de vie le 5 novembre 2026. Votre chaîne reposant sur zensical seul (et non sur mkdocs + mkdocs-material), cette échéance ne la concerne pas, et vous n'avez rien à changer dans votre configuration.

Deux options si besoin : theme: variant: classic retrouve l'apparence exacte de l'ancien Material ; des thèmes tiers packagés (Catppuccin, par exemple) s'installent par pip et se référencent par leur nom (theme: name: catppuccin).

Ce n'est pas obligatoire, mais un environnement virtuel isole les dépendances de chaque projet et évite les conflits de versions avec le Python du système. Il garantit aussi que vous savez exactement quelle version de Zensical tourne. Attention : un environnement virtuel est lié à la version de Python qui l'a créé. Après une montée de version de votre distribution, il faudra le recréer (voir la section Maintenance).

Cette commande crée le dossier docs avec deux pages d'exemple, un fichier de configuration zensical.toml et un dossier .github (un workflow de publication sur GitHub Pages). Elle n'écrase jamais un fichier existant.

Dans ce tutoriel, j'utilise le format mkdocs.yml, déjà très répandu. Si les deux fichiers existent, zensical.toml est prioritaire : il faut donc le supprimer, ainsi que le dossier .github si vous ne publiez pas sur GitHub Pages.

L'architecture de votre dossier devrait ressembler à ceci :

doc.mon_domaine.fr
├─ docs/
│  ├─ index.md
│  ├─ Windows_Server.md
│  ├─ Windows_Client.md
│  └─ Mes_notes_techniques.md
└─ mkdocs.yml

• docs contient vos fichiers Markdown, qui forment le contenu du site.
• index.md est la page d'accueil.
• mkdocs.yml est le fichier de configuration à créer à l'étape suivante.

Référez-vous à la documentation officielle : https://zensical.org

Avec MkDocs Material, le plugin privacy téléchargeait les polices et les emojis pour les héberger sur votre serveur (conformité RGPD). Zensical ne le propose pas, et ignorerait sa configuration sans prévenir : le navigateur de vos visiteurs irait alors chercher ces ressources chez Google et sur un CDN.

La solution est de ne rien charger d'extérieur : font: false utilise les polices du système du visiteur, et le générateur to_alt affiche les emojis en caractères Unicode. Le contrôle de la section suivante permet de le vérifier.

Les modifications, ajouts et suppressions de fichiers sont détectés automatiquement : il n'est pas nécessaire de relancer le serveur.

Zensical traite vos fichiers Markdown et votre configuration, puis génère un site complet (HTML, CSS, JavaScript) dans le dossier site. L'option --clean vide le cache, et --strict arrête la construction au moindre avertissement (lien cassé, option erronée), ce qui évite de publier un site défectueux.

Un site statique n'a besoin que de peu de choses, autant le protéger correctement :

# Dans le bloc http de nginx.conf : ne plus annoncer la version de Nginx
server_tokens off;

# Dans le bloc server (HTTPS) du site
add_header Strict-Transport-Security "max-age=86400" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header Referrer-Policy "no-referrer" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

• Commencez HSTS avec une durée courte (ici un jour), puis augmentez-la une fois que tout fonctionne.
• Un add_header placé dans un bloc location annule ceux du bloc parent : il faut alors les y répéter.
• Comme votre site n'appelle aucune ressource externe, vous pouvez mettre en place une politique Content-Security-Policy très stricte. Testez-la d'abord avec l'en-tête Content-Security-Policy-Report-Only, qui ne bloque rien mais signale dans la console du navigateur ce qui serait refusé.
• Vérifiez toujours avant de recharger : sudo nginx -t && sudo systemctl reload nginx.