Aller au contenu
Starlight

Barre latérale de navigation

Une barre latérale bien organisée est une des clés d’une bonne documentation, car c’est l’une des principales méthodes de navigation qui sera utilisée par les utilisateurs de votre site. Starlight fournit un ensemble complet d’options pour personnaliser la structure et le contenu de votre barre latérale.

Barre latérale par défaut

Par défaut, Starlight générera automatiquement une barre latérale basée sur la structure du système de fichiers de votre documentation, en utilisant la propriété title de chaque fichier comme entrée de la barre latérale.

Par exemple, pour la structure de fichiers suivante :

  • Répertoiresrc/
    • Répertoirecontent/
      • Répertoiredocs/
        • Répertoireconstellations/
          • andromede.md
          • orion.md
        • Répertoireetoiles/
          • betelgeuse.md

La barre latérale suivante sera automatiquement générée :

Pour en savoir plus sur les barres latérales générées automatiquement, consultez la section sur les groupes générés automatiquement.

Ajouter des liens et des groupes de liens

Pour configurer les liens et groupes de liens (dans un en-tête rétractable) de votre barre latérale, utilisez la propriété starlight.sidebar dans le fichier astro.config.mjs.

En combinant les liens et les groupes, vous pouvez créer une grande variété de structures de barre latérale.

Liens internes

Ajoutez un lien vers une page située dans src/content/docs/ en utilisant un objet avec la propriété slug. Le titre de la page liée sera utilisé comme étiquette par défaut.

Par exemple, avec la configuration suivante :

starlight({
  sidebar: [
    { slug: 'constellations/andromede' },
    { slug: 'constellations/orion' },
  ],
});

Et la structure de fichiers suivante :

  • Répertoiresrc/
    • Répertoirecontent/
      • Répertoiredocs/
        • Répertoireconstellations/
          • andromede.md
          • orion.md

La barre latérale suivante sera générée :

Pour personnaliser les valeurs inférées du frontmatter de la page liée, vous pouvez ajouter les propriétés label, translations et attrs.

Consultez la section « Personnaliser les liens générés automatiquement dans le frontmatter » pour plus de détails sur comment contrôler l’apparence de la barre latérale à partir du frontmatter de la page.

Syntaxe simplifiée pour les liens internes

Les liens internes peuvent également être spécifiés en utilisant uniquement une chaîne de caractères comme raccourci pour le slug de la page.

Par exemple, la configuration suivante est équivalente à la configuration ci-dessus, qui utilisait slug :

starlight({
  sidebar: ['constellations/andromede', 'constellations/orion'],
});

Autres liens

Ajoutez un lien vers une page externe ou ne faisant pas partie de votre documentation en utilisant un objet avec les propriétés label et link.

starlight({
  sidebar: [
    // Un lien vers une page ne faisant pas partie de la documentation.
    { label: 'Boutique de météores', link: '/boutique/' },
    // Un lien externe vers le site de la NASA.
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Groupes

Vous pouvez donner de la structure à votre barre latérale en regroupant des liens connexes sous un en-tête rétractable. Les groupes peuvent contenir à la fois des liens et d’autres sous-groupes.

Ajoutez un groupe en utilisant un objet avec les propriétés label et items. Le label sera utilisé comme en-tête pour le groupe. Ajoutez des liens ou des sous-groupes au tableau items.

starlight({
  sidebar: [
    // Un groupe de liens avec le label "Constellations".
    {
      label: 'Constellations',
      items: [
        'constellations/carene',
        'constellations/centaure',
        // Un groupe de liens imbriqué pour les constellations saisonnières.
        {
          label: 'Saisonnières',
          items: [
            'constellations/andromede',
            'constellations/orion',
            'constellations/petite-ourse',
          ],
        },
      ],
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Groupes générés automatiquement

Starlight peut générer automatiquement un groupe dans votre barre latérale en fonction d’un répertoire de votre documentation. Cela est utile lorsque vous ne souhaitez pas entrer manuellement chaque élément de la barre latérale dans un groupe.

Par défaut, les pages sont triées par ordre alphabétique selon le slug du fichier.

Ajoutez un groupe généré automatiquement en utilisant un objet avec les propriétés label et autogenerate. La configuration de autogenerate doit spécifier le répertoire à utiliser pour les entrées de la barre latérale avec la propriété directory. Par exemple, avec la configuration suivante :

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Génère automatiquement un groupe de liens pour le répertoire "constellations".
      autogenerate: { directory: 'constellations' },
    },
  ],
});

Et la structure de fichiers suivante :

  • Répertoiresrc/
    • Répertoirecontent/
      • Répertoiredocs/
        • Répertoireconstellations/
          • carene.md
          • centaure.md
          • Répertoiresaisonnieres/
            • andromede.md

La barre latérale suivante sera générée :

Personnaliser les liens générés automatiquement dans le frontmatter

Utilisez le champ sidebar du frontmatter dans différentes pages pour personnaliser les liens générés automatiquement.

Les options du frontmatter pour la barre latérale vous permettent de définir une étiquette personnalisée ou d’ajouter un badge à un lien, de masquer un lien de la barre latérale, ou de définir une pondération de tri personnalisée.

src/content/docs/exemple.md
---
title: Ma page
sidebar:
  # Définit une étiquette personnalisée pour le lien dans la barre latérale
  label: Étiquette personnalisée
  # Définit un ordre personnalisé pour le lien
  # (les nombres plus petits sont affichés plus haut)
  order: 2
  # Ajoute un badge au lien
  badge:
    text: Nouveau
    variant: tip
---

Un groupe généré automatiquement incluant une page avec le frontmatter ci-dessus générera la barre latérale suivante :

Badges

Les liens, groupes et groupes générés automatiquement peuvent inclure une propriété badge pour afficher un badge à côté de leurs étiquettes.

starlight({
  sidebar: [
    {
      label: 'Étoiles',
      items: [
        // Un lien avec un badge "Supergéante".
        {
          slug: 'etoiles/persei',
          badge: 'Supergéante',
        },
      ],
    },
    // Un groupe généré automatiquement avec un badge "Obsolète".
    {
      label: 'Lunes',
      badge: 'Obsolète',
      autogenerate: { directory: 'lunes' },
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Variantes de badges et style personnalisé

Personnalisez le style du badge en utilisant un objet avec les propriétés text, variant, et class.

La propriété text représente le contenu à afficher (par exemple, “Nouveau”). Par défaut, le badge utilise la couleur d’accentuation de votre site. Pour utiliser un style de badge intégré, définissez la propriété variant à l’une des valeurs suivantes : note, tip, danger, caution ou success.

Facultativement, vous pouvez créer un style de badge personnalisé en définissant la propriété class à un nom de classe CSS.

starlight({
  sidebar: [
    {
      label: 'Étoiles',
      items: [
        // Un lien avec un badge "Ébauche" jaune.
        {
          slug: 'etoiles/sirius',
          badge: { text: 'Ébauche', variant: 'caution' },
        },
      ],
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Attributs HTML personnalisés

Les liens peuvent aussi inclure une propriété attrs pour ajouter des attributs HTML personnalisés à l’élément du lien.

Dans l’exemple suivant, attrs est utilisé pour ajouter un attribut target="_blank", afin que le lien s’ouvre dans un nouvel onglet, et pour appliquer un attribut style personnalisé pour mettre en italique l’étiquette du lien :

starlight({
  sidebar: [
    {
      label: 'Ressources',
      items: [
        // Un lien externe vers le site de la NASA s'ouvrant dans un nouvel onglet.
        {
          label: 'NASA',
          link: 'https://www.nasa.gov/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Internationalisation

Utilisez la propriété translations sur les liens et les groupes pour traduire l’étiquette du lien ou du groupe pour chaque langue prise en charge en spécifiant une étiquette d’identification de langue BCP-47, par exemple "en", "ar" ou "zh-CN", comme clé et l’étiquette traduite comme valeur. La propriété label sera utilisée pour la langue par défaut et pour les langues sans traduction.

starlight({
  sidebar: [
    {
      label: 'Constellations',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: 'Andromède',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromede',
        },
        {
          label: 'Scorpion',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpion',
        },
      ],
    },
  ],
});

Parcourir la documentation en portugais brésilien générera la barre latérale suivante :

Internationalisation avec des liens internes

Les liens internes utiliseront automatiquement les titres de page traduits depuis le frontmatter du contenu par défaut :

starlight({
  sidebar: [
    {
      label: 'Constellations',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        { slug: 'constellations/andromede' },
        { slug: 'constellations/scorpion' },
      ],
    },
  ],
});

Parcourir la documentation en portugais brésilien générera la barre latérale suivante :

Pour les sites multilingues, la valeur de la propriété slug n’inclut pas la portion de langue dans l’URL. Par exemple, si vous avez des pages à en/intro et pt-br/intro, le slug est intro lors de la configuration de la barre latérale.

Groupes rétractables

Les groupes de liens peuvent être rétractés par défaut en définissant la propriété collapsed à true.

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Rétracte le groupe par défaut.
      collapsed: true,
      items: ['constellations/andromede', 'constellations/orion'],
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Les groupes générés automatiquement respectent la valeur collapsed de leur groupe parent :

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Rétracte le groupe et ses sous-groupes générés automatiquement
      // par défaut.
      collapsed: true,
      autogenerate: { directory: 'constellations' },
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :

Ce comportement peut être remplacé en définissant la propriété autogenerate.collapsed.

starlight({
  sidebar: [
    {
      label: 'Constellations',
      // Ne rétracte pas le groupe "Constellations" mais rétracte ses
      // sous-groupes générés automatiquement.
      collapsed: false,
      autogenerate: { directory: 'constellations', collapsed: true },
    },
  ],
});

La configuration ci-dessus génère la barre latérale suivante :