Utilisation des 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 liaison ou d’une intégration YouTube. Starlight prend en charge l’utilisation de composants dans les fichiers MDX et Markdoc et fournit des composants courants que vous pouvez utiliser.

Pour en savoir plus sur la création de composants, consultez la documentation d’Astro.

Utilisation d’un composant avec MDX

Vous pouvez utiliser un composant en l’important dans votre fichier MDX et ensuite l’afficher en tant que balise JSX. Ces balises ressemblent à des balises HTML, mais commencent par une lettre majuscule correspondant au nom utilisé dans votre instruction import :

---
title: Bienvenue dans ma documentation
---

import { Icon } from '@astrojs/starlight/components';
import CustomCard from '../../components/CustomCard.astro';

<Icon name="open-book" />

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

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

Utilisation d’un composant avec Markdoc

Ajoutez la prise en charge de la rédaction de contenu avec Markdoc en suivant notre guide de configuration Markdoc.

En utilisant la préconfiguration Markdoc de Starlight, vous pouvez utiliser les composants intégrés à Starlight avec la syntaxe de balises {% %} de Markdoc. À la différence du format MDX, les composants dans les fichiers Markdoc n’ont pas besoin d’être importés. L’exemple suivant affiche le composant de carte de Starlight dans un fichier Markdoc :

---
title: Bienvenue dans ma documentation
---

{% card title="Étoiles" icon="star" %}
Sirius, Véga, Bételgeuse
{% /card %}

Consultez la documentation de l’intégration Astro Markdoc pour plus d’informations sur l’utilisation des composants dans les fichiers Markdoc.

Composants intégrés

Starlight fournit des composants intégrés par défaut pour des cas d’utilisation courants à une documentation. Ces composants sont disponibles dans le paquet @astrojs/starlight/components dans les fichiers MDX et dans la préconfiguration Markdoc de Starlight dans les fichiers Markdoc.

Utilisez la barre latérale pour obtenir une liste des composants disponibles et savoir comment les utiliser.

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, utilisez la classe not-content sur votre composant pour les désactiver.

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

Props des composants

Utilisez le type ComponentProps depuis astro/types pour référencer les Props acceptées par un composant même si elles ne sont pas exportées par le composant lui-même. Cela peut être utile lorsqu’il s’agit d’entourer ou d’étendre un composant existant.

L’exemple suivant utilise ComponentProps pour obtenir le type des props acceptées par le composant Icon intégré à Starlight :

---
import type { ComponentProps } from 'astro/types';
import { Icon } from '@astrojs/starlight/icon';

type IconProps = ComponentProps<typeof Icon>;
---