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 wird mit der folgenden Datenstruktur:

Ordnersrc/
- Ordnercontent/
  - Ordnerdocs/
    Ordnerconstellations/
    andromeda.md
    orion.md
    Ordnerstars/
    betelgeuse.md

Die folgende Seitenleiste automatisch generiert:

constellations
- Andromeda
- Orion
stars
- Beteigeuze

Erfahre mehr über autogenerierte Seitenleisten im Abschnitt autogenerierte Links.

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.

Interne Links

Füge einen Link zu einer Seite in src/content/docs/ mit Hilfe eines Objekts mit der Eigenschaft slug hinzu. Der Titel der verlinkten Seite wird standardmäßig als Bezeichnung verwendet.

Zum Beispiel wird mit der folgenden Konfiguration:

starlight({
  sidebar: [
    { slug: 'constellations/andromeda' },
    { slug: 'constellations/orion' },
  ],
});

Und der folgende Dateistruktur:

Ordnersrc/
- Ordnercontent/
  - Ordnerdocs/
    Ordnerconstellations/
    andromeda.md
    orion.md

Die folgende Seitenleiste erstellt:

Andromeda
Orion

Um die Werte zu überschreiben, die aus dem Frontmatter einer verlinkten Seite abgeleitet werden, kannst du die Eigenschaften label, translations und attrs hinzufügen.

Unter „Anpassen von automatisch generierten Links“ findest du weitere Informationen über die Steuerung des Erscheinungsbildes der Seitenleiste über das Frontmatter der Seite.

Kürzel für interne Links

Interne Links können auch angegeben werden, indem nur ein String für den Slug der Seite als Kurzform angegeben wird.

Die folgende Konfiguration entspricht zum Beispiel der obigen Konfiguration, die slug verwendet:

starlight({
  sidebar: ['constellations/andromeda', 'constellations/orion'],
});

Andere Links

Füge einen Link zu einer externen oder Nicht-Dokumentations-Seite hinzu, indem du ein Objekt mit den Eigenschaften label und link verwendest.

starlight({
  sidebar: [
    // Ein Link zu einer Nicht-Dokumentations-Seite auf dieser Website.
    { label: 'Meteor-Laden', link: '/laden/' },
    // Ein externer Link zur NASA-Website.
    { label: 'NASA', link: 'https://www.nasa.gov/' },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Meteor-Laden
NASA

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.

starlight({
  sidebar: [
    // Eine Gruppe von Links mit der Bezeichnung 'Konstellationen'.
    {
      label: 'Konstellationen',
      items: [
        'constellations/carina',
        'constellations/centaurus',
        // Eine verschachtelte Gruppe von Links für saisonale Konstellationen.
        {
          label: 'Saisonale',
          items: [
            'constellations/andromeda',
            'constellations/orion',
            'constellations/ursa-minor',
          ],
        },
      ],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Konstellationen
- Kiel des Schiffes
- Zentaur
- Saisonale

Automatisch generierte Links

Starlight kann automatisch Links 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.

Standardmäßig werden die Seiten in alphabetischer Reihenfolge nach der Datei id sortiert.

Füge automatisch generierte Links hinzu, indem du ein Objekt mit der Eigenschaften autogenerate verwendest. In der Konfiguration von autogenerate muss das directory angegeben werden, das für die Einträge in der Seitenleiste verwendet werden soll. Zum Beispiel wird mit der folgenden Konfiguration:

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      // Automatisches Erzeugen von Links für das Verzeichnis 'constellations'.
      items: [{ autogenerate: { directory: 'constellations' } }],
    },
  ],
});

Und der folgende Dateistruktur:

Ordnersrc/
- Ordnercontent/
  - Ordnerdocs/
    Ordnerconstellations/
    carina.md
    centaurus.md
    Ordnerseasonal/
    andromeda.md

Die folgende Seitenleiste erzeugt:

Konstellationen
- Kiel des Schiffes
- Zentaur
- seasonal
  - Andromeda

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 eine benutzerdefinierte Bezeichnung festlegen, benutzerdefinierte Attribute verwenden, ein Abzeichen zu einem Link hinzufügen, einen Link aus der Seitenleiste verstecken oder eine eigene Reihenfolge definieren.

---
title: Meine Seite
sidebar:
  # Setzt eine eigene Beschriftung für den Link
  label: Benutzerdefinierte Seitenleistenbeschriftung
  # Legen du eine benutzerdefinierte Reihenfolge für den Link fest (niedrigere Zahlen werden weiter oben angezeigt)
  order: 2
  # Fügen du dem Link ein Abzeichen hinzu
  badge:
    text: Neu
    variant: tip
---

Eine Gruppe mit autogenerierten Links, die eine Seite mit dem obigen Frontmatter enthält, erzeugt die folgende Seitenleiste:

Anleitungen

Abzeichen

Links und Gruppen können auch eine badge-Eigenschaft enthalten, um ein Abzeichen neben dem jeweiligen Text anzuzeigen.

starlight({
  sidebar: [
    {
      label: 'Sterne',
      items: [
        //Ein Link mit einem "Überriese"-Abzeichen.
        {
          slug: 'stars/persei',
          badge: 'Überriese',
        },
      ],
    },
    // Eine Gruppe mit dem "Veraltet"-Abzeichen.
    {
      label: 'Monde',
      badge: 'Veraltet',
      items: [{ autogenerate: { directory: 'moons' } }],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Sterne
- Persei Überriese
Monde Veraltet

Abzeichenvarianten

Passe das Design des Abzeichens mit einem Objekt mit den Eigenschaften text, variant und class an.

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.

Optional kannst du einen benutzerdefinierten Abzeichenstil erstellen, indem du die Eigenschaft class auf einen CSS-Klassennamen setzt.

starlight({
  sidebar: [
    {
      label: 'Sterne',
      items: [
        // Ein Link mit einem gelben „Platzhalter“-Abzeichen.
        {
          slug: 'stars/sirius',
          badge: { text: 'Platzhalter', variant: 'caution' },
        },
      ],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Sterne
- Sirius Platzhalter

Erfahre mehr über Verwendung und Anpassung von Badges.

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:

starlight({
  sidebar: [
    {
      label: 'Ressourcen',
      items: [
        // Ein externer Link zur NASA-Website, der in einem neuen Tab geöffnet wird.
        {
          label: 'NASA',
          link: 'https://www.nasa.gov/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Ressourcen
- NASA

Benutzerdefinierte HTML-Attribute für automatisch generierte Links

Du kannst die HTML-Attribute aller automatisch generierten Links anpassen, indem du die Eigenschaft attrs in der Konfiguration autogenerate festlegst. Einzelne Seiten können eigene Attribute über das sidebar.attrs-Frontmatter-Feld festlegen, welches mit der autogenerate.attrs-Konfiguration zusammengeführt wird.

Zum Beispiel wird mit der folgenden Konfiguration:

starlight({
  sidebar: [
    {
      autogenerate: {
        // Erstelle automatisch Links für das Verzeichnis 'constellations'.
        directory: 'constellations',
        // Alle automatisch generierten Link-Bezeichnungen kursiv darstellen.
        attrs: { style: 'font-style: italic' },
      },
    },
  ],
});

Und der folgenden Dateistruktur:

Ordnersrc/
- Ordnercontent/
  - Ordnerdocs/
    Ordnerconstellations/
    carina.md
    centaurus.md
    Ordnerseasonal/
    andromeda.md

Die folgende Seitenleiste mit allen automatisch generierten Links in Kursivschrift erstellt:

Kiel des Schiffes
Zentaur
seasonal
- Andromeda

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.

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          label: 'Andromeda',
          translations: {
            'pt-BR': 'Andrômeda',
          },
          slug: 'constellations/andromeda',
        },
        {
          label: 'Skorpion',
          translations: {
            'pt-BR': 'Escorpião',
          },
          slug: 'constellations/scorpius',
        },
      ],
    },
  ],
});

Wenn du die Dokumentation in brasilianischem Portugiesisch durchsuchst, wird die folgende Seitenleiste angezeigt:

Constelação
- Andrômeda
- Escorpião

Internationalisierung mit internen Links

Interne Links verwenden standardmäßig automatisch übersetzte Seitentitel aus dem Frontmatter des Inhalts:

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        { slug: 'constellations/andromeda' },
        { slug: 'constellations/scorpius' },
      ],
    },
  ],
});

Wenn du die Dokumentation auf brasilianisches Portugiesisch durchsuchst, wird die folgende Seitenleiste angezeigt:

Constelações
- Andrômeda
- Escorpião

Bei mehrsprachigen Websites enthält der Wert von slug nicht den sprachlichen Teil der URL. Wenn du zum Beispiel Seiten unter en/intro und pt-br/intro hast, ist der Slug intro, wenn du die Seitenleiste konfigurierst.

Internationalisierung mit Badges

Für Abzeichen kann die Eigenschaft text ein String sein oder für mehrsprachige Seiten ein Objekt mit Werten für jedes unterschiedliche Gebietsschema. Wenn du die Objektform verwendest, müssen die Schlüssel BCP-47 Tags sein (z. B. en, ar oder zh-CN):

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      translations: {
        'pt-BR': 'Constelações',
      },
      items: [
        {
          slug: 'constellations/andromeda',
          badge: {
            text: {
              de: 'Neu',
              'pt-BR': 'Novo',
            },
          },
        },
      ],
    },
  ],
});

Wenn du die Dokumentation auf brasilianisches Portugiesisch durchsuchst, wird die folgende Seitenleiste angezeigt:

Constelações
- Andrômeda Novo

Zusammenklappen von Gruppen

Gruppen von Links können standardmäßig eingeklappt werden, indem man die Eigenschaft collapsed auf true setzt.

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      // Schließe die Gruppe standardmäßig.
      collapsed: true,
      items: ['constellations/andromeda', 'constellations/orion'],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Konstellationen
- Andromeda
- Orion

Automatisch generierte Untergruppen können standardmäßig ausgeblendet werden, indem du die Eigenschaft autogenerate.collapsed auf true setzt.

starlight({
  sidebar: [
    {
      label: 'Konstellationen',
      items: [
        {
          autogenerate: {
            directory: 'constellations',
            // Standardmäßig werden automatisch
            // generierte Untergruppen ausgeblendet.
            collapsed: true,
          },
        },
      ],
    },
  ],
});

Die obige Konfiguration erzeugt die folgende Seitenleiste:

Konstellationen
- Kiel des Schiffes
- Zentaur
- seasonal
  - Andromeda