Nouvelle tâche: Héberger la doc
Dans mes dernières pĂ©rĂ©grinations, j’ai du dĂ©ployer un nouveau site de documentation. Et pour une fois, j’ai dĂ©cidĂ© de creuser un peu le sujet avant de partir vers les poncifs du genre.
Les sites de doc sont souvent mis au second plan, bĂ©nĂ©ficiant de moins d’attention que les gros projets. MĂŞme si leurs UXs se ressemblent souvent, ils sont omniprĂ©sents sur internet, en plus d’ĂŞtre essentiels au cycle de vie d’un projet et d’offrir un très large choix de solutions.
C’est ainsi que je voulais profiter du travail sur Blackswift pour prendre un peu de recul, avant de simplement choisir celui qui a le mieux rĂ©ussi son SEO. Mes principales motivations Ă©taient d’avoir quelque chose de moderne, facilement exploitable, rapide et bien sĂ»r… On adore tous passer 2 jours Ă chercher la meilleure solution Ă un problème qui prendrait 2 petites heures Ă rĂ©soudre.
Dinosaures et Javascript
Si vous cherchez à creuser le sujet, il ne faudra pas longtemps pour vous rendre compte qu’il existe 2 grands types de solutions pour héberger votre doc:
Les projets en full javascript 👨‍💻
Avec les derniers frameworks Ă la mode, compatibles avec tout-ce-que-vous-voulez, installables en PWA (Progressive Web Apps) et bien plus encore…. Mais dont la seule consultation de la page d’accueil suffira Ă dĂ©clencher l’alerte “Consommation de donnĂ©es mobile” sur votre tĂ©lĂ©phone.
Les autres projets đź—ż
Ils tournent avec un seul script, dont les fichiers sont formatĂ©s dans un DSL (Domain Specific Language, comme le HTML ou le balisage MediaWiki) obscur, avec un numĂ©ro de version du projet Ă©crit en chiffres romains… Mais ils sont extrĂŞmement sobres en ressources et tournent sur tout et n’importe quoi.
Ce clivage est surprenant… mais compréhensible !
Après tout, soit vous voulez un outil sobre, purement utilitaire et il suffit alors d’un script pour compiler vos fichiers Markdown ou LaTeX, puis de les servir sur le web de la manière la plus rapide et légère possible.
Soit vous voulez proposer un outil plus sophistiquĂ© et dynamique. Et lĂ … il vous faudra sans doute de la rĂ©activitĂ© en front avec un framework comme React ou Vue, et possiblement un backend actif permettant d’aller chercher des donnĂ©es un peu partout. Avec ça, vous pourrez en mettre ✨plein les yeux✨ Ă vos visiteurs !
Mais quid des middle-ground, à mi-chemin entre ces deux philosophies ? Ce sont justement souvent les moins populaires. Mais j’ai décidé de creuser. Il était donc venu temps…. d’enquêter !
Il y a le bon et le mauvais framework
On peut dire qu’il y a beaucoup de solutions diffĂ©rentes. Beaucoup trop pour qu’un article les liste toutes ou mĂŞme qu’une sĂ©rie d’articles vous les dĂ©crive sans que vous ne dĂ©crochiez en cours de route.
Il me fallait donc limiter les choix et je me suis décidé à filtrer en fonction de ces principaux critères :
Léger 
Pas d’infra lourde pour le faire tourner ou de bundles javascript gigantesques.
Extensible 
Et si demain, j’ai besoin d’ajouter un composant React… et après-demain, de ne plus avoir de JS, je veux que ce soit simple Ă rĂ©aliser.
Pas trop niche 
Pour trouver facilement des infos, les technos à utiliser (Désolé mais odoc, c’est trop pour moi).
Moderne Ă maintenir 
Pas de bidouilles pour le faire fonctionner et le builder. Pas de mises à jours trop fréquentes ou trop majeures.
UX front 
Elle doit refléter les points précédents et proposer une expérience fluide et agréable pour les visiteurs. Je ne fais pas ça uniquement pour moi !
Vous avez dĂ©jĂ lu le titre de l’article… on ne va donc pas faire semblant de comparer objectivement les solutions avec ces critères (dĂ©jĂ biaisĂ©s) pour finir sur celle que j’ai choisie ! Mais il est toujours enrichissant de faire un tour d’horizon de la concurrence avant d’attaquer le vif du sujet.
Avec ces critères et suite Ă quelques recherches, j’ai pu finalement arriver Ă une shortlist de solutions viables.
Le club des cinq
Docusaurus
Docusaurus est sans doute le projet le plus en vogue de cette liste, permettant de déployer des documentations assez simplement.
Il est très intégré et populaire dans l’écosystème Javascript, tourne en React et permet de rédiger sa documentation en Markdown ou d’intégrer du contenu React.
Vitepress
Vitepress est l’équivalent de Docusaurus mais basé sur le framework Javascript Vue.
Moins populaire (mais avec le vent en poupe), il tire son nom de Vite, un outil de l’écosytème Javascript permettant d’amĂ©liorer les performances locales et d’optimiser les bundles de production. Vitepress est une solution de SSG (Static Site Generation) qui vous permettra de crĂ©er vos documentations en Markdown. Lors de l’étape de build, il compilera tout en statique.
Docsify
Docsify est un projet basé également sur Javascript et qui a la particularité de ne pas avoir d’étape de build !
Sur un site Doscify, lorsque vous explorez la documentation dans votre navigateur, au lieu de fetch des fichiers pré-rendus, vous chargez directement des fichiers Markdown et le rendu HTML se fait côté navigateur.
Mkdocs
Mkdocs est un projet Python assez répandu et qui permet assez simplement de créer votre documentation.
Comme la plupart des solutions concurrentes, une fois rédigée, la documentation est compilée sous forme de fichiers statiques à servir assez simplement et utilise en front jQuery et Bootstrap pour enrichir l’expérience.
Starlight
Starlight n’est pas une solution de documentation à proprement parler mais un template de projet Astro.
Bien que le rĂ©sultat final soit proche d’un Docusaurus, il s’en distingue surtout par la volontĂ© d’éviter au maximum le Javascript cĂ´tĂ© navigateur et le cas Ă©chĂ©ant, se permet d’être agnostique quant au framework (si vous en voulez quand mĂŞme.)
L’élu de la shortlist
Suite à ce premier écrémage, et en se basant sur les critères évoqués plus haut, mon choix s’est donc finalement porté sur 🌟 Starlight 🌟. Mais pourquoi ?
Comme évoqué succinctement plus haut, il répond à tous mes critères et offre, de mon point de vue, la proposition la plus intéressante :
LĂ©ger ?
En prod, on n’aura que nginx et un minimum de JS dans le navigateur.
Extensible ?
On peut y faire du rendu dynamique avec React, Vue, Svelte, et plus (la liste continue de s’agrandir), étendre le thème, ajouter des modules ou en développer.
Pas trop niche ?
Rédaction des docs en Markdown et complètement intégré à l’écosystème Javascript. Son évolution est liée à celle d’Astro, qui est un projet très dynamique (même si c’est pour faire des site statiques !)
Moderne Ă maintenir ?
Une stack standard Node/Javascript et une conteneurisation aisée.
UX front ?
Peu de JS en front et des fichiers statiques servis par nginx. On est pas loin du maximum, même en mode MPA (Multi-Page Application).
Ok, c’est très bien tout ça ! Mais c’est quoi au final Starlight… puisque ce n’est qu’un template de projet Astro ? Et d’abord, c’est quoi Astro ?
Questions tout à fait légitimes et je suis très heureux que vous suiviez !
Kezastro ?
Astro est un framework web dont l’objectif est de servir avant tout du contenu statique.
Si vous avez un site de réservation de billets en ligne, ce n’est pas la solution qu’il vous faut. Mais un blog personnel ou une documentation à héberger ? Vous tenez là votre champion !
Son principe de fonctionnement est exactement comme tel : il vous permet de rédiger vos pages de contenu en Markdown ou HTML ou de le fetcher depuis des sources distantes, et d’y inclure des composants d’à peu près n’importe quel framework JS. Il possède ensuite une étape de compilation pour optimiser tout cela.
Ainsi, l’idĂ©e est de faire un prĂ©-rendu de la majoritĂ© de vos pages (en SSG ou SSG+SSR). Pour garder le dynamisme dans ces pages, les zones interactives seront comme des Ă®lots, seuls endroits comportant de l’activitĂ© au milieu d’un ocĂ©an calme et immobile. C’est d’ailleurs ce nom qui a Ă©tĂ© retenu par Astro: les Islands.
Et Starlight alors ? Ce n’est qu’un template permettant de simplifier l’initialisation, la mise en page et la rédaction de contenu dans Astro. Vous créez le projet et vous n’avez plus qu’à commencer à rédiger votre documentation puis la builder et la mettre en production !
Des possibilités stellaires
Bien ! Après cette entrée en matière, on peut creuser davantage sous la surface et voir quelles sont ses principales forces, pour être certain de ne pas regretter mon choix par la suite.
Installation
Très bien documentée, comme la majorité des solutions JS modernes. Vous décollez en une seule commande (ici avec pnpm pour faire mon original) :
pnpm create astro --template starlight
Ensuite, un p’tit pnpm run dev et une visite à http://localhost:4321 . Vous êtes lancés !
La rédaction de contenu
Si, comme moi, vous n’avez besoin de rien de plus : vous n’écrirez que du Markdown agrémenté d’un peu de frontmatter pour les metadatas (position dans le menu, SEO, …) en début de fichier.
Par exemple:
---
title: DĂ©ployez un WordPress avec Helm
description: Comment déployer un chart Helm wordpress
sidebar:
order: 30
---
SSR et SSG
Par défaut, Starlight compilera vos fichiers Markdown durant le build. Mais si besoin, le SSR (Server Side Rendering) reste possible et certaines données pourront être récupérées dynamiquement.
La recherche
La recherche est sans doute la partie la plus magique: Starlight est compilé, n’a besoin que de nginx pour tourner, mais propose tout de même une recherche intelligente de contenu, sans avoir à tout charger dans le navigateur.
Comment fait-il ? Eh bien, avec Pagefind !
Pleinement intégré, lors du build du projet, il va simplement analyser vos fichiers Markdown, construire les index qu’il stockera dans des fichiers statiques. Ces fichiers seront demandés si besoin par le front lors de la recherche.
Ce qui donne une recherche extrĂŞmement performante, reposant uniquement sur des fichiers statiques !
Les traductions (i18n)
L’internationalisation est bien évidemment supportée, avec la possibilité d’avoir un fallback par défaut. Le sélecteur de langue est présent par défaut et il suffit de séparer les sources de vos docs dans un dossier par locale.
Composants
C’est du Astro, vous pouvez donc créer des composants custom ! Cela peut être des composants Astro, React, Svelte, Vue, etc.
Tout cela restera compilé “au plus simple” dans le navigateur au final, ce qui nous garantit une bonne flexibilité à ce niveau-là , sans les inconvénients.
Et bien sûr, il y a les composants fournis par défaut pour avoir des cards, encarts, icônes, badges, etc.
Impact environnemental
Alors bien entendu, les benchmarks exposĂ©s fièrement par Starlight sont biaisĂ©s et basĂ©s sur un outil en ligne de calcul d’indice carbone. Le benchmark se contente d’afficher la premier page des sites concernĂ©s : il suffit qu’il y ait des images pour voir le score exploser.
NĂ©anmoins, de part les optimisations et la manière de procĂ©der de Starlight, nous sommes complètement en accord avec leur philosophie globale qui mise sur la sobriĂ©tĂ© et la durabilitĂ© de l’outil.
Et le Devops dans tout ça ?
Pardon, je n’avais pas oubliĂ©… j’attendais juste le bon moment pour en parler !
Avec tous ses avantages côté serveur, on peut déjà s’en douter mais c’est un régal à servir et à gérer pour un DevOps.
La conteneurisation
Vous n’avez pas de Node en local ? Vous n’avez pas de… local ?Â
Bon ! Du moment que vous avez un clavier et un accès quelconque Ă Â Docker … dĂ©velopper sur Starlight ne nĂ©cessite guère plus qu’une image Docker aussi simple que la suivante :
FROM node:20.10-alpine
ENV HOST=0.0.0.0
ENV PORT=4321
EXPOSE 4321
RUN corepack enable # Installe pnpm
COPY ./ /app
WORKDIR /app
CMD ["pnpm", "dev", "--host"]
Préparer le déploiement: Le build
C’est très bien… mais comment dĂ©ployer ? On parle de tout avoir en statique … mais pour le moment, on a simplement une image Docker avec Node, le nom ressemble d’ailleurs un peu Ă nginx (si si, en plissant les yeux !) mais ça s’arrĂŞte lĂ .
Comment on passe de « ça » à nos chers fichiers statiques ? Eh bien, on build le projet.
Je ne vais pas rentrer dans les spécificités de la CI. Mais c’est assez simple : si vous voulez tout en statique, il vous suffit d’exécuter dans un environnement Node :
corepack enable # Active pnpm dans un conteneur node
pnpm install --frozen-lockfile
pnpm build
Préparer le déploiement: Le serveur
Bon ! Le projet est buildé, les fichiers générés sont dans le dossier dist et il ne vous reste plus qu’à construire une image nginx qui contiendra vos sources avec le Dockerfile suivant (attention les yeux !) :
FROM nginx:1.19-alpine
COPY ./dist/ /usr/share/nginx/html
DĂ©ployer
Ca y est ! Techniquement, votre image nginx peut être déployée n’importe où et vous aurez accès à votre Starlight en mode production. Vous pouvez tester très rapidement avec la commande suivante :
docker build -t starlight-nginx . # On construit l'image
docker docker run --rm -f starlight-nginx # On la fait tourner
L’ombre au tableau
Voilà pour ce tour d’horizon ! Dans les faits, rien n’est fondamentalement différent de certains autres frameworks, mais son focus sur la sobriété a particulièrement fait vibrer ma corde sensible et m’a convaincu d’essayer. Depuis, je n’ai pas été déçu ! 
Toutefois, il serait malhonnête de ne pas mentionner les deux principaux “inconvénients” de cette solution. Rien de rédhibitoire et ce point de vue est personnel, mais à garder en tête néanmoins !
Pas de navigation côté client
Pour les aficionados des frameworks frontend, ce point-là est peut-être une hérésie mais Starlight n’a qu’un mode MPA (Multi Page Application) et qui n’est pas une SPA (Single Page Application).
Vous vous demandez quelles sont les implications ? Eh bien, lorsque vous cliquez sur un lien dans une MPA (et donc Starlight), le résultat sera différent des sites avec un front en React par exemple (un fetch des données pour ne modifier que les parties concernées de la page avec les données récupérées). A la place, ce sera comme dans un site web classique où chaque clic implique un rechargement complet de la page pour charger le contenu sur lequel vous avez cliqué.
Astro lui, supporte la navigation côté client via les views transitions, donc si ce n’est déjà fait au moment où cet article est publié Starlight le devrait aussi, mais il faut garder en tête que l’expérience native sera une MPA.
Pas encore en 1.0
A l’heure oĂą j’écris ces lignes Starlight est en version 0.28.3. Comme toutes les versions prĂ©-1.0, il faut faire attention Ă ce que l’on fait avec et garder cette information Ă l’esprit. Les choses pourraient encore changer drastiquement (en bien ou en mal.)
Pour mitiger ce risque, on peut noter quelques points :
Â
-
- Votre version de prod étant juste des fichiers HTML, vous n’aurez jamais à vous soucier de vos sites déjà en prod qui arrêtent de marcher ou que vous ne pourrez pas redéployer ailleurs
-
- La migration vers d’autres solutions sera simplifiée car votre contenu sera rédigé en Markdown
- Astro le “moteur” de Starlight est, lui, est en 4.X actuellement. Stable, avec un développement très actif et l’équipe semble à l’écoute de la communauté.
Vers l’infini et au-dĂ©lĂ
On arrive Ă la fin de cet article… mais pour notre documentation, ce n’est qu’un dĂ©but ! Vous l’aurez sans doute compris Ă la lecture du titre mais, de mon cĂ´tĂ©, Starlight a su me convaincre et nous continuerons encore Ă l’exploiter chez Blackswift pour un bon moment !
Si vous voulez jeter un oeil à la version que j’ai mise en ligne avec cette solution vous pouvez aller la voir par ici.
Dans tous les cas, cet article n’a pas vocation à être une étude exhaustive. N’hésitez pas à faire vos propres recherches et écrire le vôtre si vous pensez qu’une autre solution mérite aussi vos éloges !
Dans le fond, toutes se valent et il vaut mieux juste utiliser ce avec quoi vous êtes à l’aise et vous pensez pouvoir le mieux exploiter. En gardant cette étincelle de curiosité pour continuer d’explorer de nouvelles pistes et découvrir des solutions toujours plus intéressantes.
Sur ce, bon décollage avec Starlight et amusez-vous bien !
