Pages

Starlight génère les pages HTML de votre site en fonction de votre contenu, avec des options flexibles fournies par le biais du frontmatter en 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 du frontmatter personnalisable qui permet de 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 le support des fichiers .astro parmi d’autres formats de pages. Ceci est utile si vous avez besoin de construire 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 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.

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

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
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.

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

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

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 en Markdown :

• La propriété slug n’est pas supportée 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 titres de cette page. Starlight générera la table des matières de la page à partir de ces titres 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.