Vue d'ensemble

Ce site est produit par deux briques empilées : Astro, un générateur de sites, et Starlight, un thème de documentation complet qui se branche sur Astro.

Astro : un générateur de site statique

Astro prend des fichiers sources (Markdown, composants, images…) et les transforme une fois pour toutes, au moment du build, en fichiers HTML, CSS et JS.

Les points clés :

• Le travail est fait à la compilation, pas à la visite. Quand un lecteur ouvre une page, le serveur renvoie un fichier HTML déjà prêt. Pas de base de données, pas de code serveur.
• Zéro JavaScript par défaut. Astro n’envoie au navigateur que le JS strictement nécessaire (ici : la recherche, le menu mobile, le sélecteur de thème…). Le reste est du HTML pur.
• Basé sur Vite. Le serveur de développement (npm run dev) recharge instantanément la page quand un fichier change.
• Extensible par des « intégrations ». Une intégration est un module qui ajoute des fonctionnalités à Astro. Starlight en est une.

Starlight : le thème de documentation

Starlight est une intégration Astro qui fournit, prêts à l’emploi :

La mise en page

En-tête, barre latérale de navigation, table des matières à droite, liens « page précédente / suivante ».

La recherche

Un index Pagefind généré au build : la recherche fonctionne sans serveur.

Le thème clair / sombre

Avec sélecteur, et respect des préférences du système.

L'internationalisation

Interface traduite (ici en français) et gestion de plusieurs langues de contenu.

Des composants

Onglets, encarts, cartes, étapes, arborescences… utilisables en MDX.

La validation du contenu

Chaque page est vérifiée (titre obligatoire, champs connus…) à la compilation.

Qui fait quoi ?

Vous écrivez…	Starlight fournit…	Astro fait…
Le contenu (.md / .mdx)	Les gabarits de page (layout, sidebar, TOC)	La compilation Markdown → HTML
La configuration (astro.config.mjs)	Le schéma de validation du frontmatter	Le routage (fichier → URL)
Éventuellement des images, du CSS	Les composants (<Tabs>, <Aside>…)	L’optimisation des images, le bundling CSS/JS

En pratique, pour rédiger de la documentation, on ne touche qu’au dossier src/content/docs/. Tout le reste est de la configuration qu’on modifie rarement.

Le cycle de vie d’une page

src/content/docs/guides/getting-started.md        ← vous écrivez du Markdown
        │
        │  1. Astro lit le fichier via la « collection » docs
        │  2. Starlight valide le frontmatter (title, description…)
        │  3. Le Markdown est converti en HTML
        │  4. Starlight l'insère dans son gabarit (en-tête, sidebar, TOC)
        ▼
dist/guides/getting-started/index.html            ← fichier statique final
        │
        ▼
https://mon-site/guides/getting-started/          ← servi tel quel par Nginx, Apache…

Pour aller plus loin

Structure du projetÀ quoi sert chaque fichier et dossier.

Compilation et dossier dist/Ce qui se passe pendant npm run build.