Guide

Starlight : un thème de documentation pour Astro

Starlight transforme des fichiers Markdown en site de documentation Astro : recherche Pagefind, traductions, mode sombre. Version 0.41.7, licence MIT, alternatives.

L'équipe CodeWorlds16 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Starlight est une intégration Astro qui transforme un répertoire de fichiers Markdown en site de documentation avec une barre latérale, un mode sombre, des traductions et un moteur de recherche qui tourne en local. La version actuelle du paquet @astrojs/starlight est la 0.41.7, sortie le 5 août 2026, sous licence MIT.

Un thème, pas un framework distinct

La différence entre un thème et un framework ressemble à une querelle de mots jusqu'au moment d'adapter l'outil à un dépôt. Docusaurus est son propre framework : ses propres commandes, son propre routeur, son propre cycle de build. Starlight n'a rien de tout cela, car il prend tout à Astro. Vous l'installez comme dépendance, vous ajoutez une entrée au tableau integrations dans astro.config.mjs, et vous continuez avec de simples astro dev et astro build.

La conséquence pratique est que la documentation cesse d'être un projet séparé. Un site marketing, un blog d'entreprise et la documentation peuvent vivre dans un seul dépôt, partager un seul fichier de configuration, un seul jeu de dépendances et un seul pipeline de déploiement. Starlight ne revendique que les routes qu'il injecte lui-même, et le reste de src/pages/ reste à vous.

Le paquet livre 25 composants qui peuvent être remplacés via le champ de configuration components, plus un ensemble de composants à utiliser dans le contenu : Aside, Badge, Card, CardGrid, Icon, Tabs, TabItem, LinkCard, Steps, FileTree, LinkButton et un Code réexporté depuis le paquet astro-expressive-code. La coloration syntaxique des blocs de code est gérée par Expressive Code, version 0.44.

Le revers de cette dépendance est évident et doit être dit clairement. Une équipe qui ne connaît pas Astro commence par apprendre le framework : collections de contenu, îlots, adaptateurs, syntaxe des fichiers .astro. Si personne dans l'entreprise ne touche à Astro en dehors de la documentation, c'est le coût de l'entretien d'un savoir réutilisable nulle part ailleurs.

Version, licence et le numéro inférieur à un

La licence concorde dans les trois endroits que j'ai vérifiés. Le fichier LICENSE de la branche principale du dépôt withastro/starlight contient le texte MIT avec une mention de copyright commençant en 2023. Le champ license du registre npm pour la version 0.41.7 indique MIT. L'archive publiée, de 336 kilo-octets, contient 195 fichiers dont package/LICENSE, ainsi que 144 fichiers .astro, .ts et .js, c'est-à-dire du vrai code et non une coquille qui renvoie vers un autre paquet. C'est un cas d'école où il n'y a rien à trancher lors d'un audit de dépendances.

Le numéro de version, en revanche, mérite son propre paragraphe. Le paquet est apparu en 0.0.1 en mai 2023 et, après 186 versions, reste en dessous de un, alors que le projet est entretenu, sort à rythme régulier et est soutenu par l'équipe Astro. Ni le README du paquet ni le changelog ne contiennent de phrase déclarant une politique de compatibilité, donc l'historique des changements est la seule source solide. Il dit ceci : sur 41 versions mineures, de la 0.1.0 à la 0.41.0, dix-huit contiennent au moins une entrée marquée comme changement cassant. L'exemple le plus récent est la 0.41.0, qui a ajouté la prise en charge d'Astro 7 et abandonné Astro 6 dans la même version. La conclusion pour planifier le travail : passer de la 0.40 à la 0.41 n'est pas un changement qu'un robot de dépendances peut pousser sans lire les notes de version.

Il vaut la peine de vérifier à côté les plages de dépendances peer. Starlight 0.41.7 déclare astro dans la plage ^7.0.2 et @astrojs/markdown-remark dans la plage ^7.2.0. Astro actuel est la 7.2.4, sortie le 19 août 2026, donc les deux plages sont satisfaites sans effort.

Installation et configuration

Deux voies d'entrée : un nouveau projet à partir d'un template, ou l'ajout à un projet existant.

Bash
# new project from the ready-made documentation template
npm create astro@latest -- --template starlight

# or add Starlight to an existing Astro project
npx astro add starlight

# local work and building
npx astro dev
npx astro build

La commande astro add starlight installe le paquet et ajoute l'intégration à la configuration, mais elle ne créera pas la collection de contenu à votre place. Il faut le faire à la main, dans src/content.config.ts, avec le loader et le schéma fournis par Starlight.

TSsrc/content.config.ts
// src/content.config.ts
import { defineCollection } from 'astro:content'
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders'
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() })
}

docsLoader lit les fichiers de src/content/docs/ avec les extensions md, mdx, markdown, mdown, mkdn, mkd et mdwn, en ignorant les noms qui commencent par un underscore. Si le projet a l'intégration @astrojs/markdoc, le loader ajoute mdoc à cette liste. La collection i18n est optionnelle et accepte des fichiers json, yml et yaml.

La configuration du thème elle-même vit dans astro.config.mjs. Voici un ensemble de champs qui existent réellement dans le schéma de la 0.41.7.

astro.config.mjs
// astro.config.mjs
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

export default defineConfig({
  site: 'https://docs.example.com',
  integrations: [
    starlight({
      title: 'Documentation',
      tagline: 'Deployment handbook',
      titleDelimiter: '|',
      credits: false,
      prerender: true,
      editLink: { baseUrl: 'https://github.com/example/docs/edit/main/' },
      lastUpdated: true,
      pagination: true,
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
      customCss: ['./src/styles/docs.css'],
      routeMiddleware: './src/starlightRouteData.ts',
      markdown: { headingLinks: true, processedDirs: [] },
      components: {
        Footer: './src/overrides/Footer.astro'
      },
      sidebar: [
        { label: 'Start', link: '/start/' },
        {
          label: 'Guides',
          collapsed: false,
          items: [{ autogenerate: { directory: 'guides', collapsed: true } }]
        }
      ]
    })
  ]
})

Deux champs de cette liste sont une source courante d'erreurs silencieuses. routeMiddleware rejette tout chemin qui correspond à ./src/middleware.ts ou ./src/middleware/index.ts, car ces emplacements appartiennent à Astro, et affiche un message qui suggère de renommer le fichier. Par ailleurs, les groupes autogenerate ne peuvent plus porter de champ label : la prise en charge des groupes autogénérés a été retirée dans la 0.39.0, et le schéma renvoie une erreur descriptive avec la correction toute prête.

La recherche Pagefind et où se situe sa limite

C'est la raison de comparer Starlight à Docusaurus. Docusaurus n'a pas de recherche dans son cœur et vous renvoie vers le service externe Algolia DocSearch, gratuit uniquement pour la documentation technique publique et seulement après une demande acceptée. Starlight a la recherche dès le premier build et n'exige ni configuration ni compte nulle part.

En dessous se trouve Pagefind version 1.5.2 sous MIT, avec le paquet @pagefind/default-ui à la même version. Le mécanisme est simple : dans le hook astro:build:done, Starlight prend le répertoire du HTML terminé, appelle createIndex, puis index.addDirectory sur le répertoire de sortie, et enfin index.writeFiles dans un sous-répertoire pagefind/. Le journal de build affiche un message avec le nombre de fichiers HTML trouvés et le temps d'indexation.

Deux limites découlent de ce mécanisme et aucune configuration ne peut les contourner. Première : l'index est produit à partir du HTML généré, donc les pages doivent être prérendues. Le schéma de configuration rejette explicitement prerender: false combiné avec Pagefind activé et renvoie un message qui dit que la recherche Pagefind n'est pas prise en charge avec le prérendu désactivé. Seconde : l'indexation ajoute du temps de build, et elle a lieu après la fin du build proprement dit, donc sur une grande documentation vous le verrez dans le pipeline de déploiement.

Sur l'échelle, les auteurs de Pagefind donnent leur propre mesure : un site de dix mille pages devrait être interrogeable avec une charge réseau totale inférieure à 300 kilo-octets, bibliothèque comprise, et pour la plupart des sites ce chiffre devrait être plus proche de 100 kilo-octets. La clé de cette promesse est le découpage de l'index en morceaux, dont le navigateur ne récupère que ceux qui correspondent à la requête.

Je l'ai mesuré sur le site de Starlight lui-même. Le fichier pagefind-entry.json pèse 1 133 octets et liste 17 index de langues distincts, 36 pages chacun, soit 612 pages au total. L'index anglais se compose de trois fichiers .pf_index de 20 279, 33 546 et 34 745 octets, soit 88 570 octets au total. S'y ajoutent les éléments récupérés chaque fois que la recherche s'ouvre pour la première fois : pagefind.js à 45 555 octets, pagefind-ui.js à 119 987 octets, pagefind-ui.css à 14 482 octets, wasm.en.pagefind à 72 209 octets, le fichier d'entrée mentionné plus haut à 1 133 octets et le fichier de métadonnées de l'index à 450 octets. Ces six éléments totalisent 253 816 octets. En ajoutant un morceau d'index, la première recherche coûte entre 274 095 et 288 561 octets avant la compression que votre serveur appliquera de toute façon.

La limite d'échelle se situe donc à deux endroits à la fois. Plus de 250 kilo-octets de surcoût fixe, c'est beaucoup pour un site de documentation, et chacun qui clique dans le champ de recherche le paie. Le second endroit est le contenu multilingue : Pagefind construit un index séparé par langue, donc une documentation en une douzaine de langues signifie une douzaine d'index, une douzaine de fichiers WebAssembly et un build proportionnellement plus long. Avec deux cents pages dans une langue, vous ne le remarquerez jamais. Avec quelques milliers de pages réparties sur huit langues, mesurez le temps de build avant de vous engager.

Entre-temps, le comportement du client est raisonnable. Le code de recherche se charge dynamiquement via await import('@pagefind/default-ui') dans un élément <dialog>, dans un appel planifié par requestIdleCallback, et seulement dans les builds de production. Le constructeur PagefindUI reçoit element, baseUrl, bundlePath, showImages: false, showSubResults: true et les traductions de l'interface.

La pertinence des résultats peut être réglée, et les noms de champs correspondent un à un aux options de Pagefind.

JavaScript
starlight({
  title: 'Documentation',
  pagefind: {
    indexWeight: 1,
    ranking: {
      pageLength: 0.1,
      termFrequency: 0.1,
      termSaturation: 2,
      termSimilarity: 9,
      diacriticSimilarity: 0.8,
      metaWeights: { title: 5 }
    },
    mergeIndex: [
      { bundlePath: 'https://api.example.com/pagefind/', indexWeight: 0.5, language: 'en' }
    ]
  }
})

Les valeurs par défaut sont exactement celles indiquées ci-dessus, et metaWeights pondère le titre à cinq par défaut. La recherche peut aussi être désactivée entièrement avec pagefind: false, une page peut être ignorée avec pagefind: false dans son frontmatter, et un fragment de page peut être exclu avec l'attribut data-pagefind-ignore. Quiconque a accès au programme DocSearch et préfère Algolia peut se tourner vers le plugin officiel @astrojs/starlight-docsearch en version 0.7.0.

Traductions et navigation latérale

Starlight a les traductions dans son cœur, sans plugins. Le paquet contient 34 fichiers de traduction de l'interface, de l'arabe aux deux variantes de chinois, et le polonais en fait partie. La configuration se résume au champ locales, où la clé root marque la langue servie depuis le chemin racine, et chaque entrée accepte label, un lang optionnel et un dir valant ltr ou rtl. Les balises de langue sont validées selon BCP 47, donc une faute de frappe dans un code de langue arrête le build au lieu de produire des URL mortes.

JavaScript
starlight({
  title: { pl: 'Dokumentacja', en: 'Documentation' },
  defaultLocale: 'root',
  locales: {
    root: { label: 'Polski', lang: 'pl' },
    en: { label: 'English', lang: 'en' },
    ar: { label: 'العربية', lang: 'ar', dir: 'rtl' }
  }
})

La barre latérale fonctionne en deux modes qui peuvent être mélangés dans un même tableau. Un élément avec un champ link est un lien simple et accepte label, translations, badge et attrs qui porte des attributs HTML. Un groupe a label, items et collapsed. Une entrée autogenerate lit un répertoire et construit des éléments à partir des fichiers, en acceptant directory, collapsed et attrs. L'ordre et les libellés des pages individuelles se règlent dans leur frontmatter.

Markdown
---
title: Deploying to production
description: Deployment steps and a checklist
template: doc
tableOfContents: false
lastUpdated: 2026-08-10
draft: false
pagefind: true
sidebar:
  label: Deployment
  order: 3
  badge: New
prev: false
next:
  link: /guides/rollback/
  label: Rolling changes back
banner:
  content: This page covers the 3.x line
---

Page content in Markdown.

La liste complète des champs de frontmatter est title, description, editUrl, head, tableOfContents, template, hero, lastUpdated, prev, next, sidebar, banner, pagefind et draft. Le champ template prend doc ou splash, où splash est une mise en page sans barre latérale, destinée à une page d'accueil avec une section hero.

Mélanger la documentation et le reste du projet

Ce point est facile à manquer et souvent décisif. Comme Starlight est une intégration Astro, le reste du projet reste un projet Astro simple. La page d'accueil, les tarifs, le blog et le formulaire de contact vivent dans src/pages/, la documentation dans src/content/docs/, et un seul build produit tout à la fois.

src/
  content.config.ts
  content/
    docs/            # claimed by Starlight
      index.mdx
      guides/
    i18n/            # interface translations
  pages/
    index.astro      # marketing page, outside Starlight
    pricing.astro
  components/
    PricingTable.tsx # a [React] island or any other framework
  styles/
    docs.css

Les composants interactifs écrits en React s'exécutent sur la page marketing comme des îlots et peuvent aussi être intégrés dans le contenu MDX de la documentation. Le bundler est Vite, les types sont vérifiés par TypeScript, et si le projet utilise Tailwind CSS version 4, le plugin officiel @astrojs/starlight-tailwind en version 5.0.0 accorde le thème de documentation à la même palette. Un produit hébergé ne peut pas offrir cela par définition, car la documentation vit alors en dehors de votre dépôt.

Starlight face à Docusaurus, Mintlify et Nextra

CritèreStarlight 0.41.7Docusaurus 3.10.2MintlifyNextra 4.6.1
FondationIntégration Astroson propre framework Reactplateforme hébergéeun thème Next.js
Recherche dans le cœuroui, Pagefind en localnon, Algolia externeoui, côté fournisseuroui, en local
Versionnement dans le cœurnon, plugin communautaireouioui, côté fournisseurnon
Blog dans le cœurnon, plugin communautaireoui, dans le preset classicoui, côté fournisseurnon
Traductions dans le cœuroui, 34 langues d'interfaceouioui, côté fournisseuroui
LicenceMITMITElastic 2.0, moteur ferméMIT
Dernière version5 août 202610 juillet 2026outil mint, 22 août 20264 décembre 2025

La différence la plus importante avec Docusaurus est l'absence de versionnement de la documentation dans le cœur de Starlight. Quiconque maintient plusieurs versions majeures d'un produit en parallèle obtient dans Docusaurus un mécanisme versioned_docs tout prêt, alors qu'avec Starlight il faut se tourner vers le plugin starlight-versions. Ce projet est maintenu par une seule personne en dehors de l'équipe Astro, en version 0.10.0 du 21 août 2026, sous MIT. Il en va de même pour le blog : starlight-blog en version 0.29.0 vient de la même source. Il existe trois plugins officiels qui portent le scope @astrojs : starlight-docsearch, starlight-tailwind et starlight-markdoc. Tout ce qui va au-delà est maintenu par la communauté, avec tout ce que cela implique sur un horizon de maintenance plus long.

Face à Mintlify, la différence est d'une autre nature : là, vous payez et recevez une plateforme finie avec un moteur fermé, ici vous obtenez du code MIT dans votre propre dépôt et vous assumez vous-même la responsabilité de l'hébergement. Nextra reste un choix sensé pour une équipe qui vit déjà dans Next.js, mais sa dernière version date de décembre 2025, donc le rythme de travail est visiblement plus lent que dans les deux autres projets.

Erreurs courantes

Premièrement : l'absence de src/content.config.ts. La commande astro add starlight ajoute l'intégration mais ne créera pas la collection, et sans docsLoader, le site ne trouve aucun contenu.

Deuxièmement : prerender: false avec la recherche activée. La configuration sera rejetée avec un message indiquant que Pagefind n'est pas pris en charge sans prérendu. Si une partie du site doit s'exécuter côté serveur, désactivez le prérendu pour cette route seulement, pas globalement.

Troisièmement : un champ label à l'intérieur d'un objet autogenerate. Cette forme a cessé de fonctionner dans la 0.39.0. Il faut créer un groupe avec le libellé et placer l'entrée autogenerate dans son tableau items.

Quatrièmement : un fichier de middleware nommé src/middleware.ts et passé à routeMiddleware. Ce chemin entre en collision avec le mécanisme propre d'Astro, donc le schéma renvoie une erreur. Nommez le fichier autrement, par exemple src/starlightRouteData.ts.

Cinquièmement : mettre à niveau une version mineure sans lire les notes. Dix-huit versions mineures sur quarante et une portaient un changement cassant, donc un robot qui met à jour les dépendances peut casser le build.

Sixièmement : les plages de dépendances peer des plugins sont ouvertes vers le haut. starlight-blog déclare >=0.41.0, starlight-versions déclare >=0.39.0, et starlight-tailwind déclare >=0.38.0. Le gestionnaire de paquets ne vous empêchera pas d'installer un plugin sur une version de Starlight plus récente que celle sur laquelle ce plugin a été testé.

FAQ

Starlight convient-il à une grande documentation ?

Jusqu'à quelques centaines de pages dans une langue, sans réserve. Au-delà de ce seuil, vérifiez deux choses : le temps d'indexation de Pagefind, qui s'ajoute après la fin du build, et le nombre de langues, car chacune a son propre index et son propre fichier WebAssembly. Les auteurs de Pagefind annoncent un fonctionnement correct à dix mille pages avec une charge inférieure à 300 kilo-octets.

Peut-on versionner la documentation ?

Pas dans le cœur. Le plugin starlight-versions s'en charge, maintenu en dehors de l'équipe Astro, en version 0.10.0 sous MIT. Si le versionnement est une exigence ferme, Docusaurus l'a dans son cœur et c'est un vrai argument en sa faveur.

Que signifie un numéro de version inférieur à un ?

Que les versions mineures peuvent casser la compatibilité, et dans ce projet elles l'ont réellement fait : dix-huit versions mineures sur quarante et une portent une entrée du changelog marquée comme changement cassant. Un exemple récent est la 0.41.0, qui a abandonné la prise en charge d'Astro 6.

Faut-il connaître Astro pour utiliser Starlight ?

Pour monter un site à partir du template, non. Pour modifier la mise en page, remplacer l'un des 25 composants ou ajouter vos propres pages, oui, car vous travaillez alors dans des fichiers .astro et dans les collections de contenu d'Astro.

Comment exclure une page de l'index ?

Mettez pagefind: false dans son frontmatter. Pour exclure une partie d'une page, enveloppez-la dans un élément portant l'attribut data-pagefind-ignore. Toute la fonction de recherche se désactive avec pagefind: false dans la configuration de l'intégration.

La documentation peut-elle cohabiter avec un site marketing ?

Oui, et c'est l'un des principaux avantages de cet agencement. Starlight gère la collection docs tandis que src/pages/ reste à votre disposition. Un seul dépôt, un seul build, un seul déploiement.

Sources : la documentation de Starlight, la documentation de Pagefind et le fichier de licence dans le dépôt.

À lire aussi