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 les 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
Ajoutez un lien vers une page interne ou externe en utilisant un objet avec les propriétés label
et link
.
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
.
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 :
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.
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.
La configuration ci-dessus génère la barre latérale suivante :
Variantes de badges
Personnalisez le style du badge en utilisant un objet avec les propriétés text
et variant
.
La propriété text
représente le contenu à afficher (par exemple, “Nouveau”).
Remplacez le style default
, qui utilise la couleur d’accentuation de votre site, en définissant la propriété variant
avec l’une des valeurs suivantes : note
, tip
, danger
, caution
ou success
.
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 :
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.
Parcourir la documentation en portugais brésilien générera la barre latérale suivante :
Groupes rétractables
Les groupes de liens peuvent être rétractés par défaut en définissant la propriété collapsed
à true
.
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 :
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
.
La configuration ci-dessus génère la barre latérale suivante :