Manuelle Einrichtung

Der schnellste Weg, eine neue Starlight-Site zu erstellen, ist die Verwendung von create astro, wie auf der Seite Erste Schritte beschrieben. Wie du Starlight zu einem bestehenden Astro-Projekt hinzufügst, wird in dieser Anleitung erklärt.

Starlight einrichten

Um dieser Anleitung folgen zu können, benötigst du ein bestehendes Astro-Projekt.

Hinzufügen der Starlight-Integration

Starlight ist eine Astro-Integration. Füge sie zu deiner Website hinzu, indem du den Befehl astro add im Wurzelverzeichnis deines Projekts ausführst:

npm

npx astro add starlight

pnpm

pnpm astro add starlight

Yarn

yarn astro add starlight

Dies installiert die erforderlichen Abhängigkeiten und fügt Starlight zum Array integrations in deiner Astro-Konfigurationsdatei hinzu.

Konfiguriere die Integration

Die Starlight-Integration wird in der Datei astro.config.mjs konfiguriert.

Füge zunächst einen Titel mit der Eigenschaft title hinzu:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Meine Dokumentation',
    }),
  ],
});

Alle verfügbaren Optionen findest du in der Starlight-Konfigurationsreferenz.

Konfigurieren von Inhaltssammlungen

Starlight baut auf Astros Inhaltssammlungen auf, die in der Datei src/content/config.ts konfiguriert werden.

Erstelle oder aktualisiere die Inhaltskonfigurationsdatei und füge eine docs-Sammlung hinzu, die Starlight’s docsSchema verwendet:

src/content/config.ts

import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
};

Inhalte hinzufügen

Starlight ist jetzt konfiguriert und du kannst Inhalte hinzuzufügen.

Erstelle ein Verzeichnis src/content/docs/ und füge zunächst eine index.md-Datei hinzu. Dies wird die Startseite deiner neuen Website sein:

src/content/docs/index.md

---
title: Meine Dokumentation
description: Erfahre mehr über mein Projekt auf dieser mit Starlight erstellten Dokumentseite.
---

Willkommen bei meinem Projekt!

Starlight verwendet dateibasiertes Routing, was bedeutet, dass jede Markdown-, MDX- oder Markdoc-Datei in src/content/docs/ zu einer Seite auf deiner Website wird. Frontmatter-Metadaten (die Felder title und description im obigen Beispiel) können ändern, wie jede Seite angezeigt wird. Alle verfügbaren Optionen findest du in der Frontmatter-Referenz.

Tipps für bestehende Websites

Wenn du ein bestehendes Astro-Projekt hast, kannst du mit Starlight schnell eine Dokumentation zu deiner Website hinzufügen.

Starlight mit einem anderen Pfad verwenden

Um alle Starlight-Seiten mit einem anderen Pfad aufrufen zu können, lege den gesamten Inhalt in einem Unterverzeichnis von src/content/docs/ ab.

Wenn zum Beispiel die URL alle Starlight-Seiten mit /guides/ beginnen sollen, füge deine Inhalte in das Verzeichnis src/content/docs/guides/ ein:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • guide.md
        • index.md
  • Directorypages/

    • …
• astro.config.mjs

Für die Zukunft planen wir, diesen Anwendungsfall besser zu unterstützen, um die Notwendigkeit eines zusätzlichen verschachtelten Verzeichnisses in src/content/docs/ zu vermeiden.

Starlight mit SSR verwenden

Um SSR zu aktivieren, folge der Anleitung „Serverseitiges Rendern (SSR)“ in der Astro-Dokumentation, um einen Server-Adapter zu deinem Starlight-Projekt hinzuzufügen.

Die von Starlight erzeugten Dokumentationsseiten werden standardmäßig vorgerendert, unabhängig vom Ausgabemodus deines Projekts. Wenn du nicht möchtest, dass deine Starlight-Seiten vorgerendert werden, setze die Konfigurationsoption prerender auf false.