Pages

Starlight génère les pages HTML de votre site en fonction de votre contenu, avec des options flexibles fournies via le frontmatter du fichier Markdown. En outre, les projets Starlight bénéficient d’un accès complet aux puissants outils de génération de pages d’Astro. Ce guide montre comment fonctionne la génération de pages dans Starlight.

Pages de contenu

Formats de fichiers

Starlight prend en charge la création de contenu en Markdown et MDX sans aucune configuration requise. Vous pouvez ajouter la prise en charge de Markdoc en suivant le guide « Markdoc ».

Ajouter des pages

Ajoutez de nouvelles pages à votre site en créant des fichiers .md ou .mdx dans src/content/docs/. Utilisez des sous-dossiers pour organiser vos fichiers et pour créer plusieurs segments de chemin.

Par exemple, la structure de fichier suivante générera des pages à exemple.com/hello-world et exemple.com/reference/faq :

• Répertoiresrc/

  • Répertoirecontent/

    • Répertoiredocs/

      • hello-world.md
      • Répertoirereference/

        • faq.md

Frontmatter avec sûreté du typage

Toutes les pages Starlight partagent un ensemble commun de propriétés de frontmatter personnalisable pour contrôler l’apparence de la page :

---
title: Bonjour tout le monde !
description: Voici une page de mon site propulsé par Starlight
---

Si vous oubliez quelque chose d’important, Starlight vous le fera savoir.

Pages personnalisées

Pour les cas d’utilisation avancés, vous pouvez ajouter des pages personnalisées en créant un répertoire src/pages/. Le répertoire src/pages/ utilise le routage basé sur les fichiers d’Astro et inclut la prise en charge des fichiers .astro parmi d’autres formats de pages. Ceci est utile si vous avez besoin de créer des pages avec une mise en page complètement personnalisée ou de générer une page à partir d’une source de données alternative.

Par exemple, ce projet mélange du contenu Markdown dans src/content/docs/ avec des routes Astro et HTML dans src/pages/ :

• Répertoiresrc/

  • Répertoirecontent/

    • Répertoiredocs/

      • hello-world.md
  • Répertoirepages/

    • custom.astro
    • archived.html

Pour en savoir plus, consultez le guide « Pages » dans la documentation d’Astro.

Utiliser le design de Starlight dans des pages personnalisées

Pour utiliser la mise en page de Starlight dans des pages personnalisées, englobez le contenu de votre page avec le composant <StarlightPage />. Cela peut s’avérer utile si vous générez du contenu de manière dynamique, mais que vous souhaitez tout de même utiliser le design de Starlight. Ce composant doit être la première importation dans votre fichier pour configurer les couches de cascade et garantir un ordre prévisible pour le CSS.

Pour ajouter des liens d’ancrage vers des en-têtes avec une apparence équivalente aux liens d’ancrage Markdown de Starlight, vous pouvez utiliser le composant <AnchorHeading> dans vos pages personnalisées.

src/pages/page-perso/exemple.astro

---
// Importer le composant `<StarlightPage>` en premier pour configurer les
// couches de cascade.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';

// Importer tous les autres composants que vous souhaitez utiliser dans votre
// page personnalisée.
import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
import CustomComponent from './CustomComponent.astro';
---

<StarlightPage frontmatter={{ title: 'Ma page personnalisée' }}>
  <p>Il s'agit d'une page personnalisée avec un composant personnalisé :</p>
  <CustomComponent />

  <AnchorHeading level="2" id="en-savoir-plus">En savoir plus</AnchorHeading>
  <p>
    <a href="https://starlight.astro.build/">
      Consulter la documentation de Starlight
    </a>
  </p>
</StarlightPage>

Composant <StarlightPage>

Le composant <StarlightPage /> affiche une page complète de contenu en utilisant la mise en page et les styles de Starlight.

---
// Importer le composant `<StarlightPage>` en premier pour configurer les
// couches de cascade.
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
---

<StarlightPage frontmatter={{ title: 'Ma page personnalisée' }}>
  <!-- Contenu de la page personnalisée -->
</StarlightPage>

En raison du fonctionnement de l’ordre d’importation dans Astro, le composant <StarlightPage /> doit être la première importation dans votre fichier pour configurer les couches de cascade utilisées en interne par Starlight pour gérer l’ordre de ses styles.

Le composant <StarlightPage /> accepte les props suivantes.

frontmatter

Obligatoire
Type : StarlightPageFrontmatter

Définit les propriétés du frontmatter pour cette page, similaire au frontmatter dans les pages Markdown. La propriété title est obligatoire et toutes les autres propriétés sont optionnelles.

Les propriétés suivantes diffèrent du frontmatter des fichiers Markdown :

• La propriété slug n’est pas prise en charge et est automatiquement définie en fonction de l’URL de la page personnalisée.
• L’option editUrl nécessite une URL pour afficher un lien d’édition.
• La propriété sidebar du frontmatter permettant de personnaliser l’affichage de la page dans les groupes de liens autogénérés n’est pas disponible. Les pages utilisant le composant <StarlightPage /> ne font pas partie d’une collection et ne peuvent pas être ajoutées à un groupe de liens autogénérés.
• L’option draft affiche uniquement une note indiquant que la page est une ébauche, mais ne l’exclut pas automatiquement des déploiements en production.

sidebar

Type : SidebarItem[]
Par défaut : la barre latérale générée en fonction de la configuration globale sidebar

Fournit une barre latérale de navigation personnalisée pour cette page. Si elle n’est pas définie, la page utilisera la barre latérale globale par défaut.

Par exemple, la page suivante remplace la barre latérale par défaut par un lien vers la page d’accueil et un groupe de liens vers diverses autres pages personnalisées.

<StarlightPage
  frontmatter={{ title: 'Orion' }}
  sidebar={[
    { label: 'Accueil', link: '/' },
    {
      label: 'Constellations',
      items: [
        { label: 'Andromède', link: '/andromède/' },
        { label: 'Orion', link: '/orion/' },
        {
          label: 'La Petite Ourse',
          link: '/la-petite-ourse/',
          badge: 'Ébauche',
        },
      ],
    },
  ]}
>
  Exemple de contenu.
</StarlightPage>

Consultez le guide « Barre latérale de navigation » pour en savoir plus sur les options disponibles pour personnaliser la barre latérale.

hasSidebar

Type : boolean
Par défaut : false si frontmatter.template est 'splash', autrement true

Contrôle l’affichage ou non de la barre latérale sur cette page.

headings

Type : { depth: number; slug: string; text: string }[]
Par défaut : []

Fournit un tableau de tous les en-têtes de cette page. Starlight générera la table des matières de la page à partir de ces en-têtes s’ils sont fournis.

dir

Type : 'ltr' | 'rtl'
Par défaut : le sens d’écriture pour la locale actuelle

Définit le sens d’écriture pour le contenu de la page.

lang

Type : string
Par défaut : la langue de la locale actuelle

Définit l’étiquette d’identification BCP-47 pour le contenu de cette page, par exemple en, zh-CN, ou pt-BR.

isFallback

Type : boolean
Par défaut : false

Indique si cette page utilise un contenu de repli parce qu’il n’y a pas de traduction pour la langue actuelle.

Composant <AnchorHeading>

Le composant <AnchorHeading> affiche un élément d’en-tête HTML avec un lien d’ancrage cliquable avec une apparence équivalente aux styles Markdown de Starlight.

---
import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
---

<AnchorHeading level="2" id="sous-rubrique">Sous rubrique</AnchorHeading>

Il accepte les props suivantes ainsi que n’importe quel autre attribut HTML universel valide.

level

Obligatoire
Type : 1 | 2 | 3 | 4 | 5 | 6

Le niveau d’en-tête à afficher. Par exemple, level="1" afficherait un élément <h1>.

id

Obligatoire
Type : string

Un identifiant unique pour cet en-tête. Celui-ci sera utilisé comme attribut id de l’en-tête affiché et l’icône d’ancrage rendirigera vers celui-ci.