Wiki et docs as code : BookStack, Wiki.js, Zensical, Docusaurus

Un wiki est un site où l'équipe écrit et range sa documentation directement dans le navigateur ; le docs as code consiste à écrire la documentation en Markdown dans un dépôt Git, à la relire comme du code et à la publier automatiquement en site web. Ce chapitre compare les deux approches, présente les outils (BookStack, Wiki.js, Zensical, MkDocs, Docusaurus) dans leur version de novembre 2026 et montre comment créer un site de documentation.

Où ranger la documentation ?

Le choix dépend des auteurs autant que des lecteurs. La documentation d'une application, écrite par les développeurs, vit naturellement dans son dépôt. Les procédures d'exploitation, écrites par des techniciens qui ne passent pas leurs journées dans Git, vivent bien dans un wiki. Ce qui compte : une seule source de vérité par document, et des liens entre les lieux.

Le wiki : écrire dans le navigateur

Un wiki d'équipe moderne offre un éditeur visuel (et souvent un éditeur Markdown), une recherche dans tout le contenu, l'historique des révisions de chaque page (qui a changé quoi, quand, avec retour possible à une version antérieure), des droits de lecture et d'écriture, des pièces jointes et des diagrammes.

Son défaut est connu : sans règles, il se remplit de pages en double, orphelines ou périmées. Trois règles le gardent utile :

1. Une structure décidée avant d'écrire, alignée sur les lecteurs : un espace « Procédures du service informatique », un espace « Guides des salariés », un espace « Infrastructure ».
2. Un propriétaire par page, nommé en tête, chargé de la tenir à jour.
3. Une date de relecture : chaque procédure est relue au moins une fois par an, ou à chaque changement de l'outil qu'elle décrit.

BookStack

BookStack est un wiki libre (licence MIT), écrit en PHP avec le cadriciel Laravel, qui range le contenu comme une bibliothèque : des étagères regroupent des livres, divisés en chapitres, eux-mêmes faits de pages. Cette structure imposée est son atout : on sait toujours où ranger une page.

• Version : la série 26.09, publiée en septembre 2026, suivie de correctifs de sécurité. Le projet publie plusieurs versions par an et des correctifs de sécurité fréquents : un wiki se met à jour comme n'importe quelle application.
• Prérequis : PHP 8.2 ou plus récent, MySQL 8.0 ou plus récent ou MariaDB 10.6 ou plus récent, un serveur web. Des scripts d'installation existent pour Ubuntu, et des images Docker sont maintenues par des tiers (dont LinuxServer.io).
• Édition : un éditeur visuel par défaut, ou un éditeur Markdown avec aperçu en direct ; un éditeur de diagrammes draw.io intégré aux pages.
• Droits : des rôles, et des permissions réglables jusqu'à la page.
• Authentification : comptes locaux, ou annuaire LDAP, SAML 2.0 et OpenID Connect pour se connecter avec les comptes de l'entreprise.

Wiki.js

Wiki.js est un wiki libre (licence AGPL-3.0) écrit en Node.js, dont l'arborescence est libre : tu crées tes dossiers et tes pages comme tu veux.

• Versions : la branche 2.5, la plus déployée, a été la version stable pendant des années. La version 3.0 est sortie en version stable au début de novembre 2026, après une longue période de développement ; la 3.2.0 a suivi quelques jours plus tard.
• Prérequis de la version 3 : Node.js 26, et une base PostgreSQL (versions 17 et 18) : c'est la seule base prise en charge. L'installation par Docker est fortement recommandée.
• Migration : on ne met pas une 2.x à jour sur place. On met d'abord la 2.x à jour vers sa dernière version, on exporte le contenu, puis on l'importe dans une nouvelle installation 3.x.

Le choix de Sorbier. Antoine Mercier retient BookStack : l'équipe maîtrise déjà MariaDB, la structure en livres convient aux salariés comme aux techniciens, et la connexion LDAP permet d'utiliser les comptes de l'Active Directory. La note de choix de Moussa, avec sa grille de comparaison, est au chapitre 3. Le wiki est installé sur srv-wiki, dans le VLAN 21 (procédure du même chapitre). Trois étagères : Service informatique (lecture et écriture pour les trois membres du service informatique), Guides des salariés (lecture pour tous, écriture pour le service informatique), Direction (lecture pour la direction).

Docs as code : la documentation traitée comme du code

Le docs as code applique à la documentation les outils et les habitudes du développement : elle est écrite en Markdown, rangée dans un dépôt Git (souvent dans un dossier docs/ à côté du code), relue par pull request, vérifiée automatiquement, puis publiée en site web à chaque fusion.

Ce qu'on y gagne :

• La documentation suit les versions du code : la branche qui ajoute une route à l'API ajoute aussi sa documentation, dans la même pull request. Le relecteur refuse la fusion si l'une manque.
• Chaque changement est relu, comme le code.
• L'historique dit qui a changé quoi, et permet de retrouver la documentation de n'importe quelle version livrée.
• Des vérifications automatiques : liens cassés, syntaxe Markdown, orthographe, construction du site. Un lien mort bloque la fusion au lieu de frustrer un lecteur.

Ce qu'il faut accepter : les auteurs doivent connaître Git, et le contenu est moins facile à modifier « en deux clics ». Beaucoup d'équipes combinent les deux : docs as code pour l'application, wiki pour l'exploitation et les utilisateurs.

Les générateurs de sites de documentation en 2026

Un générateur transforme un dossier de fichiers Markdown en site web statique : navigation, recherche, thème clair et sombre, coloration du code. Le paysage a beaucoup bougé en 2025 et 2026 ; voici où il en est en novembre 2026.

D'autres outils existent selon l'écosystème : Sphinx pour les projets Python (il génère aussi la documentation à partir des docstrings), VitePress dans l'écosystème Vue, mdBook dans l'écosystème Rust.

Créer un site de documentation avec Zensical

Zensical s'installe avec pip dans un environnement virtuel Python (Python 3.11 ou plus récent) :

mkdir doc-api-parc && cd doc-api-parc
python3 -m venv .venv
source .venv/bin/activate        # sous Windows : .venv\Scripts\activate
pip install zensical
zensical new .
zensical serve

zensical new . crée le squelette du projet : le fichier de configuration zensical.toml (avec des commentaires qui décrivent les réglages), une page d'accueil docs/index.md, une page d'exemple de la syntaxe et un workflow GitHub Actions .github/workflows/docs.yml qui publie le site. zensical serve lance un aperçu sur http://localhost:8000, reconstruit à chaque enregistrement : tu écris dans VS Code, le navigateur se met à jour.

Il reste à :

1. écrire tes pages dans docs/ (une page par sujet, des noms de fichiers en minuscules avec des tirets) ;
2. générer le site final avec zensical build, ou laisser le workflow le faire à chaque push sur la branche principale ;
3. sur GitHub, activer la publication dans Settings > Pages, avec GitHub Actions comme source.

Pour un projet MkDocs existant, Zensical sait construire le site à partir du mkdocs.yml ; une partie seulement des extensions de MkDocs est prise en charge, donc teste avant de migrer.

Avec Docusaurus, la démarche est la même avec les outils de Node.js (Node.js 20 au minimum ; installe une version LTS maintenue, 24 ou 26) :

npx create-docusaurus@latest doc-api-parc classic
cd doc-api-parc
npm run start

Le site s'ouvre sur http://localhost:3000, les pages s'écrivent dans docs/, et npm run build produit le site statique dans le dossier build/.

Exercices