Créer un site de documentation avec Astro Starlight

Vous cherchez à créer un site de documentation pour votre projet, votre équipe ou votre entreprise ? Ce guide vous accompagne pas à pas pour construire un site moderne avec Astro et Starlight — une solution qui génère des pages ultra-rapides sans nécessiter de connaissances approfondies en développement frontend.

Ce que vous allez apprendre

Pourquoi Astro est particulièrement adapté aux sites de documentation
Comment créer et configurer votre premier projet
Comment ajouter du contenu et personnaliser l’apparence
Comment déployer votre site sur un serveur web

Pourquoi choisir Astro et Starlight ?

Avant de plonger dans l’installation, prenons un moment pour comprendre ce qui rend cette combinaison particulièrement intéressante pour la documentation.

Le problème des sites de documentation classiques

Créer un site de documentation pose souvent un dilemme. D’un côté, vous pouvez utiliser un générateur de site statique simple comme Jekyll ou Hugo, mais la personnalisation demande beaucoup d’efforts. De l’autre, des frameworks modernes comme React ou Vue offrent une grande flexibilité, mais ils envoient beaucoup de JavaScript au navigateur, ce qui ralentit le chargement des pages.

Pour une documentation technique, la vitesse est cruciale. Vos lecteurs veulent accéder rapidement à l’information qu’ils cherchent, pas attendre que du JavaScript se charge. C’est précisément le problème qu’Astro résout.

Qu’est-ce qu’Astro ?

Astro est un framework web créé en 2020 qui adopte une philosophie radicalement différente : générer des pages HTML pures par défaut, sans JavaScript. Le navigateur reçoit uniquement le HTML et le CSS nécessaires pour afficher la page, ce qui garantit des temps de chargement extrêmement rapides.

Concrètement, quand vous visitez une page Astro, votre navigateur n’a pas besoin d’exécuter du code JavaScript pour afficher le contenu. Tout est déjà prêt, comme si vous lisiez une page web des années 2000, mais avec un design moderne. Cette approche s’appelle le rendu statique.

Astro n’interdit pas JavaScript pour autant. Si vous avez besoin d’interactivité (un menu déroulant, un formulaire dynamique), vous pouvez ajouter du JavaScript uniquement là où c’est nécessaire. Astro appelle cela l’hydratation partielle : seuls les composants interactifs reçoivent du JavaScript, le reste de la page reste statique.

Qu’est-ce que Starlight ?

Starlight est un thème officiel pour Astro, spécialement conçu pour les sites de documentation. Au lieu de partir d’une page blanche, Starlight vous fournit tout ce dont un site de documentation a besoin :

Une navigation latérale organisée automatiquement
Un moteur de recherche intégré (Pagefind)
Un mode sombre et clair que les lecteurs peuvent choisir
Le support du multi-langue si vous traduisez votre documentation
Une mise en page responsive qui s’adapte aux mobiles et tablettes

Starlight gère tous ces aspects techniques pour vous. Vous n’avez qu’à vous concentrer sur l’écriture de votre contenu.

Comparaison avec d’autres solutions

Pour vous aider à situer Astro Starlight parmi les alternatives, voici ce qui le distingue des autres outils populaires.

Par rapport à Docusaurus (basé sur React), Astro Starlight génère des pages plus légères car il n’envoie pas de framework JavaScript au navigateur. Vos pages se chargent plus vite, surtout sur les connexions lentes ou les appareils moins puissants.

Par rapport à MkDocs (basé sur Python), Starlight offre une personnalisation plus poussée grâce à l’écosystème JavaScript moderne, tout en restant simple à utiliser pour les cas courants.

Par rapport à GitBook (service hébergé), Astro Starlight vous donne un contrôle total sur votre site — vous l’hébergez où vous voulez, sans dépendre d’un service tiers.

Prérequis

Pour suivre ce guide, vous aurez besoin de quelques outils sur votre ordinateur. Si vous ne les avez pas encore, prenez quelques minutes pour les installer.

Node.js version 20 ou supérieure

Node.js est l’environnement d’exécution qui permet de lancer les outils Astro. Même si votre site final ne contiendra pas de JavaScript, Node.js est nécessaire pendant la phase de développement pour compiler vos fichiers et lancer le serveur local.

Pour vérifier si Node.js est installé et connaître sa version, ouvrez un terminal et tapez la commande suivante. Le terminal affichera le numéro de version si Node.js est présent sur votre système.

node --version

Si la commande affiche v20.0.0 ou une version supérieure, vous êtes prêt. Si Node.js n’est pas installé ou si la version est trop ancienne, rendez-vous sur le site officiel nodejs.org pour télécharger la dernière version LTS (Long Term Support).

Un éditeur de code

Vous aurez besoin d’un éditeur pour modifier les fichiers de votre projet. Visual Studio Code est recommandé car il dispose d’excellentes extensions pour Astro qui colorent la syntaxe et signalent les erreurs. Cependant, tout éditeur de texte convient si vous préférez autre chose.

Connaissances de base

Ce guide suppose que vous savez naviguer dans un terminal (ouvrir un dossier, exécuter une commande) et que vous avez une compréhension basique du format Markdown. Si ce n’est pas le cas, consultez d’abord notre guide sur le langage Markdown avant de continuer.

Créer votre premier projet

Maintenant que votre environnement est prêt, passons à la création de votre site de documentation. Astro fournit un outil qui génère automatiquement la structure de base de votre projet.

Lancer l’assistant de création

Ouvrez un terminal dans le dossier où vous souhaitez créer votre projet. Ensuite, exécutez la commande suivante qui télécharge et lance l’assistant de création Astro avec le modèle Starlight.

npm create astro@latest -- --template starlight

L’assistant affiche d’abord un message de bienvenue puis vous pose quelques questions pour configurer votre projet.

 astro   Launch sequence initiated.

   dir   Where should we create your new project?
         ./blue-binary

La première question concerne l’emplacement du projet. L’assistant propose un nom aléatoire (ici blue-binary), mais vous pouvez entrer votre propre nom, par exemple ma-documentation. Ce sera le nom du répertoire qui contiendra tous les fichiers de votre site.

Ensuite, l’assistant propose d’installer les dépendances.

  deps   Install dependencies?
         Yes

Répondez “Yes” pour qu’il télécharge automatiquement toutes les bibliothèques nécessaires. Cette étape peut prendre quelques minutes selon votre connexion internet.

Enfin, il vous demande d’initialiser un dépôt Git.

   git   Initialize a new git repository?
         Yes

Si vous prévoyez de versionner votre documentation (ce qui est fortement recommandé), répondez “Yes”. Le terminal affiche ensuite un résumé des opérations effectuées.

      ✔  Project initialized!
         ■ Template copied
         ■ Dependencies installed
         ■ Git initialized

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./ma-documentation
         Run npm run dev to start the dev server. CTRL+C to stop.

Votre projet est maintenant créé et prêt à être utilisé !

Comprendre la structure du projet

Une fois l’assistant terminé, vous disposez d’un projet complet avec une structure de fichiers bien organisée. Prenons un moment pour comprendre à quoi sert chaque dossier, car cette connaissance vous sera utile quand vous ajouterez du contenu.

Répertoirema-documentation/
- Répertoire.vscode/
  - …
- Répertoirepublic/
  - favicon.svg
- Répertoiresrc/
  - Répertoireassets/
    houston.webp
  - Répertoirecontent/
    Répertoiredocs/
    Répertoireguides/
    example.md
    Répertoirereference/
    example.md
    index.mdx
    content.config.ts
- .gitignore
- astro.config.mjs
- package.json
- README.md
- tsconfig.json

Voici ce que contient chaque élément important de cette structure :

Le dossier public/ contient les fichiers statiques accessibles directement par URL, comme le favicon.svg (l’icône du site qui apparaît dans l’onglet du navigateur). Tout ce que vous placez ici sera copié tel quel dans le site final, sans transformation.

Le dossier src/ contient le code source de votre site. C’est là que vous passerez le plus de temps. À l’intérieur, plusieurs sous-dossiers organisent votre contenu :

assets/ stocke les images et médias qui seront optimisés par Astro
content/docs/ accueille vos pages de documentation au format Markdown ou MDX, organisées par catégories (guides/, reference/, etc.)

Le fichier astro.config.mjs est le cerveau de votre projet. Il définit le titre du site (“My Docs” par défaut), la structure de la sidebar (navigation latérale), et les liens sociaux affichés dans l’en-tête.

Le fichier package.json liste les dépendances de votre projet (Astro, Starlight, etc.) et définit les commandes disponibles : npm run dev pour le développement, npm run build pour la construction, etc.

Démarrer le serveur de développement

Avant d’ajouter du contenu, vérifions que tout fonctionne correctement. Entrez dans le dossier de votre projet, puis lancez le serveur de développement.

cd ma-documentation
npm run dev

Le terminal affiche plusieurs messages pendant le démarrage. D’abord, Astro génère les types TypeScript pour votre projet, puis synchronise le contenu.

16:35:38 [types] Generated 0ms
16:35:39 [content] Syncing content
16:35:39 [content] Synced content

Ensuite, le serveur démarre et affiche l’adresse locale pour accéder à votre site. Par défaut, c’est http://localhost:4321.

 astro  v5.16.9 ready in 821 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

16:35:39 watching for file changes...

Si le port 4321 est déjà utilisé par un autre processus, Astro choisira automatiquement le port suivant (4322, 4323, etc.). Le terminal vous indiquera l’adresse exacte à utiliser.

Ouvrez l’adresse affichée dans votre navigateur. Vous devriez voir la page d’accueil par défaut de Starlight, avec un titre “Welcome to Starlight”, une mascotte (Houston) et des cartes présentant les prochaines étapes. Félicitations, votre site fonctionne !

Page d'accueil Astro Starlight

Le serveur de développement surveille vos fichiers en permanence. Chaque fois que vous modifiez un fichier et l’enregistrez, la page se recharge automatiquement dans le navigateur. Cette fonctionnalité, appelée rechargement à chaud, accélère considérablement le travail de rédaction.

Pour arrêter le serveur, appuyez sur Ctrl+C dans le terminal.

Configurer votre site

Le fichier astro.config.mjs contrôle l’apparence et le comportement de votre site. Modifions-le pour personnaliser votre documentation.

Personnaliser le titre et les informations générales

Ouvrez le fichier astro.config.mjs dans votre éditeur. Vous y trouvez une structure qui ressemble au code ci-dessous. Les commentaires expliquent le rôle de chaque section.

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

export default defineConfig({
  integrations: [
    starlight({
      // Le titre apparaît dans l'en-tête et l'onglet du navigateur
      title: 'Ma Documentation',

      // Liens vers vos réseaux sociaux (optionnel)
      social: {
        github: 'https://github.com/votre-compte/votre-projet',
      },

      // Structure de la navigation latérale
      sidebar: [
        {
          label: 'Guides',
          items: [
            { label: 'Premier pas', slug: 'guides/getting-started' },
          ],
        },
      ],
    }),
  ],
});

Remplacez 'Ma Documentation' par le nom de votre projet. Ce titre apparaît en haut de chaque page et dans l’onglet du navigateur.

La section social permet d’afficher des icônes de liens vers vos réseaux dans l’en-tête du site. Modifiez l’URL GitHub pour pointer vers votre dépôt, ou supprimez cette section si vous ne souhaitez pas afficher de liens sociaux.

La section sidebar définit la structure du menu de navigation qui apparaît à gauche de chaque page. Cette configuration est importante car elle guide vos lecteurs à travers votre documentation.

Starlight propose deux façons d’organiser le menu. La première consiste à lister manuellement chaque page, ce qui vous donne un contrôle total sur l’ordre et les titres affichés.

sidebar: [
  {
    label: 'Guides',
    items: [
      { label: 'Installation', slug: 'guides/installation' },
      { label: 'Configuration', slug: 'guides/configuration' },
      { label: 'Déploiement', slug: 'guides/deployment' },
    ],
  },
],

La seconde façon utilise l’autogénération. Starlight détecte automatiquement tous les fichiers d’un dossier et crée les entrées de menu correspondantes. Cette approche est pratique quand vous ajoutez fréquemment de nouvelles pages.

sidebar: [
  {
    label: 'Référence',
    autogenerate: { directory: 'reference' },
  },
],

Vous pouvez combiner les deux approches dans le même site. Par exemple, listez manuellement les guides importants pour contrôler leur ordre, et utilisez l’autogénération pour une section de référence qui évolue souvent.

Ajouter du contenu

Votre site est configuré, il est temps d’y ajouter vos propres pages. Starlight utilise le format Markdown (ou MDX pour des fonctionnalités avancées) pour le contenu.

Créer une nouvelle page

Pour créer une page, ajoutez un fichier .md ou .mdx dans le dossier src/content/docs/. L’emplacement du fichier détermine son URL. Par exemple, un fichier src/content/docs/guides/installation.md sera accessible à l’adresse /guides/installation/.

Chaque page commence par un frontmatter — un bloc de métadonnées encadré par trois tirets. Ces informations permettent à Starlight de générer le titre et la description de la page.

---
title: Guide d'installation
description: Apprenez à installer notre outil en quelques minutes.
---

Bienvenue dans le guide d'installation !

Le champ title définit le titre qui apparaît en haut de la page et dans l’onglet du navigateur. Le champ description est utilisé par les moteurs de recherche et apparaît dans les résultats de recherche. Après le frontmatter, vous écrivez votre contenu en Markdown standard.

Bonnes pratiques de rédaction

Une documentation efficace suit quelques principes qui facilitent la lecture et la compréhension.

Structurez votre contenu avec des titres. Utilisez ## pour les sections principales et ### pour les sous-sections. Évitez # qui est réservé au titre de la page (généré automatiquement depuis le frontmatter).

Expliquez le “pourquoi” avant le “comment”. Avant de donner une commande ou une instruction, prenez une phrase pour expliquer son objectif. Vos lecteurs retiendront mieux l’information s’ils comprennent son contexte.

Utilisez des exemples concrets. Plutôt que des explications abstraites, montrez des cas d’usage réels. Les exemples de code doivent utiliser des noms de fichiers et des valeurs réalistes, pas foo ou example.com.

Validez chaque étape. Après une instruction importante, indiquez comment le lecteur peut vérifier que tout s’est bien passé. “La commande doit afficher OK” ou “Vous devriez voir apparaître…” sont des formulations utiles.

Utiliser les composants Starlight

Starlight fournit des composants visuels qui enrichissent vos pages. Pour les utiliser, nommez votre fichier avec l’extension .mdx au lieu de .md, puis importez les composants au début du fichier.

Les encadrés (Aside) mettent en évidence des informations importantes. Ils existent en plusieurs variantes : note pour les informations complémentaires, tip pour les astuces, caution pour les avertissements, et danger pour les actions risquées.

Les étapes numérotées (Steps) présentent clairement une procédure à suivre dans l’ordre. Ce composant numérote automatiquement les étapes et les met en forme de manière distinctive.

Consultez la documentation Starlight pour découvrir tous les composants disponibles et leur syntaxe.

Construire et déployer votre site

Votre documentation est rédigée, il est temps de la publier sur internet. Cette section explique comment générer les fichiers finaux et les déployer sur un serveur.

Générer les fichiers statiques

Le serveur de développement que vous avez utilisé jusqu’ici n’est pas adapté à la production. Il consomme des ressources et n’optimise pas les fichiers. Pour créer la version finale de votre site, exécutez la commande de construction suivante.

npm run build

Cette commande compile tout votre projet et génère un dossier dist/ contenant des fichiers HTML, CSS et JavaScript optimisés. Ces fichiers sont prêts à être servis par n’importe quel serveur web — ils ne dépendent plus de Node.js.

La construction prend généralement quelques secondes à quelques minutes selon la taille de votre documentation. Le terminal affiche la progression et signale toute erreur qui empêcherait la génération.

Prévisualiser la version finale

Avant de déployer, vous pouvez prévisualiser le site construit pour vérifier que tout fonctionne correctement. Astro fournit une commande qui lance un serveur local servant les fichiers du dossier dist/.

npm run preview

Ouvrez l’adresse affichée dans le terminal (généralement http://localhost:4321) et naviguez dans votre site. Cette prévisualisation correspond exactement à ce que verront vos utilisateurs après le déploiement.

Déployer sur un serveur Nginx

Pour publier votre site, vous devez copier le contenu du dossier dist/ vers un serveur web. Nginx est un serveur populaire, performant et bien adapté aux sites statiques comme ceux générés par Astro.

La première étape consiste à transférer les fichiers sur votre serveur. L’outil rsync est idéal pour cette tâche car il ne copie que les fichiers modifiés, ce qui accélère les déploiements suivants. La commande suivante envoie le contenu de dist/ vers le dossier /var/www/ma-documentation sur votre serveur.

rsync -avz dist/ utilisateur@votre-serveur:/var/www/ma-documentation

Remplacez utilisateur par votre nom d’utilisateur sur le serveur, et votre-serveur par l’adresse IP ou le nom de domaine de votre machine. Le dossier de destination doit correspondre à la configuration de votre site Nginx.

Après le transfert, vérifiez que votre site est accessible en ouvrant son URL dans un navigateur. Si tout s’affiche correctement, votre documentation est en ligne !

Alternatives de déploiement

Si vous ne souhaitez pas gérer votre propre serveur, plusieurs plateformes hébergent gratuitement les sites statiques. Netlify, Vercel et GitHub Pages sont les plus populaires. Ces services se connectent à votre dépôt Git et reconstruisent automatiquement votre site à chaque modification.

La documentation Astro propose des guides détaillés pour chaque plateforme : guides de déploiement Astro.

Dépannage

Voici les problèmes les plus fréquents et leurs solutions.

Le serveur de développement ne démarre pas

Si la commande npm run dev échoue avec une erreur de dépendances, les bibliothèques n’ont probablement pas été installées correctement. Supprimez le dossier node_modules/ et le fichier package-lock.json, puis réexécutez l’installation des dépendances avec npm install.

Vérifiez d’abord que le fichier se trouve bien dans src/content/docs/ et qu’il possède un frontmatter valide avec au moins un champ title. Ensuite, vérifiez votre configuration sidebar dans astro.config.mjs : si vous listez les pages manuellement, votre nouvelle page doit y figurer ; si vous utilisez l’autogénération, le fichier doit être dans le bon dossier.

Les modifications n’apparaissent pas dans le navigateur

Le rechargement à chaud fonctionne généralement sans problème, mais certaines modifications (notamment dans astro.config.mjs) nécessitent de redémarrer le serveur. Arrêtez-le avec Ctrl+C puis relancez-le avec npm run dev.

La construction échoue avec des erreurs

Lisez attentivement le message d’erreur dans le terminal — il indique généralement le fichier et la ligne problématiques. Les causes fréquentes sont un frontmatter mal formaté (vérifiez les tirets et l’indentation), un lien vers une page inexistante, ou un composant MDX mal importé.

À retenir

Astro génère des pages HTML statiques ultra-rapides, idéales pour la documentation.
Starlight fournit tout ce dont un site de documentation a besoin : navigation, recherche, thèmes, responsive.
Les pages de contenu sont de simples fichiers Markdown dans src/content/docs/.
La configuration se fait dans astro.config.mjs, notamment pour la navigation latérale.
La commande npm run build génère un dossier dist/ prêt à être déployé sur n’importe quel serveur web.

Prochaines étapes

Le langage Markdown Maîtrisez la syntaxe Markdown pour rédiger efficacement votre documentation.

Démarrez avec MkDocs Découvrez une alternative Python pour créer des sites de documentation.

Générer une doc avec Docusaurus Explorez l'alternative React pour les sites de documentation.

Documentation officielle Starlight Approfondissez vos connaissances avec la documentation complète de Starlight.

Ressources complémentaires

Pour aller plus loin dans votre apprentissage d’Astro et Starlight, voici les ressources officielles les plus utiles.

Le site officiel d’Astro (astro.build) présente les fonctionnalités du framework et propose des tutoriels interactifs pour les débutants. C’est le meilleur point de départ si vous souhaitez comprendre l’écosystème global.

La documentation d’Astro (docs.astro.build) couvre en détail tous les aspects du framework : composants, routage, données, optimisation, et bien plus. Consultez-la quand vous avez besoin d’approfondir un sujet spécifique.

La documentation de Starlight (starlight.astro.build) explique toutes les fonctionnalités du thème : personnalisation, composants, internationalisation, intégrations. C’est votre référence pour tout ce qui concerne spécifiquement la documentation.

Le dépôt GitHub de Starlight (github.com/withastro/starlight) contient le code source, les issues et les discussions. Consultez-le pour signaler des bugs, proposer des améliorations, ou voir les fonctionnalités à venir.