Aller au contenu
Starlight

Composants

Les composants vous permettent de réutiliser facilement un élément d’interface utilisateur ou de style de manière cohérente. Il peut s’agir par exemple d’une carte de lien ou d’une intégration YouTube. Starlight prend en charge l’utilisation de composants dans les fichiers MDX et fournit des composants courants que vous pouvez utiliser.

Pour en savoir plus sur la création de composants, consultez les Astro Docs.

Utilisation d’un composant

Vous pouvez utiliser un composant en l’important dans votre fichier MDX et en le rendant sous forme de balise JSX. Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration import :

src/content/docs/exemple.mdx
---
title: Bienvenue dans ma documentation
---


import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';


<SomeComponent prop="something" />


<AnotherComponent>
  Les composants peuvent également contenir du **contenu imbriqué**.
</AnotherComponent>

Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n’importe quel cadre d’interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine) dans vos fichiers MDX. Pour en savoir plus sur l’utilisation de composants dans MDX, consultez la documentation Astro.

Compatibilité avec les styles de Starlight

Starlight applique des styles par défaut à votre contenu Markdown, par exemple en ajoutant une marge entre les éléments. Si ces styles entrent en conflit avec l’apparence de votre composant, définissez la classe not-content sur votre composant pour les désactiver.

src/components/Exemple.astro
<div class="not-content">
  <p>Contenu non affecté par les styles par défaut de Starlight.</p>
</div>

Composants intégrés

Starlight fournit quelques composants intégrés pour les cas d’utilisation courants de la documentation. Ces composants sont disponibles dans le paquet @astrojs/starlight/components.

Onglets

Vous pouvez afficher une interface à onglets en utilisant les composants <Tabs> et <TabItem>. Chaque <TabItem> doit avoir un label à afficher aux utilisateurs.

src/content/docs/exemple.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';


<Tabs>
  <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Moons">Io, Europa, Ganymede</TabItem>
</Tabs>

Le code ci-dessus génère les onglets suivants sur la page :

Sirius, Vega, Betelgeuse

Cartes

Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant <Card>. Enveloppez plusieurs cartes dans le composant <CardGrid> pour afficher les cartes côte à côte lorsqu’il y a suffisamment d’espace.

Une <Card> nécessite un title et peut optionellement inclure un attribut icon fixé au nom de l’une des icônes intégrées de Starlight.

src/content/docs/exemple.mdx
import { Card, CardGrid } from '@astrojs/starlight/components';


<Card title="Check this out">
  Contenu intéressant que vous souhaitez mettre en évidence.
</Card>


<CardGrid>
  <Card title="Stars" icon="star">
    Sirius, Vega, Betelgeuse
  </Card>
  <Card title="Moons" icon="moon">
    Io, Europa, Ganymede
  </Card>
</CardGrid>

Le code ci-dessus génère ce qui suit sur la page :

Check this out

Contenu intéressant que vous souhaitez mettre en évidence.

Stars

Sirius, Vega, Betelgeuse

Moons

Io, Europa, Ganymede

Cartes de Liaison

Utilisez le composant <LinkCard> pour créer un lien bien visible vers différentes pages.

Une <LinkCard> nécessite les attributs title et href. Vous pouvez optionellement inclure une courte description ou d’autres attributs de lien tels que target.

Regroupez plusieurs composants <LinkCard> dans <CardGrid> pour afficher les cartes côte à côte lorsqu’il y a suffisamment d’espace.

src/content/docs/exemple.mdx
import { LinkCard, CardGrid } from '@astrojs/starlight/components';


<LinkCard
  title="Personnalisation de Starlight"
  description="Apprenez à personnaliser votre site Starlight avec vos propres styles, vos polices et bien plus encore."
  href="/fr/guides/customization/"
/>


<CardGrid>
  <LinkCard
    title="Création de contenu en Markdown"
    href="/fr/guides/authoring-content/"
  />
  <LinkCard title="Composants" href="/fr/guides/components/" />
</CardGrid>

Le code ci-dessus génère ce qui suit sur la page :

Personnaliser Starlight Apprenez à personnaliser votre site Starlight avec vos propres styles, vos polices et bien plus encore.
Création de contenu en Markdown
Composants

Icônes

Starlight fournit un ensemble d’icônes courantes que vous pouvez afficher dans votre contenu à l’aide du composant <Icon>.

Chaque <Icon> nécessite un name et peut optionellement inclure un attribut label, size et color.

src/content/docs/exemple.mdx
import { Icon } from '@astrojs/starlight/components';


<Icon name="star" color="goldenrod" size="2rem" />

Le code ci-dessus génère ce qui suit sur la page :

Toutes les icônes

Une liste de toutes les icônes disponibles est affichée ci-dessous avec leurs noms associés. Cliquez sur une icône pour copier le code du composant.