Seminar Docusaurus – Custom Pages, Routing und Client-Architektur

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Routingmodell und Seitentypen verstehen
3. Schritt 2: Eigene Seiten mit Layout aufbauen
4. Schritt 3: Statische Generierung und Hydration berücksichtigen
5. Schritt 4: Browserabhängige Funktionen sicher kapseln
6. Schritt 5: Client-Module und Lebenszyklen einsetzen
7. Schritt 6: Build-Time-Daten bereitstellen
8. Schritt 7: Fehlerseiten, Weiterleitungen und Randfälle behandeln
9. Schritt 8: Tests und Wartungsgrenzen definieren
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar zeigt, wie individuelle Seiten und interaktive Funktionen upgradefähig in die Docusaurus-Architektur integriert werden. Schwerpunkte sind Routing, Layouts, statische Generierung, Hydration, Browsergrenzen, Client-Module, Build-Time-Daten und robuste Fehlerbehandlung.

• eigene Seiten und Routen kontrolliert in eine Docusaurus-Site integrieren
• serverseitige Generierung und clientseitige Hydration technisch korrekt berücksichtigen
• globale Client-Funktionen mit klaren Lebenszyklen und geringer Kopplung umsetzen
• Datenflüsse, Fehlerfälle und Tests für individuelle Funktionen strukturieren

Seminarinhalte

Schritt 1: Routingmodell und Seitentypen verstehen

Dateibasierte Seiten, Dokumentrouten, Blogrouten und plugin-erzeugte Routen werden voneinander abgegrenzt. Konflikte und Prioritäten werden bereits bei der Pfadplanung erkannt.

• Routenquellen und Namensräume inventarisieren
• stabile Slugs und Pfadkonventionen festlegen
• Kollisionen zwischen Content-Plugins vermeiden

Schritt 2: Eigene Seiten mit Layout aufbauen

Individuelle React-Seiten werden mit dem vorhandenen Layout, Theme-Komponenten und Metadaten verbunden. Inhalt und Präsentation bleiben modular, damit die Seite nicht zu einer isolierten Sonderlösung wird.

• Seitenkomponente und Layout-Vertrag definieren
• Seitentitel und Metadaten setzen
• wiederverwendbare Abschnitte in Komponenten auslagern

Schritt 3: Statische Generierung und Hydration berücksichtigen

Docusaurus rendert Seiten vorab als statisches HTML und aktiviert Interaktion anschließend im Browser. Komponenten müssen deshalb beim ersten Server- und Client-Render dieselbe Struktur liefern.

• serverseitig verfügbare Daten von Browserdaten trennen
• Hydrationsabweichungen erkennen und vermeiden
• statische Grundfunktion ohne JavaScript erhalten

Schritt 4: Browserabhängige Funktionen sicher kapseln

Zugriffe auf Fenster, Speicher, Medienabfragen oder browsergebundene Bibliotheken werden erst im geeigneten Client-Kontext ausgeführt. Fallbacks halten die statische Ausgabe verständlich.

• BrowserOnly und Effekte gezielt einsetzen
• Fallback-Inhalte für die statische Ausgabe definieren
• clientseitige Bibliotheken verzögert laden

Schritt 5: Client-Module und Lebenszyklen einsetzen

Globale Seiteneffekte werden als Client-Module mit klarer Initialisierung und Route-Update-Logik umgesetzt. Seiteneffekte bleiben idempotent und werden bei Navigation korrekt bereinigt.

• globale Initialisierung von routenabhängiger Logik trennen
• Route-Updates ohne Mehrfachregistrierung verarbeiten
• Listener und Ressourcen zuverlässig freigeben

Schritt 6: Build-Time-Daten bereitstellen

Daten, die während des Builds verfügbar sind, werden kontrolliert geladen und als statische Daten an Seiten oder Plugins übergeben. Geheimnisse oder unnötig große Datenmengen gelangen nicht in das Browserpaket.

• Datenquelle und Aktualisierungstakt bestimmen
• serialisierbare Seitendaten erzeugen
• öffentliche und interne Informationen trennen

Schritt 7: Fehlerseiten, Weiterleitungen und Randfälle behandeln

Nicht gefundene Seiten, veraltete Pfade und unvollständige Daten erhalten vorhersehbare Reaktionen. Weiterleitungen werden zentral verwaltet und regelmäßig auf Notwendigkeit geprüft.

• 404- und Fehlerdarstellung anpassen
• Weiterleitungsregeln versionieren
• fehlende Daten mit kontrollierten Fallbacks behandeln

Schritt 8: Tests und Wartungsgrenzen definieren

Eigene Seiten werden auf Build-Fähigkeit, Routen, Interaktion, Zugänglichkeit und Hydration geprüft. Abhängigkeiten von internen Theme-Strukturen werden minimiert und dokumentiert.

• Produktions-Build und Routentests automatisieren
• Interaktionen und Fokusverhalten testen
• Upgrade-Risiken und Eigentümerschaft festhalten

Praxisphasen

Die einzelnen Arbeitsschritte werden an einer durchgängigen Übungsplattform umgesetzt. Konfigurationen, Inhalte und Prüfungen werden schrittweise erweitert und jeweils mit einem produktionsnahen Build kontrolliert.

• Entwicklung einer individuellen Landingpage mit Layout, Metadaten und wiederverwendbaren Komponenten
• Einbau einer browserabhängigen Funktion mit statischem Fallback und korrekter Hydration
• Implementierung eines Client-Moduls mit Route-Update und automatisierten Prüfungen

Zielgruppe und Voraussetzungen

Zielgruppe: Frontend-Entwickler, Docusaurus-Entwickler, Documentation Engineers und Plattformteams mit individuellen Portalanforderungen

Voraussetzungen: Sichere Docusaurus-Grundkenntnisse sowie Grundlagen in JavaScript oder TypeScript und React