Starlight

Thème de documentation Astro où chaque fichier Markdown devient une page

Starlight est un thème de documentation complet pour Astro, installé comme une intégration du framework. Chaque fichier Markdown ou MDX rangé dans src/content/docs/ devient une page, et Starlight fournit autour la navigation latérale, la recherche, le mode sombre et la coloration du code. Un projet neuf part du modèle officiel (npm create astro@latest -- --template starlight), un site Astro existant l'ajoute avec npx astro add starlight. Par défaut, les pages de doc sont prérendues en HTML au build, même quand le reste du projet tourne en rendu serveur.

Recherche Pagefind, frontmatter typé et interface en 36 langues

• Recherche sans service externe : un index Pagefind est produit au build et s'ouvre par Ctrl+K ou Cmd+K. Une page s'en retire avec pagefind: false, et le plugin officiel @astrojs/starlight-docsearch remplace Pagefind par Algolia DocSearch pour les projets admis à ce programme.
• Frontmatter validé par un schéma typé : docsSchema() décrit les champs de chaque page, et son option extend y ajoute ceux du projet.
• Traductions avec repli : un dossier par langue, des pages associées par leur nom de fichier. Une page pas encore traduite s'affiche dans la langue par défaut, avec un avis qui le signale. Les langues écrites de droite à gauche sont prises en charge, et les libellés de l'interface sont livrés en 36 langues.
• Composants React, Vue, Svelte ou Solid dans le MDX : les îles d'Astro leur évitent d'envoyer du JavaScript au navigateur tant que leur hydratation n'est pas demandée.
• Apparence réglable à plusieurs niveaux : variables CSS, styles rangés dans une couche @layer starlight, prise en charge de Tailwind CSS v4, et remplacement de composants de l'interface (en-tête, recherche, sélecteur de langue, pied de page) par des composants Astro.

Bêta en 0.42, Astro 7.2.10 minimum, recherche absente en dev

Le projet se présente encore comme un logiciel en bêta. Le guide de démarrage l'écrit tel quel et annonce des mises à jour fréquentes. La branche 0.42 a connu huit versions entre le 2 septembre et le 23 octobre 2026, date de la 0.42.7, et le dernier commit date du 27 octobre 2026.

Une version mineure peut imposer une migration. La 0.41.0, du 23 juin 2026, a abandonné Astro 6 pour Astro 7. La 0.42.0 exige Astro 7.2.10 ou plus et ne prend plus officiellement en charge les navigateurs Chromium antérieurs à la version 116, Safari avant la 17.0 ni Firefox avant la 125. Starlight et Astro se mettent donc à jour ensemble (npx @astrojs/upgrade), et le changelog prévient que les plugins communautaires peuvent devoir suivre à la main.

Starlight ne fonctionne qu'à l'intérieur d'un projet Astro. La configuration vit dans astro.config.mjs, le contenu dans les content collections d'Astro, et le guide de démarrage renvoie à la documentation d'Astro pour tout ce que celle de Starlight ne couvre pas. Servir la doc sous un sous-chemin oblige à l'imbriquer dans un dossier de src/content/docs/, contournement que le projet dit vouloir supprimer.

La recherche ne fonctionne pas avec le serveur de développement. L'index Pagefind n'existe qu'après un build. En mode dev, la fenêtre de recherche indique qu'elle n'est disponible qu'en production et propose de construire puis de prévisualiser le site.

Le projet mesure lui-même le poids de ses pages. Sa page « Eco-friendly docs » annonce moins de 50 Ko de données compressées à la première visite. Elle publie aussi un relevé du Website Carbon Calculator daté du 21 avril 2026 : 0,01 g de CO₂ par visite pour une page de la documentation de Starlight, contre 0,04 g pour VitePress et 0,09 g pour Docusaurus, chaque outil mesuré sur sa propre documentation.