Composants MDX

Resume executif

Cette reference organise les composants a utiliser dans les pages MDX. La regle centrale est simple : utiliser les composants natifs Starlight pour les patterns generiques de documentation, et garder les composants Astro locaux pour les besoins metier de la base documentaire.

Document actif

Le kit V2 conserve les composants existants, ajoute les composants manquants pour les documents longs et clarifie les limites avec les composants natifs Starlight.

2026-05-25

Statut

Actif

Responsable

Tepe

Mise a jour

2026-05-25

Tags

mdxstarlightcomposants

Doctrine

Le projet ne doit pas devenir une application UI complexe. Les composants doivent rendre la lecture, la decision et la maintenance plus faciles sans ajouter de dependance inutile.

Ordre de preference :

1. Markdown natif quand la structure suffit.
2. Composant Starlight natif quand le besoin est documentaire et standard.
3. Composant local Astro quand le besoin correspond a une regle documentaire du projet.
4. Plugin Starlight seulement quand le gain est durable et transversal.

Matrice d’usage

Besoin	Composant recommande	Origine	Usage cible
Resume executif	ExecutiveSummary	Local	Debut de document long, note strategique, reference durable
Statut de page	StatusBanner	Local	Page active, brouillon important, archive commentee
Statut projet	ProjectStatus	Local	Page d’accueil projet ou fiche de suivi
Decision	DecisionBox	Local	Arbitrage, choix propose, validation, rejet
Journal de decisions	DecisionLog	Local	Plusieurs decisions datees a comparer
Comparaison d’options	OptionMatrix	Local	Arbitrage multi-options avec recommandation
Preuve ou hypothese	EvidenceBox	Local	Fait, hypothese, source et niveau de confiance
Metadonnees document	DocumentMeta	Local	Statut, responsable, date, tags
Chronologie	Timeline	Local	Jalons, historique projet, sequence d’evenements
Risque critique	WarningBox	Local	Point bloquant, limite forte, risque operationnel
Prochaines actions	ActionList	Local	Suite operationnelle avec responsable, echeance ou statut
Sources structurees	SourceList	Local	Bas de page avec references externes
Reference courte	ReferenceCard	Local	Carte source ou ressource isolee
Note generique	Aside	Starlight	Note, conseil, avertissement non metier
Badge court	Badge	Starlight	Statut compact dans tableau ou liste
Navigation	LinkCard + CardGrid	Starlight	Index de dossiers, pages ressources, pages d’accueil
Procedure	Steps	Starlight	Workflow, runbook, tutoriel pas a pas
Arborescence	FileTree	Starlight	Structure de dossiers, conventions de fichiers
Variante equivalente	Tabs + TabItem	Starlight	Environnements, options, commandes alternatives
Code externe	Code	Starlight	Extrait importe avec ?raw, code genere, comparaison de config
Action de navigation	LinkButton	Starlight	Lien principal sur page d’accueil ou guide

Decisions

Composants natifs avant dependances

Validee

Les composants fournis par @astrojs/starlight/components sont prioritaires pour les patterns generiques : cartes, badges, onglets, etapes, arborescences, boutons, asides et blocs de code.

Composants locaux pour les regles documentaires

Validee

Les composants locaux restent reserves aux conventions propres au systeme documentaire : resume executif, decisions, risques, sources, actions, statut et suivi projet.

Ajouts locaux limites

Proposee

Les composants locaux ajoutes en V2 couvrent uniquement les besoins recurrents des documents longs : metadonnees, decisions datees, options, preuves et chronologies.

Anti-redondance

Situation	Utiliser	Ne pas utiliser
Note generique, conseil, avertissement simple	Aside Starlight	WarningBox
Risque metier ou operationnel fort	WarningBox	Aside generique
Navigation vers une page	LinkCard Starlight	ReferenceCard
Source externe annotee	ReferenceCard ou SourceList	LinkCard
Metadonnees generales	DocumentMeta	ProjectStatus
Fiche projet courte	ProjectStatus	DocumentMeta si la page est strictement projet
Comparaison d’options	OptionMatrix	Tableau Markdown repetitif
Plusieurs decisions datees	DecisionLog	Plusieurs DecisionBox empiles

Composants canoniques et aliases compatibles

Besoin	Canonique	Alias compatible	Regle
Metadonnees generales	DocumentMeta	Aucun	Standard pour les pages ressources, areas et notes transversales
Fiche projet courte	ProjectStatus	DocumentMeta	Garder ProjectStatus uniquement quand la page represente un projet
Statut court	DocBadge interne	doc-status-pill CSS	Les pages MDX ne l’importent pas directement
Risque operationnel	WarningBox	Aside type="danger"	WarningBox signale un risque metier, pas une note generique
Source annotee	ReferenceCard	SourceList	ReferenceCard pour une source isolee, SourceList pour une bibliographie

Score 10/10

Critere	Regle appliquee
Complet	Le kit couvre resume, statut, decision, options, preuves, actions, timeline, sources et navigation via Starlight
Optimal	Les statuts, labels et tons sont factorises dans un modele partage
Design	Les composants utilisent des surfaces, badges, marqueurs et separateurs coherents en light et dark mode
Sans redondance	Chaque composant local a une limite explicite face aux composants Starlight
Pertinent	Les composants locaux servent uniquement les conventions documentaires du projet

Galerie V2

Decisions datees

Journal des decisions

1. Conserver Astro pur pour les composants documentaires

   Le rendu reste statique, rapide et compatible avec MDX sans runtime client.

   Validee2026-05-25
2. Differer les plugins tant que le besoin transversal n est pas prouve

   La maintenance reste faible et les conventions locales restent lisibles.

   Proposee2026-05-25

Comparaison d’options

Options

Composants Starlight

Recommandee

Avantage

Stable, coherent avec le theme, sans maintenance locale.

Limite

Ne couvre pas les conventions metier du systeme documentaire.

Note

Choix par defaut pour les patterns generiques.

Composants locaux

Possible

Avantage

Traduit les regles documentaires propres au projet.

Limite

Demande une discipline de maintenance.

Note

A utiliser quand une regle revient dans plusieurs pages.

Nouvelle librairie UI

Rejetee

Avantage

Large catalogue pret a l emploi.

Limite

Ajoute du poids et des conventions inutiles pour une base documentaire.

Preuves et hypotheses

Fait verifie

Confiance haute

Starlight expose des composants natifs depuis @astrojs/starlight/components pour les fichiers MDX.

Voir la source

Hypothese de maintenance

Confiance moyenne

Le kit local doit rester petit : un composant est justifie seulement s’il rend une convention documentaire plus claire.

Chronologie

Chronologie

1. Audit des composants v1Termine

   2026-05-25 - Evaluation initiale a 7.4 sur 10.

2. Kit V2 documenteEn cours

   2026-05-25 - Ajout des composants manquants et des regles anti-redondance.

3. Validation par usage reelA venir

   Appliquer les composants aux prochaines pages longues.

References annotees

Documentation

Starlight Components

Reference principale pour les composants natifs disponibles dans les pages MDX.

Plugins a differer

Ne pas installer trop tot

Un plugin doit resoudre un probleme transversal deja visible dans plusieurs pages. Sinon, preferer une convention MDX locale.

Plugin	Utilite	Priorite
starlight-links-validator	Controler les liens casses	Haute quand les sources externes augmentent
starlight-image-zoom	Agrandir captures et schemas	Moyenne, utile avec beaucoup d’images
starlight-llms-txt	Generer des contextes llms.txt pour assistants IA	Moyenne, pertinent si le site sert de base IA
starlight-tags	Exploiter les tags dans la navigation	Basse tant que les tags restent simples
astro-mermaid ou astro-d2	Rendre des diagrammes depuis les blocs Markdown	Moyenne si les workflows deviennent graphiques

Exemple d’import standard

import { Aside, Badge, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import ExecutiveSummary from '../../../components/ExecutiveSummary.astro';
import DecisionBox from '../../../components/DecisionBox.astro';
import DocumentMeta from '../../../components/DocumentMeta.astro';
import DecisionLog from '../../../components/DecisionLog.astro';
import OptionMatrix from '../../../components/OptionMatrix.astro';
import EvidenceBox from '../../../components/EvidenceBox.astro';
import Timeline from '../../../components/Timeline.astro';

Exemple de niveau de titre

<ActionList headingLevel={3} actions={actions} />
<DecisionLog headingLevel={3} decisions={decisions} />
<OptionMatrix headingLevel={3} options={options} />
<Timeline headingLevel={3} items={items} />

Prochaines actions

Prochaines actions

1. Utiliser LinkCard et CardGrid dans les pages index de ressources

   Tepe

   A faire
2. Remplacer les listes de procedures longues par Steps quand le contenu est stable

   Tepe

   A faire
3. Utiliser DocumentMeta pour les prochaines references transversales

   Tepe - 2026-05-25

   En cours

Sources

Sources principales

1. Starlight - Using Components

   Reference pour importer et utiliser les composants dans les fichiers MDX.

2. Starlight - Components

   Point d entree vers les cartes, badges, asides, file tree, steps, tabs, code et boutons.

3. Starlight - Plugins and Integrations

   Catalogue des plugins officiels et communautaires pertinents pour une documentation Starlight.

4. Astro - MDX Integration

   Reference pour l usage des composants Astro et UI dans les fichiers MDX.