Installation manuelle

La façon la plus rapide de créer un nouveau site Starlight est d’utiliser create astro comme indiqué dans le guide de démarrage. Si vous voulez ajouter Starlight à un projet Astro existant, ce guide vous expliquera comment faire.

Configurer Starlight

Pour suivre ce guide, vous aurez besoin d’un projet Astro existant.

Ajouter l’intégration Starlight

Starlight est une intégration Astro. Ajoutez-la à votre site en exécutant la commande astro add dans le répertoire racine de votre projet :

npm

npx astro add starlight

pnpm

pnpm astro add starlight

Yarn

yarn astro add starlight

Cela installera les dépendances requises et ajoutera Starlight au tableau integrations dans votre fichier des configuration Astro.

Configurer l’intégration

L’intégration Starlight est configurée dans votre fichier astro.config.mjs.

Ajoutez un titre avec la propriété title pour commencer :

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Mon ravissant site de documentation',
    }),
  ],
});

Retrouvez toutes les options disponibles dans la référence de configuration Starlight.

Configurer les collections de contenu

Starlight s’appuie sur les collections de contenu d’Astro, qui sont configurées dans le fichier src/content.config.ts.

Créez ou mettez à jour le fichier de configuration du contenu, en ajoutant une collection docs qui utilise les docsLoader et docsSchema de Starlight :

src/content.config.ts

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

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

Starlight supporte également l’option legacy.collections où les collections sont gérées en utilisant l’implémentation de collections de contenu héritée. Celà est utile si vous avez un projet Astro existant et que vous ne pouvez pas apporter de modifications aux collections pour utiliser un chargeur.

Ajouter du contenu

Starlight est maintenant configuré et il est temps d’ajouter du contenu !

Créez un repetoire src/content/docs/ et commencez par ajouter un fichier index.md. Ce sera la page d’accueil de votre nouveau site :

src/content/docs/index.md

---
title: Ma documentation
description: En savoir plus sur mon projet dans ce site de documentation construit avec Starlight.
---

Bienvenue dans mon projet !

Starlight utilise une stratégie de routage basée sur les fichiers, ce qui signifie que chaque fichier Markdown, MDX ou Markdoc dans src/content/docs/ deviendra une page de votre site. Les métadonnées du frontmatter (les champs title et description dans l’exemple ci-dessus) peuvent modifier la façon dont chaque page est affichée. Retrouvez toutes les options disponibles dans la référence du frontmatter.

Astuce pour les sites existants

Si vous avez un projet d’Astro existant, vous pouvez utiliser Starlight pour ajouter rapidement une section de documentation à votre site.

Utiliser Starlight dans un sous-chemin

Pour ajouter toutes les pages Starlight dans un sous-chemin, placez tout votre contenu de documentation dans un sous-répertoire de src/content/docs/.

Par exemple, si les pages de Starlight doivent toutes commencer par /guides/, ajoutez votre contenu dans le répertoire src/content/docs/guides/ :

• Répertoiresrc/

  • Répertoirecontent/

    • Répertoiredocs/

      • Répertoireguides/

        • guide.md
        • index.md
  • Répertoirepages/

    • …
• astro.config.mjs

À l’avenir, nous prévoyons de mieux supporter ce cas d’utilisation pour éviter le besoin du répertoire supplémentaire dans src/content/docs/.

Utiliser Starlight avec SSR

Pour activer le SSR, suivez le guide « Adaptateurs de rendu à la demande » dans la documentation d’Astro pour ajouter un adaptateur serveur à votre projet Starlight.

Les pages de documentation générées par Starlight sont pré-rendues par défaut, quel que soit le mode de rendu de votre projet. Pour désactiver le pré-rendu de vos pages Starlight, définissez l’option de configuration prerender à false.