Konfigurationsreferenz
Konfiguriere die starlight
Integration
Starlight ist eine Integration, die auf dem Astro Web-Framework aufbaut. Du kannst dein Projekt innerhalb der Astro-Konfigurationsdatei astro.config.mjs
anpassen:
Du kannst die folgenden Optionen an die starlight
Integration übergeben.
title
(erforderlich)
Typ: string
Lege den Titel für deine Website fest. Wird in den Metadaten und im Titel der Browser-Tabs verwendet.
description
Typ: string
Lege die Beschreibung für deine Website fest. Wird in den Metadaten verwendet, die mit Suchmaschinen im <meta name="description">
-Tag geteilt werden, für Seiten wo description
nicht im Frontmatter festgelegt ist.
logo
Typ: LogoConfig
Legt ein Logobild fest, das in der Navigationsleiste neben oder anstelle des Seitentitels angezeigt wird. Du kannst entweder eine einzige src
-Eigenschaft oder separate Bildquellen für light
und dark
festlegen.
LogoConfig
tableOfContents
Typ: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
Voreinstellung: { minHeadingLevel: 2; maxHeadingLevel: 3; }
Konfiguriere das Inhaltsverzeichnis, das rechts auf jeder Seite angezeigt wird. Standardmäßig werden <h2>
und <h3>
Überschriften in dieses Inhaltsverzeichnis aufgenommen.
editLink
Typ: { baseUrl: string }
Aktiviere “Diese Seite bearbeiten”-Links, indem du die Basis-URL für diese festlegst. Der endgültige Link wird editLink.baseUrl
+ der aktuelle Seitenpfad sein. Zum Beispiel, um das Bearbeiten von Seiten im withastro/starlight
Repo auf GitHub zu ermöglichen:
Mit dieser Konfiguration würde eine /einfuehrung
einen Bearbeitungslink haben, der auf https://github.com/withastro/starlight/edit/main/src/content/docs/einfuehrung.md
zeigt.
sidebar
Typ: SidebarItem[]
Konfiguriere die Navigationselemente der Seitenleiste deiner Website.
Eine Seitenleiste ist eine Array von Links und Linkgruppen.
Jedes Element muss ein label
und eine der folgenden Eigenschaften haben:
link
- ein einzelner Link zu einer bestimmten URL, z.B.'/home'
oder'https://example.com'
.items
- ein Array, das weitere Links und Untergruppen enthält.autogenerate
- ein Objekt, das ein Verzeichnis deiner Dokumentation angibt, aus dem automatisch eine Gruppe von Links erzeugt werden soll.
Sortierung
Die automatisch erstellten Seitenleisten-Gruppen werden alphabetisch nach dem Dateinamen sortiert.
Zum Beispiel würde eine Seite, die aus der Datei astro.md
erzeugt wurde, über der Seite für starlight.md
erscheinen.
Zusammenklappbare Gruppen
Gruppen von Links sind standardmäßig aufgeklappt. Du kannst dieses Verhalten ändern, indem du die Eigenschaft collapsed
einer Gruppe auf true
setzt.
Autogenerierte Untergruppen respektieren standardmäßig die Eigenschaft collapsed
ihrer übergeordneten Gruppe. Dies kannst du mit der Eigenschaft autogenerate.collapsed
außer Kraft setzen.
Labels übersetzen
Wenn deine Website mehrsprachig ist, wird das label
jedes Elements als in der Standard-Sprache verfasst betrachtet. Du kannst die Eigenschaft translations
verwenden, um die Labels für andere unterstützte Sprachen festzulegen:
SidebarItem
BadgeConfig
locales
Typ: { [dir: string]: LocaleConfig }
Konfiguriere die Internationalisierung (i18n) für Ihre Website, indem du festlegst, welche Locales
unterstützt werden.
Jeder Eintrag sollte das Verzeichnis, in dem die Dateien der jeweiligen Sprache gespeichert sind, als Schlüssel verwenden.
LocaleConfig
Du kannst die folgenden Optionen für jedes Locale-Schema festlegen:
label
(erforderlich)
Typ: string
Die Bezeichnung für diese Sprache, die den Benutzern angezeigt werden soll, z. B. im Sprachumschalter. Meistens wird dies der Name der Sprache sein, wie ihn ein Benutzer dieser Sprache erwarten würde, z.B. "English"
, "العربية"
, oder "简体中文"
.
lang
Typ: string
Das BCP-47-Tag für diese Sprache, z. B. "en"
, "ar"
oder "zh-CN"
. Wenn nicht gesetzt, wird standardmäßig der Verzeichnisname der Sprache verwendet. Sprach-Tags mit regionalen Unter-Tags (z.B. "pt-BR"
oder "en-US"
) verwenden integrierte UI-Übersetzungen für ihre Basissprache, wenn keine regionalspezifischen Übersetzungen gefunden werden.
dir
Typ: 'ltr' | 'rtl'
Die Schreibrichtung dieser Sprache; "ltr"
für links-nach-rechts (die Voreinstellung) oder "rtl"
für rechts-nach-links.
Root-Locale
Du kannst die Standardsprache ohne ein /lang/
-Verzeichnis anbieten, indem du ein root
-Locale setzst:
So kannst du zum Beispiel /getting-started/
als englische Seite und /fr/getting-started/
als entsprechende französische Seite verwenden.
defaultLocale
Typ: string
Legt die Sprache fest, die als Standard für diese Website gilt.
Der Wert sollte mit einem der Schlüssel deines locales
-Objekts übereinstimmen.
(Wenn deine Standardsprache deiner Root-Locale ist, kannst du dies überspringen).
Das defaultLocale
wird verwendet, um Ersatzinhalte bereitzustellen, wenn Übersetzungen fehlen.
social
Typ: Partial<Record<'bitbucket' | 'codeberg' | 'codePen' | 'discord' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'openCollective' | 'patreon' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'twitch' | 'twitter' | 'x.com' | 'youtube', string>>
Optionale Angaben zu den Social-Media-Konten für diese Site. Wenn du eines dieser Konten hinzufügst, werden sie als Icon-Links in der Kopfzeile der Website angezeigt.
customCss
Typ: string[]
Stellen CSS-Dateien zur Verfügung, um das Aussehen deines Starlight-Projekts anzupassen.
Unterstützt lokale CSS-Dateien relativ zum Stammverzeichnis deines Projekts, z.B. './src/custom.css'
, und CSS, die du als npm-Modul installiert hast, z.B. '@fontsource/roboto'
.
head
Typ: HeadConfig[]
Füge zusätzliche Tags in den <head>
deines Starlight-Projekts ein.
Kann nützlich sein, um Analytics und andere Skripte und Ressourcen von Drittanbietern hinzuzufügen.
HeadConfig
lastUpdated
Typ: boolean
Standard: false
Legt fest, ob in der Fußzeile angezeigt werden soll, wann die Seite zuletzt aktualisiert wurde.
Standardmäßig verwendet diese Funktion die Git-Historie Ihres Repositorys und kann auf einigen Bereitstellungsplattformen, die shallow clones durchführen, nicht genau sein. Eine Seite kann diese Einstellung oder das Git-basierte Datum mit dem lastUpdated
Frontmatter-Feld überschreiben.
pagination
Typ: boolean
Standard: true
Legt fest, ob die Fußzeile Links zur vorherigen und nächsten Seite enthalten soll.
Eine Seite kann diese Einstellung oder den Linktext und/oder die URL mit Hilfe der Frontmatter-Felder prev
und next
überschreiben.
favicon
Typ: string
Standard: '/favicon.svg'
Legt den Pfad des Standard-Favicons für deine Website fest. Dieses sollte sich im Verzeichnis public/
befinden und eine gültige Icon-Datei (.ico
, .gif
, .jpg
, .png
oder .svg
) sein.
Wenn du zusätzliche Varianten oder Fallback-Favicons festlegen musst, kannst du diese mit der Option head
Tags hinzufügen:
titleDelimiter
Typ: string
Standard: '|'
Legt das Trennzeichen zwischen Seitentitel und dem Titel der Website im <title>
-Tag der Website fest, welches in den Browser-Tabs angezeigt wird.
Standardmäßig hat jede Seite einen <title>
von Seiten Überschrift | Webseitenname
.
Zum Beispiel heißt diese Seite “Konfigurationsreferenz” und diese Website heißt “Starlight”, also ist der <titel>
für diese Seite “Konfigurationsreferenz | Starlight”.
components
Typ: Record<string, string>
Gib die Pfade zu den Komponenten an, um die Standardimplementierungen von Starlight zu ersetzen.
Siehe die Komponenten-Ersetzung Referenz für Details zu allen Komponenten, die du überschreiben kannst.