Ihr kennt das alle: Die API ist fertig, das Feature funktioniert – aber wo bleibt die Dokumentation? Bei unseren Consulting-Projekten sehen wir es immer wieder: Teams kämpfen mit veralteten Wiki-Systemen, unübersichtlichen Markdown-Sammlungen oder teuren SaaS-Lösungen, die mehr kosten als sie bringen. Mit Astro Starlight gibt es endlich eine Lösung, die Developer-Herzen höher schlagen lässt und gleichzeitig Entscheider überzeugt.
Nach über 15 Jahren Spezialisierung auf Softwarequalität, Open Source und Remote Consulting haben wir bei Never Code Alone dutzende Dokumentations-Systeme gesehen und implementiert. Starlight hat uns überzeugt – und hier erfahrt ihr warum.
Was ist Astro Starlight und warum solltet ihr es kennen?
Astro Starlight ist ein vollwertiges Documentation Framework, das auf dem Astro-Web-Framework aufbaut. Anders als reine Static Site Generators wurde Starlight von Grund auf für technische Dokumentation konzipiert. Das Astro-Team, das auch die offizielle Astro-Dokumentation damit betreibt, hat die typischen Schmerzpunkte von Developer-Docs gelöst: Navigation, Suche, Internationalisierung, SEO und Dark Mode funktionieren out of the box.
Der entscheidende Unterschied zu anderen Tools: Starlight kombiniert die Geschwindigkeit eines statischen Site-Generators mit der Flexibilität eines modernen Web-Frameworks. Ihr könnt React, Vue, Svelte oder Solid-Komponenten direkt in eure Dokumentation einbetten – ohne das gesamte System umzubauen. Für Teams, die bereits in einem dieser Ökosysteme arbeiten, bedeutet das: Wiederverwendung statt Neuimplementierung.
Wie installiert ihr Astro Starlight richtig?
Die Installation von Starlight gehört zu den angenehmsten Erfahrungen im JavaScript-Ökosystem. Ihr braucht Node.js 18.14.1 oder höher und könnt sofort loslegen:
npm create astro@latest -- --template starlightDer CLI-Wizard führt euch durch die Konfiguration und erstellt ein vollständiges Projekt mit allen notwendigen Dateien. Nach wenigen Sekunden habt ihr:
cd mein-projekt
npm run devDer Development-Server startet in unter zwei Sekunden – ein Unterschied, den ihr sofort spürt, wenn ihr von Docusaurus oder ähnlichen Tools kommt. Bei größeren Projekten haben wir Startzeiten von über 20 Sekunden bei Docusaurus gemessen, während Starlight konstant unter drei Sekunden bleibt.
Für bestehende Astro-Projekte ist die Integration noch einfacher:
npx astro add starlightDieser Befehl installiert alle Dependencies und konfiguriert automatisch die astro.config.mjs.
Starlight vs. Docusaurus: Welches Tool ist besser?
Diese Frage hören wir in jedem dritten Consulting-Gespräch. Die ehrliche Antwort: Es kommt auf euren Use Case an.
Docusaurus basiert auf React und hat den Vorteil der Reife – Version 3.0 ist stabil und erprobt. Das Framework bringt Features wie Math-Rendering und Diagram-Support mit, die bei Starlight noch über Plugins nachgerüstet werden müssen.
Starlight punktet bei Performance und Framework-Flexibilität. Da es auf Astro aufbaut, könnt ihr Komponenten aus React, Vue, Svelte oder Solid mischen. Das ist ein echter Vorteil für Teams, die nicht ausschließlich im React-Ökosystem arbeiten. Ein weiterer Punkt: Docusaurus erfordert die Kompatibilität zwischen React, Docusaurus selbst und allen Plugins. Bei Starlight habt ihr weniger bewegliche Teile – das Team, das Astro entwickelt, entwickelt auch Starlight.
Aus unserer Praxis-Empfehlung: Wenn ihr bereits React nutzt und Math/Diagrams braucht, ist Docusaurus solide. Für neue Projekte ohne Framework-Bindung oder wenn Performance kritisch ist, würden wir Starlight wählen.
Wie strukturiert ihr eure Dokumentation sinnvoll?
Die Projektstruktur von Starlight folgt einem klaren Pattern:
src/
├── content/
│ ├── docs/ # Eure Dokumentationsseiten
│ │ ├── index.md
│ │ ├── getting-started/
│ │ └── reference/
│ └── i18n/ # Übersetzungsdateien (optional)
├── assets/ # Bilder und Medien
└── content.config.ts # Content Collection KonfigurationStarlight nutzt Astros Content Collections, was Frontmatter-Validierung mit TypeScript-Typsicherheit bringt. Jede Markdown-, MDX- oder Markdoc-Datei im docs/-Verzeichnis wird automatisch zu einer Seite.
Das Sidebar-Menü könnt ihr automatisch aus der Ordnerstruktur generieren lassen:
sidebar: [
{
label: 'Getting Started',
autogenerate: { directory: 'getting-started' }
},
{
label: 'API Reference',
autogenerate: { directory: 'reference' }
}
]Unser Praxis-Tipp: Nutzt aussagekräftige Ordnernamen und haltet die Hierarchie flach. Mehr als drei Ebenen verwirren eure User.
Welche SEO-Features bringt Starlight mit?
Für technische Entscheider ist SEO oft ein unterschätzter Faktor bei Dokumentation. Starlight liefert hier solide Grundlagen: automatische Sitemaps, OpenGraph-Tags, strukturierte Meta-Descriptions und semantisches HTML.
Die Konfiguration erfolgt zentral in der astro.config.mjs:
starlight({
title: 'Meine API Docs',
description: 'Vollständige Dokumentation für unsere REST API',
head: [
{
tag: 'meta',
attrs: {
property: 'og:image',
content: 'https://example.com/og-image.png'
}
}
]
})Für Structured Data wie JSON-LD müsst ihr die Head-Komponente überschreiben – ein Feature, das Starlight elegant über Component Overrides löst. In unseren Projekten integrieren wir hier auch Analytics und Custom Tracking.
Die Build-Größe spielt ebenfalls eine Rolle: Starlight-Seiten sind extrem schlank. Eine typische Dokumentationsseite überträgt weniger als 50 KB komprimiert – verglichen mit dem HTTP-Archive-Median von über 2.000 KB für Webseiten. Das verbessert nicht nur Core Web Vitals, sondern reduziert auch Hosting-Kosten.
Wie funktioniert Mehrsprachigkeit mit Starlight?
Internationalisierung ist bei Starlight keine nachträgliche Ergänzung, sondern tief integriert. Die Konfiguration erfolgt über die locales-Option:
starlight({
locales: {
root: {
label: 'Deutsch',
lang: 'de'
},
en: {
label: 'English',
lang: 'en'
}
}
})Starlight bringt UI-Übersetzungen für über 30 Sprachen mit – von Arabisch bis Vietnamesisch. Eure Dokumentationsinhalte verwaltet ihr in entsprechenden Unterordnern:
src/content/docs/
├── index.md # Deutsch (root)
└── en/
└── index.md # EnglischDer Language Switcher funktioniert automatisch und Starlight generiert korrekte hreflang-Tags für SEO.
Wie deployed ihr Starlight-Dokumentation?
Deployment ist einer der größten Vorteile von Static Site Generators. Starlight-Projekte laufen auf praktisch jeder Hosting-Plattform:
Vercel (unsere Empfehlung für die meisten Projekte):
npx astro add vercelVercel erkennt Astro-Projekte automatisch und konfiguriert Build-Settings, Caching und CDN optimal. Preview Deployments für Pull Requests sind inklusive.
Netlify:
npx astro add netlifyFür Custom Caching fügt ihr eine public/_headers Datei hinzu:
/_astro/*
Cache-Control: public, max-age=31536000, immutableGitHub Pages funktioniert ebenfalls, erfordert aber etwas mehr Konfiguration für die base-URL. Für interne Dokumentation nutzen wir oft GitLab Pages oder Cloudflare Pages.
Kann ich Starlight mit bestehenden APIs integrieren?
Ja, und hier wird es für Enterprise-Teams interessant. Starlight lässt sich über Plugins erweitern und unterstützt Server-Side Rendering (SSR) mit Adaptern für alle gängigen Plattformen.
Für OpenAPI-Dokumentation gibt es das Community-Plugin starlight-openapi:
npm install starlight-openapiDas Plugin generiert aus euren OpenAPI-Specs automatisch Dokumentationsseiten – inklusive Request/Response-Beispielen.
Astros Islands Architecture ermöglicht es, interaktive Komponenten nur dort zu laden, wo sie benötigt werden. Das bedeutet: Eure Docs bleiben schnell, auch wenn ihr komplexe API-Playgrounds einbettet.
Welche Customization-Möglichkeiten bietet Starlight?
Die Theme-Anpassung erfolgt über CSS Custom Properties – kein Compile-Step erforderlich:
:root {
--sl-color-accent: #3b82f6;
--sl-color-accent-high: #1d4ed8;
--sl-font-size-base: 1rem;
}Für tiefgreifendere Änderungen unterstützt Starlight Component Overrides. Ihr könnt einzelne UI-Elemente durch eigene Implementierungen ersetzen:
starlight({
components: {
Header: './src/components/CustomHeader.astro'
}
})Das ermöglicht Branding auf Enterprise-Niveau, ohne in den Framework-Code einzugreifen.
Wie performant ist Starlight wirklich?
Performance ist keine Nebensache – sie ist Kernfeature. Starlight nutzt Astros Zero-JavaScript-Default: Seiten werden als statisches HTML ausgeliefert, ohne Client-Side JavaScript, es sei denn, ihr fügt explizit interaktive Komponenten hinzu.
Die Zahlen sprechen für sich: Im Website Carbon Calculator schneidet Starlight besser ab als 98% aller getesteten Webseiten. Eine Dokumentationsseite produziert etwa 0.01g CO₂ pro Seitenaufruf – relevant für Unternehmen mit Nachhaltigkeitszielen.
Lighthouse-Scores von 100/100 in allen Kategorien sind keine Ausnahme, sondern die Regel. Das ist keine Marketing-Behauptung, sondern das Ergebnis einer Architektur, die Performance-First entwickelt wurde.
Die integrierte Suche basiert auf Pagefind – einem Rust-basierten Static Search Index, der auch bei tausenden Seiten performant bleibt. Keine externen Services, keine Latenz, keine Kosten.
Fazit: Warum Starlight für eure nächste Dokumentation?
Astro Starlight ist kein weiteres Documentation-Tool im überfüllten Markt. Es ist eine durchdachte Lösung für Teams, die Dokumentation ernst nehmen, aber keine Wochen in Setup und Maintenance investieren wollen.
Die Kombination aus Performance, Flexibilität und Developer Experience macht Starlight zur ersten Wahl für moderne Dokumentationsprojekte. Ob Open-Source-Library, interne API-Docs oder Produkt-Dokumentation – Starlight skaliert mit euren Anforderungen.
Bei Never Code Alone unterstützen wir Teams bei der Implementierung moderner Dokumentationslösungen. Von der initialen Architektur über Custom Theming bis zur CI/CD-Integration – wir bringen eure Docs auf Produktionsqualität.
Ihr plant ein Dokumentationsprojekt oder wollt eure bestehende Lösung modernisieren? Schreibt uns eine Mail an roland@nevercodealone.de oder bucht ein kostenloses Beratungsgespräch. Gemeinsam finden wir die optimale Lösung für eure Anforderungen.
Never Code Alone – Gemeinsam für bessere Software-Qualität!
