Zum Inhalt springen
Starlight

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:

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


export default defineConfig({
  integrations: [
    starlight({
      title: 'My delightful docs site',
    }),
  ],
});

Du kannst die folgenden Optionen an die starlight Integration übergeben.

title (erforderlich)

Typ: string | Record<string, string>

Lege den Titel für deine Website fest. Wird in den Metadaten und im Titel der Browser-Tabs verwendet.

Der Wert kann eine Zeichenkette sein, oder für mehrsprachige Websites ein Objekt mit Werten für jedes Gebietsschema. Wenn die Objektform verwendet wird, müssen die Schlüssel BCP-47-Tags sein (z. B. en, ar oder zh-CN):

starlight({
  title: {
    en: 'My delightful docs site',
    de: 'Meine bezaubernde Dokumentationsseite',
  },
});

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.

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.

starlight({
  logo: {
    src: './src/assets/my-logo.svg',
  },
});

LogoConfig

type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
  | { src: string }
  | { light: string; dark: string }
);

tableOfContents

Typ: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }
Standard: { 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.

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:

starlight({
  editLink: {
    baseUrl: 'https://github.com/withastro/starlight/edit/main/',
  },
});

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.

Typ: SidebarItem[]

Konfiguriere die Navigationselemente der Seitenleiste deiner Website.

Eine Seitenleiste ist eine Array von Links und Linkgruppen. Mit Ausnahme von Einträgen, die slug verwenden, muss jeder Eintrag ein label und eine der folgenden Eigenschaften haben:

  • link - ein einzelner Link zu einer bestimmten URL, z.B. '/home' oder 'https://example.com'.

  • slug - ein Verweis auf eine interne Seite, z.B. 'guides/getting-started'.

  • 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.

Interne Links können auch als Zeichenkette anstelle eines Objekts mit der Eigenschaft slug angegeben werden.

starlight({
  sidebar: [
    // Ein einzelner Link mit der Bezeichnung "Startseite".
    { label: 'Startseite', link: '/' },
    // Eine Gruppe mit der Bezeichnung „Hier beginnen“, die vier Links enthält.
    {
      label: 'Hier anfangen',
      items: [
        // Verwendung von `slug` für interne Links.
        { slug: 'intro' },
        { slug: 'installation' },
        // Oder du verwendst die Abkürzung für interne Links.
        'tutorial',
        'next-steps',
      ],
    },
    // Eine Gruppe, die auf alle Seiten im Referenzverzeichnis verweist.
    {
      label: 'Referenzen',
      autogenerate: { directory: 'referenz' },
    },
  ],
});

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.

sidebar: [
  // Eine zusammengefasste Gruppe von Links
  {
    label: 'Zusammengeklappte Links',
    collapsed: true,
    items: ['intro', 'next-steps'],
  },
  // Eine aufgeklappte Gruppe, die automatisch generierte Untergruppen enthält, welche standardmäßig eingeklappt sind.
  {
    label: 'Referenzen',
    autogenerate: {
      directory: 'reference',
      collapsed: true,
    },
  },
],

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:

sidebar: [
  // Ein Beispiel für eine Seitenleiste mit ins Französische übersetzten Beschriftungen
  {
    label: 'Hier anfangen',
    translations: { fr: 'Commencez ici' },
    items: [
      {
        label: 'Erste Schritte',
        translations: { fr: 'Bien démarrer' },
        link: '/getting-started',
      },
      {
        label: 'Projektstruktur',
        translations: { fr: 'Structure du projet' },
        link: '/structure',
      },
    ],
  },
],

SidebarItem

type SidebarItem =
  | string
  | ({
      translations?: Record<string, string>;
      badge?: string | BadgeConfig;
    } & (
      | {
          // Link
          link: string;
          label: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // Interner Link
          slug: string;
          label?: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // Gruppe von Links
          label: string;
          items: SidebarItem[];
          collapsed?: boolean;
        }
      | {
          // Automatisch generierte Linkgruppe
          label: string;
          autogenerate: { directory: string; collapsed?: boolean };
          collapsed?: boolean;
        }
    ));

BadgeConfig

interface BadgeConfig {
  text: string;
  variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
  class?: string;
}

locales

Typ: { [dir: string]: LocaleConfig }

Konfiguriere die Internationalisierung (i18n) für deine 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.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      // Englisch als Standardsprache festlegen.
      defaultLocale: 'en',
      locales: {
        // Englische Seiten in `src/content/docs/en/`
        en: {
          label: 'English',
        },
        // Chinesische Seiten in `src/content/docs/zh-cn/`
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // Arabische Seiten in `src/content/docs/ar/`
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

LocaleConfig

interface LocaleConfig {
  label: string;
  lang?: string;
  dir?: 'ltr' | 'rtl';
}

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 deine 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:

starlight({
  locales: {
    root: {
      label: 'Englisch',
      lang: 'en',
    },
    fr: {
      label: 'Français',
    },
  },
});

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 standard Locale wird verwendet, um Ersatzinhalte bereitzustellen, wenn Übersetzungen fehlen.

social

Typ: Partial<Record<'azureDevOps' | 'backstage' | 'bitbucket' | 'blueSky' | 'codeberg' | 'codePen' | 'discord' | 'discourse' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'hackerOne' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'nostr' | 'openCollective' | 'patreon' | 'pinterest' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'tiktok' | 'twitch' | 'twitter' | 'x.com' | 'youtube' | 'zulip', 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.

starlight({
  social: {
    codeberg: 'https://codeberg.org/knut/examples',
    discord: 'https://astro.build/chat',
    github: 'https://github.com/withastro/starlight',
    gitlab: 'https://gitlab.com/delucis',
    linkedin: 'https://www.linkedin.com/company/astroinc',
    mastodon: 'https://m.webtoo.ls/@astro',
    threads: 'https://www.threads.net/@nmoodev',
    twitch: 'https://www.twitch.tv/bholmesdev',
    twitter: 'https://twitter.com/astrodotbuild',
    'x.com': 'https://x.com/astrodotbuild',
    youtube: 'https://youtube.com/@astrodotbuild',
  },
});

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'.

starlight({
  customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});

expressiveCode

Typ: StarlightExpressiveCodeOptions | boolean
Standard: true

Starlight verwendet Expressive Code, um Codeblöcke zu rendern und Unterstützung für das Hervorheben von Teilen von Codebeispielen, das Hinzufügen von Dateinamen zu Codeblöcken und mehr hinzuzufügen. Im Handbuch „Codeblöcke“ erfährst du, wie du die Expressive Code-Syntax in deinen Markdown- und MDX-Inhalten verwendest.

Du kannst alle standardmäßigen Expressive Code-Konfigurationsoptionen sowie einige Starlight-spezifische Eigenschaften verwenden, indem du sie in der Option expressiveCode von Starlight festlegst. Lege beispielsweise die Option styleOverrides von Expressive Code fest, um das Standard-CSS zu überschreiben. Dadurch sind Anpassungen möglich, beispielsweise das Hinzufügen abgerundeter Ecken zu deinen Codeblöcken:

starlight({
  expressiveCode: {
    styleOverrides: { borderRadius: '0.5rem' },
  },
});

Wenn du Expressive Code deaktivieren möchtest, setze in deiner Starlight-Konfiguration expressiveCode: false:

starlight({
  expressiveCode: false,
});

Zusätzlich zu den standardmäßigen Expressive Code-Optionen kannst du in deiner expressiveCode-Konfiguration auch die folgenden Starlight-spezifischen Eigenschaften festlegen, um das Designverhalten für deine Codeblöcke weiter anzupassen:

themes

Typ: Array<string | ThemeObject | ExpressiveCodeTheme>
Standard: ['starlight-dark', 'starlight-light']

Lege die Designs fest, die zum Stylen von Codeblöcken verwendet werden. Weitere Informationen zu den unterstützten Designformaten findest du in der Expressive Code-Dokumentation zu Designs.

Starlight verwendet standardmäßig die dunkle und helle Variante von Sarah Drasners Night Owl-Thema.

Wenn du mindestens ein dunkles und ein helles Design angibst, wird Starlight das aktive Codeblock-Design automatisch mit dem aktuellen Site-Design synchron halten. Konfiguriere dieses Verhalten mit der Option useStarlightDarkModeSwitch.

useStarlightDarkModeSwitch

Typ: boolean
Standard: true

Falls true, wechseln Codeblöcke automatisch zwischen hellen und dunklen Designs, wenn sich das Site-Design ändert. Falls false, müssen Sie manuell CSS hinzufügen, um das Wechseln zwischen mehreren Designs zu handhaben.

useStarlightUiThemeColors

Typ: boolean
Standard: true wenn themes nicht gesetzt ist, andernfalls false

Falls true, werden Starlights CSS-Variablen für die Farben von Codeblock-UI-Elementen (Hintergründe, Schaltflächen, Schatten usw.) verwendet, die dem Site-Farbdesign entsprechen. Falls false, werden für diese Elemente die vom aktiven Syntaxhervorhebungsdesign bereitgestellten Farben verwendet.

pagefind

Typ: boolean
Standard: true

Lege fest, ob Starlight’s Standard-Site-Search-Anbieter Pagefind aktiviert ist.

Setze diese Option auf false, um die Indizierung deiner Website mit Pagefind zu deaktivieren. Dadurch wird auch die Standard-Suchoberfläche ausgeblendet, falls sie verwendet wird.

Pagefind kann nicht aktiviert werden, wenn die Option prerender auf false gesetzt ist.

prerender

Typ: boolean
Standard: true

Lege fest, ob Starlight-Seiten vorgerendert zu statischem HTML oder bei Bedarf von einem SSR-Adapter gerendert werden sollen.

Starlight-Seiten werden standardmäßig vorgerendert. Wenn du einen SSR-Adapter verwendest und Starlight-Seiten bei Bedarf rendern möchtest, setze prerender: false.

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.

starlight({
  head: [
    // Beispiel: Fathom Analytics Skript-Tag hinzufügen.
    {
      tag: 'script',
      attrs: {
        src: 'https://cdn.usefathom.com/script.js',
        'data-site': 'MY-FATHOM-ID',
        defer: true,
      },
    },
  ],
});

Einträge in head werden direkt in HTML-Elemente umgewandelt und durchlaufen nicht Astros script oder style Verarbeitung. Wenn du lokale Elemente wie Skripte, Stile oder Bilder importieren musst, überschreibe die Komponente Head.

HeadConfig

interface HeadConfig {
  tag: string;
  attrs?: Record<string, string | boolean | undefined>;
  content?: string;
}

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 deines 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.

starlight({
  favicon: '/images/favicon.svg',
}),

Wenn du zusätzliche Varianten oder Fallback-Favicons festlegen musst, kannst du diese mit der Option head Tags hinzufügen:

starlight({
  favicon: '/images/favicon.svg',
  head: [
    // ICO-Favicon als Fallback für Safari hinzufügen
    {
      tag: 'link',
      attrs: {
        rel: 'icon',
        href: '/images/favicon.ico',
        sizes: '32x32',
      },
    },
  ],
});

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“.

disable404Route

Typ: Boolean
Standard: false

Deaktiviert die Einspeisung von Starlights Standard 404 Seite. Um eine eigene src/pages/404.astro-Route in deinem Projekt zu verwenden, setze diese Option auf true.

components

Typ: Record<string, string>

Gib die Pfade zu den Komponenten an, um die Standardimplementierungen von Starlight zu ersetzen.

starlight({
  components: {
    SocialLinks: './src/components/MySocialLinks.astro',
  },
});

Siehe die Referenz der Ersetzung von Komponenten für Details zu allen Komponenten, die du überschreiben kannst.

plugins

Typ: StarlightPlugin[]

Erweitere Starlight mit eigenen Plugins. Plugins nehmen Änderungen an deinem Projekt vor, um die Funktionen von Starlight zu verändern oder zu erweitern.

Besuche das Plugins Schaufenster um eine Liste der verfügbaren Plugins zu sehen.

starlight({
  plugins: [starlightPlugin()],
});

Siehe die Referenz für Plugins für Details zur Erstellung eigener Plugins.

credits

Aktiviere die Anzeige eines „Erstellt mit Starlight“-Links in der Fußzeile deiner Website.

starlight({
  credits: true,
});