ADR: Choix de la stack pour la couche Contenu (Vitrine, Blog, Portfolio et Documentation)

Documentation technique

Statut : Accepté
Date : 2026-09-01
Auteur : AMN

1. Contexte et Problématique1/3

L’architecture globale de notre site web est structurée en trois couches distinctes :

Couche 01 : Contenu (Gestion et stockage des données)
Couche 02 : Présentation (Front-end et rendu utilisateur)
Couche 03 : Backend (Logique métier et services tiers)

1. Contexte et Problématique2/3

Pour la Couche 01 (Contenu), nous devons sélectionner les technologies adaptées pour stocker, structurer et distribuer le contenu de quatre sections aux besoins éditoriaux très différents :

Vitrine : Pages marketing nécessitant une structure de mise en page flexible.
Blog : Articles chronologiques nécessitant une édition de texte riche et une gestion des médias.
Portfolio : Projets et réalisations nécessitant des schémas de données structurés et liés.
Documentation : Pages techniques volumineuses, nécessitant un versionnage rigoureux et une structure hiérarchique stricte.

1. Contexte et Problématique3/3

L’objectif est de maximiser l’autonomie des contributeurs pour le marketing tout en conservant une approche performante et robuste pour la documentation technique.

2. Décision Architecturale

Nous décidons de séparer la couche contenu en deux outils spécialisés selon la nature des données :

Sanity.io (CMS Headless SaaS) pour la gestion du contenu dynamique et marketing : Vitrine, Blog, et Portfolio.
Astro Starlight (Fichiers locaux Markdown/MDX) pour la gestion du contenu technique : Documentation.

3. Justification du choix

3.1. Pourquoi Sanity.io (Vitrine, Blog, Portfolio) ?1/2

Flexibilité des Schémas (Content Lake) : Sanity stocke le contenu sous forme de documents JSON non structurés. Cela permet de modéliser facilement les relations complexes du Portfolio et les structures modulaires nécessaires aux pages de la Vitrine.
Interface de saisie sur mesure (Sanity Studio) : Le studio est entièrement configurable en code (TypeScript/JavaScript), ce qui permet de créer une interface d’édition épurée et adaptée aux équipes non techniques.

3.1. Pourquoi Sanity.io (Vitrine, Blog, Portfolio) ?2/2

Intégration Astro native : Sanity propose une intégration officielle avec Astro (@sanity/astro), facilitant la récupération des données via l’API GROQ ou GraphQL lors de la phase de génération statique (SSG).
Zéro maintenance infrastructure : En tant que solution SaaS, Sanity élimine le besoin de gérer une base de données ou un serveur d’administration pour le contenu marketing.

3.2. Pourquoi Astro Starlight (Documentation) ?

Approche “Docs-as-Code” : La documentation est stockée localement au format Markdown/MDX. Elle suit le même cycle de vie que le code source de l’application (commits, pull requests, revues de code, et versionnage via Git).
Performance et fonctionnalités natives : Starlight fournit nativement la recherche globale, la navigation hiérarchique, la gestion multilingue et les composants UI spécifiques aux documentations techniques sans aucun coût de requête d’API externe au build.
Isolation des responsabilités : Les modifications de la documentation technique ne dépendent pas de la disponibilité d’un CMS tiers.

4. Conséquences de la décision

Effets Positifs (Avantages)

Performance maximale au build : Le contenu de la documentation est lu localement. Le contenu de Sanity est requêté une seule fois lors de la phase de génération du site par Astro.
Expérience éditoriale optimisée : Les équipes marketing utilisent une interface graphique moderne (Sanity), tandis que l’équipe technique rédige la documentation directement dans son IDE (Markdown).
Économie de coûts : L’utilisation de Starlight réduit le volume de données stocké sur Sanity, permettant de rester durablement dans le forfait gratuit (Generous Free Tier) de Sanity.

Effets Négatifs (Inconvénients & Risques)1/3

Dualité des sources de vérité : Le contenu du site est scindé en deux emplacements (l’API de Sanity et le dépôt Git local). L’équipe technique devra s’assurer de la cohérence visuelle globale lors de la phase de présentation (Couche 02).

Effets Négatifs (Inconvénients & Risques)2/3

Processus de publication asynchrone :
- Pour la documentation, une publication nécessite un commit et un déploiement Git.
- Pour le CMS, un déclenchement de webhook de build (ex: Netlify, Vercel) est requis lors de la publication d’un article pour rafraîchir le site.

Effets Négatifs (Inconvénients & Risques)3/3

Externalisation des médias : Les fichiers médias (images, vidéos, documents) ne sont plus stockés dans Sanity. Ils sont hébergés sur Cloudflare R2 (et Cloudflare Stream pour les vidéos). Sanity ne conserve que les métadonnées et les URLs. Cette décision renforce le contrôle des coûts et l’alignement avec l’écosystème Cloudflare (Couche 03), mais implique une gestion d’upload et de nettoyage dédiée.

5. Alternatives Exclues

Tout sur Sanity (y compris la documentation) : Exclu car la gestion d’une arborescence de documentation complexe et technique est moins intuitive dans un CMS traditionnel que dans un outil dédié comme Starlight. De plus, cela aurait augmenté inutilement la consommation des quotas d’API de Sanity.
Tout en fichiers locaux Markdown (y compris Blog/Vitrine) : Exclu car cela aurait bloqué l’autonomie des équipes non techniques pour la modification de la vitrine et du blog (obligation de passer par des fichiers de code et Git).