Aller au contenu
Starlight

Référence du frontmatter

Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur frontmatter. Par exemple, une page normale peut définir les champs title et description :

src/content/docs/exemple.md
---
title: A propos de ce projet
description: En savoir plus sur le projet sur lequel je travaille.
---


Bienvenue sur la page "à propos" !

Champs du frontmatter

title (obligatoire)

Type : string

Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page.

description

Type : string

La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux.

slug

type: string

Remplace le slug de la page. Consultez « Définition d’un slug personnalisé » dans la documentation d’Astro pour plus de détails.

editUrl

Type : string | boolean

Remplace la configuration globale editLink. Mettez false pour désactiver le lien “Modifier cette page” pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable.

Type : HeadConfig[]

Vous pouvez ajouter des balises supplémentaires au champ <head> de votre page en utilisant le champ head frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d’autres balises à une seule page. Similaire à l’option globale head.

src/content/docs/exemple.md
---
title: A propos de nous
head:
  # Utiliser une balise <title> personnalisée
  - tag: title
    content: Titre personnalisé à propos de nous
---

tableOfContents

Type : false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

Remplace la configuration globale tableOfContents. Personnalisez les niveaux d’en-tête à inclure ou mettez false pour cacher la table des matières sur cette page.

src/content/docs/exemple.md
---
title: Pagee avec seulement des H2s dans la table des matières
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---
src/content/docs/exemple.md
---
title: Page sans table des matières
tableOfContents: false
---

template

Type : 'doc' | 'splash'
Par défaut : 'doc'

Définit le modèle de mise en page pour cette page. Les pages utilisent la mise en page 'doc'’ par défaut. La valeur 'splash'' permet d’utiliser une mise en page plus large, sans barres latérales, conçue pour les pages d’atterrissage.

hero

Type : HeroConfig

Ajoute un composant héros en haut de la page. Fonctionne bien avec template : splash.

Par exemple, cette configuration montre quelques options communes, y compris le chargement d’une image depuis votre dépôt.

src/content/docs/exemple.md
---
title: Ma page d'accueil
template: splash
hero:
  title: 'Mon projet : Stellar Stuffer Sooner'
  tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil.
  image:
    alt: Un logo aux couleurs vives et scintillantes
    file: ../../assets/logo.png
  actions:
    - text: En savoir plus
      link: /getting-started/
      icon: right-arrow
      variant: primary
    - text: Voir sur GitHub
      link: https://github.com/astronaut/my-project
      icon: external
      attrs:
        target: _blank
        rel: noopener
---

Vous pouvez afficher différentes versions de l’image de premier plan en mode clair et sombre.

src/content/docs/exemple.md
---
hero:
  image:
    alt: Un logo scintillant aux couleurs vives
    dark: ../../assets/logo-dark.png
    light: ../../assets/logo-light.png
---

HeroConfig

interface HeroConfig {
  title?: string;
  tagline?: string;
  image?:
    | {
        // Chemin relatif vers une image dans votre dépôt.
        file: string;
        // Alternative textuelle pour rendre l'image accessible aux technologies d'assistance.
        alt?: string;
      }
    | {
        // Chemin relatif vers une image dans votre dépôt à utiliser pour le mode sombre.
        dark: string;
        // Chemin relatif vers une image dans votre dépôt à utiliser pour le mode clair.
        light: string;
        // Alternative textuelle pour rendre l'image accessible aux technologies d'assistance.
        alt?: string;
      }
    | {
        // HTML brut à utiliser dans l'emplacement (slot) de l'image.
        // Peut être une balise `<img>` personnalisée ou une balise `<svg>` en ligne.
        html: string;
      };
  actions?: Array<{
    text: string;
    link: string;
    variant: 'primary' | 'secondary' | 'minimal';
    icon: string;
    attrs?: HTMLAttributes<"a">;
  }>;
}

Type : { content: string }

Montrera une bannière d’annonce en haut de cette page.

La valeur content peut inclure du HTML pour les liens ou d’autres contenus. Par exemple, cette page affiche une bannière comprenant un lien vers example.com.

src/content/docs/exemple.md
---
title: Page avec une bannière
banner:
  content: |
    On a lancé quelque chose de cool !
    <a href="https://example.com">Allez-y</a>
---

lastUpdated

Type : Date | boolean

Remplace la configuration globale lastUpdated. Si une date est spécifiée, elle doit être un horodatage YAML valide et remplacera la date stockée dans l’historique Git pour cette page.

src/content/docs/exemple.md
---
title: Page avec une date de dernière mise à jour personnalisée
lastUpdated: 2022-08-09
---

prev

Type : boolean | string | { link?: string; label?: string }

Remplace la configuration globale pagination. Si un string est spécifié, le texte du lien généré sera remplacé et si un objet est spécifié, le lien et le texte seront remplacés.

src/content/docs/exemple.md
---
# Masquer le lien de la page précédente
prev: false
---
src/content/docs/exemple.md
---
# Remplacer le texte du lien de la page
prev: Poursuivre the tutorial
---
src/content/docs/exemple.md
---
# Remplacer le lien et le texte de la page
prev:
  link: /unrelated-page/
  label: Consultez cette autre page
---

next

Type : boolean | string | { link?: string; label?: string }

La même chose que prev mais pour le lien de la page suivante.

src/content/docs/exemple.md
---
# Masquer le lien de la page suivante
next: false
---

pagefind

Type : boolean
Par défaut : true

Définit si cette page doit être incluse dans l’index de recherche de Pagefind. Définissez la valeur à false pour exclure une page des résultats de recherche :

src/content/docs/exemple.md
---
# Exclut cette page de l'index de recherche
pagefind: false
---

Type : SidebarConfig

Contrôler l’affichage de cette page dans la barre latérale, lors de l’utilisation d’un groupe de liens généré automatiquement.

SidebarConfig

interface SidebarConfig {
  label?: string;
  order?: number;
  hidden?: boolean;
  badge?: string | BadgeConfig;
  attrs?: Record<string, string | number | boolean | undefined>;
}

label

Type : string
Par défaut : title de la page

Définir l’étiquette de cette page dans la barre latérale lorsqu’elle est affichée dans un groupe de liens généré automatiquement.

src/content/docs/exemple.md
---
title: About this project
sidebar:
  label: About
---

order

Type : number

Contrôler l’ordre de cette page lors du tri d’un groupe de liens généré automatiquement. Les numéros inférieurs sont affichés plus haut dans le groupe de liens.

src/content/docs/exemple.md
---
title: Page à afficher en premier
sidebar:
  order: 1
---

hidden

Type : boolean
Par défaut : false

Empêche cette page d’être incluse dans un groupe de liens généré automatiquement.

src/content/docs/exemple.md
---
title: Page à masquer de la barre latérale générée automatiquement
sidebar:
  hidden: true
---

badge

Type : string | BadgeConfig

Ajoute un badge à la page dans la barre latérale lorsqu’elle est affichée dans un groupe de liens généré automatiquement. Lors de l’utilisation d’une chaîne de caractères, le badge sera affiché avec une couleur d’accentuation par défaut. Passez éventuellement un objet BadgeConfig avec les propriétés text et variant pour personnaliser le badge.

src/content/docs/exemple.md
---
title: Page avec un badge
sidebar:
  # Utilise la variante par défaut correspondant à la couleur d'accentuation de votre site
  badge: Nouveau
---
src/content/docs/exemple.md
---
title: Page avec un badge
sidebar:
  badge:
    text: Expérimental
    variant: caution
---

attrs

Type : Record<string, string | number | boolean | undefined>

Attributs HTML à ajouter au lien de la page dans la barre latérale lorsqu’il est affiché dans un groupe de liens généré automatiquement.

src/content/docs/exemple.md
---
title: Page s'ouvrant dans un nouvel onglet
sidebar:
  # Ouvre la page dans un nouvel onglet
  attrs:
    target: _blank
---

Personnaliser le schéma du frontmatter

Le schéma du frontmatter de la collection de contenus docs de Starlight est configuré dans src/content/config.ts en utilisant l’utilitaire docsSchema() :

src/content/config.ts
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';


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

Consultez « Définir un schéma de collection de contenus » dans la documentation d’Astro pour en savoir plus sur les schémas de collection de contenus.

docsSchema() accepte les options suivantes :

extend

Type : Schéma Zod ou fonction qui retourne un schéma Zod
Par défaut : z.object({})

Étendez le schéma de Starlight avec des champs supplémentaires en définissant extend dans les options de docsSchema(). La valeur doit être un schéma Zod.

Dans l’exemple suivant, nous définissons un type plus strict pour description pour le rendre obligatoire et ajouter un nouveau champ category facultatif :

src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';


export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: z.object({
        // Rend un champ de base obligatoire au lieu de facultatif.
        description: z.string(),
        // Ajoute un nouveau champ au schéma.
        category: z.enum(['tutoriel', 'guide', 'référence']).optional(),
      }),
    }),
  }),
};

Pour tirer parti de l’utilitaire image() d’Astro, utilisez une fonction qui retourne votre extension de schéma :

src/content/config.ts
import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';


export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: ({ image }) => {
        return z.object({
          // Ajoute un champ qui doit être résolu par une image locale.
          cover: image(),
        });
      },
    }),
  }),
};