Verwendung von Komponenten

Mit Komponenten kannst du auf einfache Weise einen Teil der Benutzeroberfläche oder ein Styling konsistent wiederverwendem. Beispiele könnten eine Link-Karte oder eine YouTube-Einbettung sein. Starlight unterstützt die Verwendung von Komponenten in MDX- und Markdoc-Dateien und stellt dir einige gängige Komponenten zur Verfügung, die du verwenden kannst.

Erfahre mehr über die Erstellung von Komponenten in den Astro Docs.

Verwendung einer Komponente in MDX

Du kannst eine Komponente verwenden, indem du sie in deine MDX-Datei importierst und sie dann als JSX-Tag wiedergibst. Diese sehen wie HTML-Tags aus, beginnen aber mit einem Großbuchstaben, der dem Namen in der Import-Anweisung entspricht:

---
title: Willkommen bei meiner Dokumentation
---

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

<Icon name="open-book" />

<CustomCard>
  Komponenten können auch **verschachtelte Inhalte** enthalten.
</CustomCard>

Da Starlight von Astro unterstützt wird, kannst du in deinen MDX-Dateien Unterstützung für Komponenten hinzufügen, die mit einem beliebigen unterstützten UI-Framework (React, Preact, Svelte, Vue, Solid und Alpine) erstellt wurden. Weitere Informationen über Verwendung von Komponenten in MDX findest du in der Astro-Dokumentation.

Verwendung einer Komponente in Markdoc

Füge Unterstützung für das Verfassen von Inhalten in Markdoc hinzu, indem du unsere Markdoc-Einrichtungsanleitung befolgst.

Mit der Starlight Markdoc-Voreinstellung kannst du die in Starlight eingebauten Komponenten mit der Markdoc-Tag-Syntax {% %} verwenden. Im Gegensatz zu MDX müssen die Komponenten in Markdoc nicht importiert werden. Das folgende Beispiel stellt Starlights Kartenkomponente in einer Markdoc-Datei dar:

---
title: Willkommen bei meiner Dokumentation
---

{% card title="Stars" icon="star" %}
Sirius, Wega, Betelgeuse
{% /card %}

Weitere Informationen zur Verwendung von Komponenten in Markdoc-Dateien findst du in der Astro Markdoc Integrationsdokumentation.

Integrierte Komponenten

Starlight bietet eingebaute Komponenten für gängige Dokumentationsanwendungen. Diese Komponenten sind aus dem Paket @astrojs/starlight/components in MDX-Dateien und aus dem Starlight Markdoc preset in Markdoc-Dateien verfügbar.

In der Seitenleiste findst du eine Liste der verfügbaren Komponenten und deren Verwendung.

Kompatibilität mit den Stilen von Starlight

Starlight wendet Standardstile auf deinen Markdown-Inhalt an, z.B. fügt es einen Rand zwischen den Elementen hinzu. Wenn diese Stile mit dem Erscheinungsbild deiner Komponente in Konflikt stehen, setze die Klasse not-content für deine Komponente, um sie zu deaktivieren.

<div class="not-content">
  <p>Die Standard-Inhaltsgestaltung von Starlight wirkt sich nicht aus.</p>
</div>

Komponenteneigenschaften

Verwende den Typ ComponentProps aus astro/types, um auf die von einer Komponente akzeptierten Props zu verweisen, auch wenn sie nicht von der Komponente selbst exportiert werden. Dies kann hilfreich sein, wenn man eine existierende Komponente verpackt oder erweitert.

Das folgende Beispiel benutzt ComponentProps, um den Typ der Eigenschaften zu ermitteln, die von Starlights eingebauter Komponente Icon akzeptiert werden:

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

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