NCA Social Media
Aktualisiert:
Autor:
Roland Golla
Grauer Comic Roboter folgt dem Leuchtturm Licht zum Schild Starlight

Was ist Astro Starlight?

Astro Starlight ist ein Open Source Theme für Doku Websites auf Basis von Astro. Du schreibst Inhalte in Markdown, MDX oder Markdoc und bekommst Navigation, Volltextsuche, Dark Mode, Mehrsprachigkeit und SEO direkt mit.
Das Projekt liegt bei withastro auf GitHub und steht unter MIT Lizenz. Technisch ist Starlight eine Astro Integration. Eine Starlight Seite bleibt also ein normales Astro Projekt, das du erweitern kannst.
Das macht es für Teams interessant, die ihre Doku neben dem Code im Git Repository halten. Texte laufen durch denselben Review wie der Code. Das fertige Ergebnis sind statische Dateien, die auf fast jedem Webserver laufen.
Inhalt
NCA KI Workshop für Developer

Agentic Coding im Team, nicht nur im Glossar

Ein Tag inhouse mit Benjamin Klein für Developer, Tester und Admins. Context Engineering, Harness, ADRs und zwei Hands on Blöcke mit KI Agenten in eurem Setup.

  1. 1
    Kostenloses Vorgespräch
    Stand, Rollen und Ziele klären
  2. 2
    Workshoptag bei euch
    Praxis am Vormittag, Hands on danach
  3. 3
    Praxistag optional
    Agenten im eigenen Projekt
Benjamin Klein
Benjamin Klein
Senior Consultant
Zum Workshop für Developer arrow_forward

Astro Starlight mit NCA bringt schnelle Hilfe vom Experten

Never Code Alone arbeitet täglich mit Astro. Wir kennen den Astro Static Site Build und die Astro Islands Architektur aus echten Projekten. Starlight selbst setzen wir nicht als festen Baustein ein. Wir ordnen es für Teams neutral gegen andere Doku Werkzeuge ein.
Dazu gehören ein sauberes Setup mit TypeScript im Strict Mode, Design mit Tailwind CSS, Hosting in Deutschland und Tests mit dem NCA TESTIFY Cypress Plugin. Mehr zu unserem Schwerpunkt findest du im Bereich Frontend Development.

Was Astro Starlight von Haus aus mitbringt

Eine gute Doku braucht immer dieselben Bausteine. Starlight liefert sie fertig, damit du dich um den Text kümmern kannst.
  • Dateibasiertes Routing: Jede Datei in src/content/docs/ wird zu einer Seite.
  • Volltextsuche: Pagefind läuft ohne Konfiguration und ohne externen Suchdienst.
  • Validiertes Frontmatter: Fehler in den Metadaten fallen früh auf.
  • Komponenten: Tabs, Cards, Steps, Asides, File Tree und Code Blöcke sind dabei.
  • Mehrsprachigkeit: Internationalisierung ist fest eingebaut.
  • Freie Wahl beim UI: Du kannst React, Vue, Svelte oder Solid einbinden.
Auch beim Gewicht liegt Starlight vorn. Laut eigener Doku lädt ein Erstbesuch weniger als 50 KB komprimierte Daten. UI Komponenten bringen dank Astro standardmäßig kein JavaScript in den Browser. Wie das funktioniert, zeigt unser Artikel zum Astro Static Site Generator.

So richtest du Astro Starlight in wenigen Minuten ein

Für ein neues Projekt reicht ein Befehl im Terminal. Danach startest du den lokalen Server und siehst deine Seite sofort im Browser.
Code: 
          
npm create astro@latest -- --template starlight
npm run dev
In ein bestehendes Astro Projekt holst du Starlight mit astro add. So bekommt deine Website eine Doku, ohne dass du dafür ein zweites Tool oder eine Subdomain brauchst.
Code: 
          
npx astro add starlight
Die Grundkonfiguration ist kurz. Ein Titel reicht für den Start.
Code: 
          
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Meine Doku',
    }),
  ],
});
In src/content.config.ts verbindest du die Inhalte mit dem Loader und dem Schema von Starlight. Das Schema prüft dein Frontmatter beim Build, ähnlich wie du es von Zod Schema Validation kennst.
Code: 
          
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() }),
};
Für Updates von Starlight und allen Astro Paketen gibt es npx @astrojs/upgrade. Den Befehl solltest du regelmäßig ausführen, denn die Doku von Starlight kündigt häufige Updates an.

Astro Starlight im Vergleich zu Docusaurus, VitePress und GitBook

Alle diese Werkzeuge bauen gute Doku. Am Ende entscheidet meist der Stack deines Teams. Die CO2 Werte stammen aus der Vergleichstabelle von Starlight mit Daten vom April 2026 und sind damit eine Herstellerangabe. Den Blick auf eine gehostete Plattform findest du in unserem Artikel zu GitBook.

Doku Werkzeuge im Überblick

Werkzeug Basis und CO2 pro Seitenaufruf Geeignet für
Astro Starlight Astro, 0,01 g Teams mit Astro oder ohne festes UI Framework, schlanke Seiten, Doku neben der Website
VitePress Vue und Vite, 0,04 g Teams im Vue Umfeld, Doku für Bibliotheken
Docusaurus React, 0,09 g React Teams, die Versionierung direkt im Framework wollen
Nextra Next.js, 0,10 g Teams, die schon mit Next.js arbeiten
GitBook Gehostete Plattform, 0,44 g Teams, die keinen eigenen Build betreiben wollen

Diese Grenzen solltest du bei Astro Starlight kennen

Starlight ist stark, aber nicht fertig. Die Version 1.0 steht noch aus, und die eigene Doku spricht von Beta Software. Plane also Zeit für Updates ein und halte die Abhängigkeiten aktuell.
  • Versionierung: Mehrere Doku Versionen sind nicht fest eingebaut. Das übernimmt das Community Plugin starlight-versions.
  • Plugins: Offiziell ist nur das DocSearch Plugin, fast alle anderen pflegt die Community. Prüfe vor dem Einsatz, wie aktiv ein Plugin gepflegt wird.
  • Redaktion: Einen Editor für Fachabteilungen gibt es nicht. Wer ohne Git arbeiten will, braucht ein zusätzliches Tool.
  • Barrierefreiheit: Das Theme liefert eine gute Basis. Eigene Inhalte und Komponenten musst du trotzdem selbst prüfen.
Beim letzten Punkt helfen Semantic HTML, saubere Keyboard Navigation und die Accessible Astro Components.

Astro Starlight macht Doku auch für KI Agenten lesbar

Doku hat heute zwei Leser, Menschen und Coding Agents. Markdown im Repository ist für beide ein guter Ausgangspunkt. Ein Agent wie OpenCode kann die Dateien direkt lesen und mit deinen AGENTS.md Regeln kombinieren.
Für die veröffentlichte Seite gibt es passende Community Plugins:
  • starlight-llms-txt ergänzt eine llms.txt für deine Doku.
  • starlight-md-txt stellt Seiten als rohes Markdown bereit.
  • starlight-to-skills macht aus Doku Seiten Agent Skills.
  • starlight-obsidian veröffentlicht einen Obsidian Vault.
  • starlight-openapi baut Doku Seiten aus OpenAPI Specs.
Was du für KI Suchen sonst noch beachten solltest, steht in unserem Beitrag zu LLMO. Einen ähnlichen Ansatz ohne Doku Theme zeigt Obsidian als CMS für Astro.

Astro Starlight kannst du selbst und DSGVO freundlich hosten

Starlight rendert Doku Seiten standardmäßig vor. Heraus kommt ein Ordner mit statischen Dateien. Den kannst du auf einem eigenen Server in Deutschland ausliefern, etwa mit Caddy oder über Coolify.
Auch die Suche bleibt bei dir, denn Pagefind arbeitet mit einem Index aus deinem Build. Wechselst du zu Algolia DocSearch, gehen die Suchanfragen an einen externen Dienst. Das solltest du dann datenschutzrechtlich prüfen. Ein offener Weg zum Selbsthosten ist das Community Plugin für Typesense.
Den Weg in die Produktion sichert eine CI/CD Pipeline ab. Darin können Build und Link Check bei jedem Merge Request laufen, zum Beispiel mit starlight-links-validator.

Astros offizielles Starterkit Starlight ist ein unglaubliches Werkzeug für die Erstellung einer Dokumentations-Website

Flavio Copes, Entwickler und Autor – deutsche Fassung auf starlight.astro.build

So ordnet NCA Astro Starlight in der Praxis ein

Wir helfen Teams bei der Frage, ob Starlight zu ihrer Doku passt. Wir schauen auf den vorhandenen Stack, auf die Menschen, die schreiben sollen, und auf den Aufwand im Betrieb. Wer schon Astro nutzt, findet einen besonders kurzen Weg. Warum Astro auch für den Einstieg gut passt, zeigt Astro Framework für Vibe Coding.
Bei der Umsetzung achten wir auf Qualität ab dem ersten Tag: Quality Gates, ein klares Deployment und Diagramme als Code, zum Beispiel mit PlantUML. Wie Agents dabei mitschreiben können, ohne die Kontrolle zu verlieren, zeigen unsere NCA Agentic AI Coding Guardrails und der NCA KI Workshop für Developer.
CYPRESS.IO Ambassador und IT Consultant für QA Engenieering und Qualität in PHP Projekten.
Frontend: Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile der Barrierefreiheit

Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.

E-Mail Kontakt

Häufige Fragen zu Astro Starlight

Hier findest du kurze Antworten zu Einsatz, Kosten, Plugins und Betrieb von Astro Starlight.
Was ist Astro Starlight 2026?

Astro Starlight ist ein Open Source Theme für Doku Websites auf Basis von Astro. Du schreibst in Markdown, MDX oder Markdoc und bekommst Navigation, Suche, Dark Mode und Mehrsprachigkeit direkt mit. Technisch ist es eine Astro Integration, deine Seite bleibt also ein normales Astro Projekt, das du weiter ausbauen kannst.

Ist Astro Starlight 2026 kostenlos?

Ja, Starlight selbst ist kostenlos und steht unter MIT Lizenz. Du darfst es auch kommerziell nutzen. Kosten entstehen nur für Hosting, Pflege und die Arbeit an den Inhalten. Weil am Ende statische Dateien herauskommen, reicht für viele Projekte ein einfacher Webserver ohne Datenbank und ohne eigene Laufzeit im Hintergrund.

Ist Astro Starlight 2026 bereit für Production?

Viele große Teams setzen Starlight ein, laut Projektseite etwa Microsoft, Netlify und Sentry. Die Version 1.0 steht aber noch aus, und die eigene Doku spricht von Beta Software. Für Production heißt das, Updates einplanen, Versionen fest pinnen und den Build mit Tests absichern. Dann bleibt das Risiko bei Änderungen gut überschaubar.

Was ist 2026 besser, Astro Starlight oder Docusaurus?

Das hängt vor allem vom Stack ab. Starlight passt zu Astro Teams und zu Projekten, die schlanke Seiten ohne viel JavaScript wollen. Docusaurus passt zu React Teams und bringt Versionierung direkt im Framework mit. Bei Starlight löst du Versionierung über ein Community Plugin. Beide liefern Suche, Mehrsprachigkeit und Dark Mode in guter Qualität.

Wie installiere ich Astro Starlight 2026?

Für ein neues Projekt nutzt du npm create astro@latest mit dem Template starlight. In ein bestehendes Astro Projekt kommt es mit npx astro add starlight. Danach legst du Markdown Dateien in src/content/docs/ an, und jede Datei wird automatisch zu einer Seite. Mit npm run dev siehst du das Ergebnis sofort lokal im Browser.

Kann ich Astro Starlight in eine bestehende Website einbauen?

Ja, wenn deine Website mit Astro läuft. Du fügst Starlight als Integration hinzu und legst die Inhalte in einen Unterordner von src/content/docs/, zum Beispiel guides. So erscheint die Doku unter diesem Pfad, ohne Subdomain und ohne zweites System. Die übrigen Seiten deiner Website laufen wie gewohnt in demselben Projekt weiter.

Welche Suche nutzt Astro Starlight?

Standard ist Pagefind, eine schnelle Volltextsuche für statische Seiten. Sie läuft ohne Konfiguration und braucht weder API Key noch externen Dienst. Einzelne Seiten oder Abschnitte kannst du gezielt vom Index ausnehmen. Als offizielles Plugin steht Algolia DocSearch bereit, und Typesense gibt es als selbst hostbare Alternative aus der Community.

Unterstützt Astro Starlight mehrere Sprachen?

Ja, Internationalisierung gehört zum Kern von Starlight. Die eigene Projektseite ist selbst in vielen Sprachen verfügbar, darunter Deutsch. Deine Inhalte legst du dafür pro Sprache an und übersetzt sie selbst oder mit Werkzeugen deiner Wahl. Für VS Code gibt es außerdem die Community Erweiterung starlight-i18n, die beim Übersetzen der Seiten hilft.

Kann ich in Astro Starlight React oder Vue nutzen?

Ja, Starlight bindet dich nicht an ein UI Framework. Du kannst Komponenten aus React, Vue, Svelte oder Solid einsetzen. Dank Astro Islands laden sie standardmäßig kein JavaScript im Browser. Erst wenn du eine Komponente ausdrücklich interaktiv machst, kommt der nötige Code hinzu. So bleibt auch eine größere Doku angenehm schnell und schlank.

Wie versioniere ich Doku mit Astro Starlight?

Mehrere Doku Versionen sind nicht fest eingebaut. Dafür gibt es das Community Plugin starlight-versions, das deine Seiten pro Version bereitstellt. Prüfe vorher, ob es zu deinem Release Prozess passt. Ist Versionierung für dein Produkt zentral und du arbeitest ohnehin mit React, kann Docusaurus der kürzere Weg sein, weil es das direkt mitbringt.

Kann ich Astro Starlight selbst hosten?

Ja. Doku Seiten werden standardmäßig vorgerendert, das Ergebnis sind statische Dateien. Die kannst du auf einem eigenen Server in Deutschland oder bei jedem anderen Hoster ausliefern. Serverseitiges Rendern ist über einen Astro Adapter ebenfalls möglich, für reine Doku aber selten nötig. Wichtig sind am Ende passende Cache Header für den Ordner mit den Assets.

Wie hilft NCA beim Einsatz von Astro Starlight?

Wir arbeiten täglich mit Astro und helfen Teams, Starlight neutral gegen andere Doku Werkzeuge einzuordnen. Auf Wunsch begleiten wir auch Setup, Hosting in Deutschland und Tests. Der Ablauf ist einfach: kostenloses Kennenlernen, Aufwand gemeinsam schätzen und danach transparente Minuten-Abrechnung, ganz ohne feste Pakete und ohne Mindestlaufzeit.