Refonte de la documentation MDwiki

[loup-brun]

Choisir une pile technique pour la documentation, qui ne devrait pas reposer sur du JS dans le navigateur pour être affichée.

Quelques besoins

• Documentation : la forme doit convenir en premier lieu à des contenus de documentation (et non correspondre à l’organisation visuelle/hiérarchique d’un blogue ou d’un magazine par exemple).
• i18n : prise en charge de contenus multilingues (fr / en).
• HTML-first : solution qui ne requiert pas de JavaScript pour l’affichage de documents (🚫SPA).
• Markdown : Prise en charge facile du Markdown.
• API : Possible de brancher des API tierces (par exemple, l’éventualité de connecter la documentation à la plateforme Stylo pour y gérer les contenus à même la plateforme).
• Pérennité de l’outillage : pile technique facilement reproductible (éviter les solutions reposant sur un grand nombre de dépendances, des technologies mal documentées, idiosyncrasiques qui imposent des structures non standard).

Pistes

• Hugo : générateur de site statique polyvalent avec plein de fonctionnalités, notamment une très bonne prise en charge le multilinguisme. Plusieurs thèmes existent déjà, mais une modification des thèmes sera presque certainement nécessaire, et le langage de templating de Hugo (Go HTML Templates) est un obstacle significatif qui nécessite un apprentissage non négligeable. Il n’y a pas de solution toute faite pour tirer des contenus d’une API, tout doit reposer dans les fichiers markdown du projet.
• Eleventy : générateur de site statique hybride, très configurable, écrit en JavaScript, avec accès à un très très large écosystème (plugins, bibliothèques tierces, etc.). Il n’existe pas autant de thèmes préfabriqués que pour Hugo ou Jekyll par exemple, car c’est un système relativement récent.
• Executable Books, dont MyST : écosystème JavaScript ou Python, pour produire des articles ou des livres (collections d’articles) à partir d’une vision de production de documents scientifiques.