Seitenleisten-Navigation
Eine gut organisierte Seitenleiste ist der Schlüssel zu einer guten Dokumentation, da sie eine der Hauptwege ist, auf denen die Benutzer durch deine Website navigieren werden. Starlight bietet eine ganze Reihe von Optionen, um das Layout und den Inhalt der Seitenleiste anzupassen.
Standard-Seitenleiste
Standardmäßig erzeugt Starlight automatisch eine Seitenleiste, die auf der Dateistruktur deiner Dokumentation basiert und die Eigenschaft title
jeder Datei als Seitenleisteneintrag verwendet.
Zum Beispiel, wenn du die folgende Dateistruktur hast:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryguides/
- components.md
- i18n.md
Directoryreference/
- configuration.md
Wird die folgende Seitenleiste automatisch generiert:
Erfahre mehr über autogenerierte Seitenleisten im Abschnitt autogenerierte Gruppen.
Links und Linkgruppen hinzufügen
Um deiner Seitenleiste Links und Gruppen von Links (innerhalb einer einklappbaren Kopfzeile) zu konfigurieren, verwende die Eigenschaft starlight.sidebar
in astro.config.mjs
.
Durch die Kombination von Links und Gruppen kannst du eine Vielzahl von Seitenleistenlayouts erstellen.
Links
Füge einen Link zu einer internen oder externen Seite hinzu, indem du ein Objekt mit den Eigenschaften label
und link
verwendest.
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Gruppen
Du kannst deine Seitenleiste strukturieren, indem du zusammengehörige Links unter einer zusammenklappbaren Überschrift gruppierst. Gruppen können sowohl Links als auch andere Untergruppen enthalten.
Füge eine Gruppe mit einem Objekt mit den Eigenschaften label
und items
hinzu.
Das label
wird als Überschrift für die Gruppe verwendet.
Füge Links oder Untergruppen zu dem items
Array hinzu.
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Automatisch erzeugte Gruppen
Starlight kann automatisch eine Gruppe in deiner Seitenleiste erzeugen, die auf einem Verzeichnis deiner Dokumente basiert. Dies ist hilfreich, wenn du nicht jedes Element der Seitenleiste manuell in eine Gruppe eintragen willst. Die Seiten werden standardmäßig alphabetisch nach Dateinamen sortiert.
Füge eine automatisch generierte Gruppe hinzu, indem du ein Objekt mit den Eigenschaften Label
und Autogenerate
verwendest. In der Konfiguration von autogenerate
muss das Verzeichnis
angegeben werden, das für die Einträge in der Seitenleiste verwendet werden soll. Zum Beispiel, mit der folgenden Konfiguration:
Und die folgende Dateistruktur:
Directorysrc/
Directorycontent/
Directorydocs/
Directoryguides/
- components.md
- i18n.md
Directoryadvanced/
- project-structure.md
Wird die folgende Seitenleiste erzeugt:
Autogenerierte Links im Frontmatter anpassen
Verwende das sidebar
-Frontmatter-Feld in einzelnen Seiten, um automatisch generierte Links anzupassen.
Mit den Frontmatter-Optionen in der Seitenleiste kannst du einem Link eine eigenen Bezeichnung oder ein Abzeichen hinzufügen, einen Link aus der Seitenleiste verstecken, oder eine eigene Reihenfolge definieren.
Eine autogenerierte Gruppe, die eine Seite mit dem obigen Frontmatter enthält, erzeugt die folgende Seitenleiste:
Abzeichen
Links, Gruppen und automatisch generierte Gruppen können auch eine badge
-Eigenschaft enthalten, um ein Abzeichen neben dem jeweiligen Text anzuzeigen.
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Abzeichenvarianten
Passe das Design des Abzeichens an, indem du ein Objekt mit den Eigenschaften text
und variant
verwendest.
Der text
steht für den anzuzeigenden Inhalt (z.B. “Neu”).
Überschreibe das default
-Styling, das die Akzentfarbe deiner Website verwendet, indem du die Eigenschaft variant
auf einen der folgenden Werte setzt: note
, tip
, danger
, caution
oder success
.
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Benutzerdefinierte HTML-Attribute
Links können auch eine Eigenschaft attrs
enthalten, um dem Link-Element benutzerdefinierte HTML-Attribute hinzuzufügen.
Im folgenden Beispiel wird attrs
verwendet, um ein target="_blank"
-Attribut hinzuzufügen, so dass der Link in einem neuen Tab geöffnet wird, und um ein benutzerdefiniertes style
-Attribut anzuwenden, um die Linkbeschriftung kursiv zu machen:
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Internationalisierung
Verwende die Eigenschaft translations
für Link- und Gruppeneinträge, um die Link- oder Gruppenbeschriftung für jede unterstützte Sprache zu übersetzen, indem du ein BCP-47 Sprach-Tag, z.B. "en"
, "ar"
, oder "zh-CN"
, als Schlüssel und die übersetzte Beschriftung als Wert angibst.
Die Eigenschaft label
wird für das Standardgebietsschema und für Sprachen ohne Übersetzung verwendet.
Wenn du die Dokumentation in brasilianischem Portugiesisch durchsuchst, wird die folgende Seitenleiste angezeigt:
Zusammenklappen von Gruppen
Gruppen von Links können standardmäßig eingeklappt werden, indem man die Eigenschaft collapsed
auf true
setzt.
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Autogenerierte Gruppen respektieren den collapsed
Wert ihrer Elterngruppe:
Die obige Konfiguration erzeugt die folgende Seitenleiste:
Dieses Verhalten kann durch die Definition der Eigenschaft autogenerate.collapsed
außer Kraft gesetzt werden.
Die obige Konfiguration erzeugt die folgende Seitenleiste: