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 :

Stars

Sirius, Vega, Betelgeuse

Moons

Io, Europa, Ganymede

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

Astuce

Utilisez une grille de cartes sur votre page d’accueil pour afficher les principales caractéristiques de votre projet. Ajoutez l’attribut stagger pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel :

<CardGrid stagger>
  <!-- cards -->
</CardGrid>

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.

up-caret down-caret right-caret right-arrow left-arrow bars translate pencil pen document add-document setting external moon sun laptop open-book information magnifier forward-slash close error warning approve-check-circle approve-check rocket star puzzle list-format random github gitlab bitbucket codePen discord gitter twitter x.com mastodon codeberg youtube threads linkedin twitch microsoftTeams instagram stackOverflow telegram rss facebook email reddit patreon slack matrix openCollective

Code

Utilisez le composant <Code> pour afficher du code avec coloration syntaxique lorsque l’utilisation d’un bloc de code Markdown n’est pas possible, par exemple, pour afficher des données provenant de sources externes comme des fichiers, des bases de données ou des API.

Consultez la documentation du « composant Code » d’Expressive Code pour plus de détails sur les props que <Code> supporte.

src/content/docs/exemple.mdx

import { Code } from '@astrojs/starlight/components';

export const exampleCode = `console.log("Cela peut provenir d'un fichier ou d'un CMS !");`;
export const fileName = 'exemple.js';
export const highlights = ['fichier', 'CMS'];

<Code code={exampleCode} lang="js" title={fileName} mark={highlights} />

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

exemple.js

console.log("Cela peut provenir d'un fichier ou d'un CMS !");

Code importé

Utilisez le suffixe d’import ?raw de Vite pour importer n’importe quel fichier de code sous forme de chaîne de caractères. Vous pouvez ensuite passer cette chaîne importée au composant <Code> pour l’inclure dans votre page.

src/content/docs/exemple.mdx

import { Code } from '@astrojs/starlight/components';
import importedCode from '/src/env.d.ts?raw';

<Code code={importedCode} lang="ts" title="src/env.d.ts" />

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

src/env.d.ts

/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />