Astro-Entwickler in Mannheim

#Handbücher und Hilfecenter für Mannheimer Technikfirmen

Mannheim ist nach der Darstellung der Stadt das Zentrum der Metropolregion Rhein-Neckar mit 2,4 Millionen Einwohnern und rund 920.000 Beschäftigten. Zu den Clustern der städtischen Wirtschaftsförderung gehören Smart Industries und Medizintechnologie. Das Netzwerk Smart Industries verbindet seit 2016 nach eigener Angabe rund 50 Start-ups, Mittelständler, Konzerne und Forschungseinrichtungen aus IT und Industrie. Der Mannheim Medical Technology Campus bringt Unternehmen, Klinik und Forschung räumlich zusammen.

Firmen dieser Art haben etwas gemeinsam: Ihr Wissen steckt in Handbüchern, Datenblättern, Schnittstellenbeschreibungen und Anleitungen für Servicepersonal. Oft liegt es in PDF-Dateien, Wikis oder Ordnern auf dem Laufwerk. Kunden und Monteure finden darin nichts, weil es keine Suche und keine feste Adresse für einen Abschnitt gibt.

Für genau diese Aufgabe gibt es Astro Starlight. Dieser Text beschreibt, was es kann, wo seine Grenzen liegen und wie ein Projekt mit mir abläuft. Die Angaben stammen aus der Starlight-Dokumentation. Die aktuelle Version des Pakets @astrojs/starlight ist laut npm-Registry 0.42.10, veröffentlicht am 6. November 2026, und verlangt Astro ab 7.2.10.

Foto: Flocci Nivis, CC BY 4.0, Wikimedia Commons.

#Was Starlight ist und was es Ihnen abnimmt

Starlight beschreibt sich als vollwertiges Dokumentations-Theme auf Basis von Astro. Ein neues Projekt entsteht mit npm create astro@latest -- --template starlight. Seiten sind Markdown- oder MDX-Dateien in src/content/docs/, Markdoc lässt sich nachrüsten. Jede Datei braucht mindestens einen title im Kopfbereich.

Fertig mitgeliefert werden Kopfzeile, Navigation, Inhaltsverzeichnis je Seite, Hell- und Dunkelmodus, Suche und eine Sitemap, sobald site in der Astro-Konfiguration gesetzt ist. Was Sie sonst selbst bauen müssten, ist damit erledigt. Ihr Aufwand verlagert sich auf Inhalt und Struktur, und genau dort liegt der Wert eines Handbuchs.

Starlight ist ein Astro-Projekt wie jedes andere. Eigene Seiten mit eigenem Layout liegen in src/pages/, und die Komponente StarlightPage setzt dort das Starlight-Layout ein. Ein Produktfinder oder eine Ersatzteilliste kann also neben dem Handbuch stehen, ohne dass Sie ein zweites System betreiben.

#Sidebar: Struktur, die Ihre Leser wiederfinden

Standardmäßig erzeugt Starlight die Sidebar aus der Ordnerstruktur. Jede Datei erscheint mit ihrem title, die Reihenfolge ist alphabetisch nach Datei-ID. Für ein Handbuch ist das ein guter Start und selten das Endergebnis.

Per sidebar in der Konfiguration lässt sich die Navigation von Hand bauen: Links auf Seiten über slug, Links nach außen über label und link, Gruppen mit items, auch verschachtelt. Eine Gruppe kann mit collapsed: true eingeklappt starten. Ein Ordner lässt sich mit autogenerate einbinden, damit neue Seiten von selbst erscheinen:

sidebar: [
  { label: 'Montage', items: [{ autogenerate: { directory: 'montage' } }] },
  { label: 'Fehlercodes', collapsed: true, items: ['fehlercodes/e100'] },
],

Einträge können ein Abzeichen tragen, etwa “Neu” oder einen Hinweis auf einen Entwurf. Für jede Sprache lassen sich Beschriftungen über translations setzen. Für Firmen mit mehreren Produktlinien führt die Plugin-Seite der Dokumentation starlight-sidebar-topics, das die Dokumentation in Bereiche mit je eigener Sidebar teilt. Das ist ein Community-Plugin, kein Teil des Kerns, und ich prüfe vor dem Einsatz, ob es zur Starlight-Version passt.

#Suche: Pagefind eingebaut, Algolia als Option

Jede Starlight-Seite hat laut Dokumentation Volltextsuche mit Pagefind, einem Werkzeug für statische Websites. Es ist keine Konfiguration nötig: Sie bauen und veröffentlichen die Seite, dann funktioniert die Suche. Lokal im Entwicklungsmodus gibt es sie nicht, die Oberfläche weist darauf hin, dass die Suche nur in Produktions-Builds verfügbar ist.

Für ein Handbuch zählt die Feinsteuerung. Mit pagefind: false im Kopfbereich nimmt man eine ganze Seite aus dem Index, mit dem Attribut data-pagefind-ignore nur einen Teil. Interne Hinweise, Entwürfe interner Anleitungen oder Archivseiten bleiben so aus den Trefferlisten. Ob ein Abschnitt in die Suche gehört, entscheiden Sie, und ich trage es ein.

Wer bereits Zugang zum Programm Algolia DocSearch hat, kann Pagefind über das offizielle Plugin @astrojs/starlight-docsearch ersetzen. Dann öffnet die Suchleiste einen Algolia-Dialog. Das ist ein externer Dienst, mehr dazu im Abschnitt zum Datenschutz.

#Versionen: was Starlight selbst tut und was ein Plugin

Technische Dokumentation ändert sich mit dem Produkt. Ein Kunde mit Gerät in Stand A braucht das Handbuch zu Stand A. Die Leitfäden zu Seiten, Sidebar und Mehrsprachigkeit behandeln das nicht. Auf der Plugin-Seite der Dokumentation steht das Community-Plugin starlight-versions mit der Beschreibung “Version your Starlight documentation pages”.

Ich sehe zwei Wege und lege einen davon im Umfang fest:

Beide Wege verlangen dieselbe Entscheidung: Jemand muss entscheiden, wann ein Stand eingefroren wird und wer ältere Stände noch korrigiert. Das ist eine Frage Ihres Produktprozesses, nicht der Technik.

#Mehrsprachigkeit für Märkte außerhalb Deutschlands

Industrie- und Medizintechnikfirmen liefern ins Ausland. Starlight bringt dafür Routing und Rückfallinhalte mit. Sie nennen locales und defaultLocale in der Konfiguration und legen je Sprache einen Ordner an, etwa src/content/docs/de/ und src/content/docs/en/:

defaultLocale: 'de',
locales: {
  de: { label: 'Deutsch' },
  en: { label: 'English' },
},

Gleicher Dateiname in beiden Ordnern verknüpft die Seiten. Fehlt eine Übersetzung, zeigt Starlight den Inhalt der Standardsprache mit dem Hinweis, dass er in der gewählten Sprache noch nicht vorliegt. So können Sie auf Deutsch anfangen und Sprache für Sprache nachziehen. Eine “Root”-Sprache ohne Sprachpräfix in der Adresse ist möglich.

Oberflächentexte wie “Auf dieser Seite” oder “Zum Inhalt springen” sind laut Dokumentation unter anderem auf Deutsch, Englisch, Französisch, Italienisch, Niederländisch, Polnisch, Spanisch, Tschechisch und Norwegisch (Bokmål) vorhanden. Abweichende Begriffe tragen Sie in einer eigenen i18n-Sammlung ein. Die Übersetzung der Inhalte selbst bleibt Ihre Aufgabe. Fachbegriffe für Ihre Zielmärkte kennen Ihre Techniker und Ihre Übersetzer besser als ich.

#MDX-Komponenten: Anleitungen, die man befolgen kann

Mit MDX lassen sich in Markdown Komponenten einbinden. Starlight liefert unter @astrojs/starlight/components fertige mit, darunter Steps für nummerierte Arbeitsschritte, Tabs und TabItem für gleichwertige Varianten, Aside für Hinweise, Card, Badge und FileTree für Verzeichnisstrukturen. Eigene Komponenten kommen aus .astro-Dateien oder aus React, Preact, Svelte, Vue, Solid oder Alpine.

Für ein Servicehandbuch heißt das: Ein Austauschverfahren wird zu Steps, die Varianten je Gerätetyp zu Tabs, ein Warnhinweis zu Aside. Ein Datenblatt kann eine eigene Komponente sein, die ihre Werte aus einer Datenquelle liest. Das Design bestimmen Sie. Eine eigene Farbwelt und Schrift setze ich über customCss um, auf Wunsch mit dem offiziellen Tailwind-Paket @astrojs/starlight-tailwind.

#Pflege: wer ändert was, und woran sieht man es

Dokumentation veraltet leise. Starlight unterstützt die Pflege mit einigen Mitteln:

• lastUpdated zeigt das Datum der letzten Änderung. Standardmäßig stammt es aus der Git-Historie, im Kopfbereich einer Seite lässt es sich überschreiben.
• Mit draft: true gilt eine Seite als Entwurf und kommt nicht in Produktions-Builds.
• Das Community-Plugin starlight-links-validator prüft laut Plugin-Seite auf defekte Links.

Bei Handbüchern prüfe ich Links im Build, damit ein umbenannter Abschnitt nicht still einen Verweis zerstört. Wer die Seiten pflegt, schreibt in Markdown, legt eine Änderung auf einem Zweig an und lässt sie freigeben. Das läuft ohne Datenbank und ohne Login-Seite, die jemand absichern muss.

#Datenschutz: wann die Suche ein Thema wird

Zuständig für Unternehmen in Baden-Württemberg ist der Landesbeauftragte für den Datenschutz und die Informationsfreiheit des Landes. Mit der Pagefind-Standardsuche läuft die Suche ohne externen Anbieter. Das ändert sich mit Algolia DocSearch: Dann kommt ein Dienst dazu, den Ihre Datenschutzerklärung nennen muss. Die DocSearch-Optionen der Starlight-Dokumentation nennen insights, das Suchereignisse an Ihren DocSearch-Index sendet (Standard: aus), und disableUserPersonalization, das verhindert, dass letzte Suchen und Favoriten im lokalen Speicher des Browsers abgelegt werden (Standard: aus).

Der Zugriff auf gespeicherte Informationen im Endgerät fällt unter § 25 TDDDG, der dafür grundsätzlich eine Einwilligung verlangt, mit Ausnahmen in Absatz 2. Ob eine Einstellung unter diese Ausnahmen fällt, beurteilt Ihre Rechtsberatung. Ich halte im Umfang fest, welche Variante gebaut wird, und stelle die Optionen so ein, wie Sie es entscheiden.

#Ablauf eines Starlight-Projekts mit mir

Die Zusammenarbeit läuft vollständig in Textform.

1. Briefing. Sie senden mir die Adresse Ihrer heutigen Dokumentation, das Ziel, den Termin und den aktuellen Stack. Fehlende Angaben erfrage ich per Nachricht.
2. Umfang und Annahmen. Ich halte fest: Sprachen, Produktlinien, Versionen, Suche, Komponenten, Hosting und was ich von Ihnen voraussetze. Gestaltung, Grafiken und Wireframes liefern Sie, ich übernehme die technische Umsetzung. Ich beginne mit der Arbeit erst nach Ihrer schriftlichen Bestätigung des Umfangs.
3. Aufbau auf einer Testumgebung. Sie sehen den Stand auf einer Vorschau-Adresse, mit einigen Ihrer echten Seiten.
4. Abnahme. Maßstab der Abnahme ist der schriftlich vereinbarte Umfang. Wünsche darüber hinaus erfasse ich als gesondertes Angebot.
5. Start und Wartung (optional). Danach kann ich Updates von Astro und Starlight übernehmen. Wie das abläuft, steht auf der Seite Wartung und Support in Mannheim. Nicht genutzte Stunden eines Monats verfallen.

Soll aus dem Handbuch ein Kundenportal mit Anmeldung werden, ist Next.js in Mannheim meist die bessere Grundlage. Wer von einer bestehenden Website umzieht, findet den Ablauf auf der Seite zur Migration nach Astro in Mannheim. Wenn Ihre Redaktion lieber im Editor schreibt, hilft die Seite zu WordPress in Mannheim.

#Checkliste vor dem Start (auch ohne mich nutzbar)

#Häufige Fragen

#Reicht Starlight für ein Handbuch mit mehreren Produktlinien?

Für eine Produktlinie reicht die Sidebar aus Ordnern und Gruppen. Für mehrere trennt das Community-Plugin starlight-sidebar-topics die Dokumentation in Bereiche mit je eigener Sidebar. Ob das passt, lege ich nach Ihrer Produktstruktur im Umfang fest.

#Gibt es in Starlight Versionen wie bei Software-Releases?

Die Plugin-Seite der Dokumentation führt das Community-Plugin starlight-versions mit der Beschreibung “Version your Starlight documentation pages”. Eine Alternative ist ein eigener Build je Produktstand. Welche Variante zu Ihrem Release-Rhythmus passt, kläre ich mit Ihnen schriftlich im Umfang.

#Ist die Suche DSGVO-konform?

Die Standardsuche Pagefind ist laut Dokumentation für statische Websites gebaut und braucht keine Konfiguration. Bei Algolia DocSearch kommt ein externer Dienst dazu, den Ihre Datenschutzerklärung nennen muss. Die rechtliche Bewertung gehört zu Ihrer Rechtsberatung.

#Können unsere Techniker in Markdown schreiben, ohne Programmierkenntnisse?

Ja. Seiten sind Markdown- oder MDX-Dateien mit einem kurzen Kopfbereich. Komponenten wie Schritte, Tabs oder Hinweisboxen setze ich als Vorlagen auf, die Ihre Redaktion nur kopiert und ausfüllt.

#Lassen sich bestehende Handbücher im PDF-Format übernehmen?

Nur als Inhalt, den jemand in Markdown überführt, denn Seiten sind bei Starlight Markdown- oder MDX-Dateien. Ich prüfe mit Ihnen, welche Handbücher sich als Seiten lohnen und welche als Download bleiben.

#Kommen Sie für das Projekt nach Mannheim?

Nein. Ich arbeite von Gdynia aus und nur in Textform: Anfrage, Rückfragen, Umfang, Vorschau-Adresse zur Abnahme. Besprechungen oder Telefonate biete ich nicht an. Eine erste schriftliche Einschätzung zu Ihrem Dokumentationsprojekt kostet nichts.

#Schreiben Sie mir

Schicken Sie mir über das Kontaktformular die Adresse Ihrer heutigen Dokumentation oder ein Beispiel-Handbuch, Ihr Ziel, Ihren Termin, die gewünschten Sprachen und den aktuellen Stack. Ich lese alles durch und melde mich schriftlich mit Rückfragen und einer ersten Einschätzung. Dafür berechne ich nichts. Passt Starlight nicht zu Ihrem Vorhaben, schreibe ich das offen und nenne die bessere Lösung.