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 Starlights docsLoader und docsSchema verwendet:

src/content.config.ts

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

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

Starlight unterstützt auch die Option legacy.collections, bei dem Sammlungen mit der Legacy-Implementierung von Inhaltssammlungen behandelt werden. Dies ist nützlich, wenn du ein bestehendes Astro-Projekt hast und zum jetzigen Zeitpunkt keine Änderungen an den Sammlungen vornehmen kannst, um einen Loader zu verwenden.

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.