Seminar Docusaurus – Monorepos und mehrere Dokumentationsbereiche

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Anwendungsfälle und Grenzen prüfen
3. Schritt 2: Workspace-Struktur entwerfen
4. Schritt 3: Mehrere Docs-Instanzen konfigurieren
5. Schritt 4: Versionierungszyklen trennen
6. Schritt 5: Gemeinsame Komponenten und Inhalte bereitstellen
7. Schritt 6: Selektive Builds und Caches planen
8. Schritt 7: Eigentümerschaft und Releases organisieren
9. Schritt 8: Integration und Wartbarkeit testen
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar behandelt Docusaurus in Monorepositories und bei mehreren getrennten Dokumentationsbereichen innerhalb einer Site. Workspace-Struktur, mehrere Content-Plugin-Instanzen, gemeinsame Pakete, unabhängige Versionierung, Build-Auslöser, Eigentümerschaft und Integrationstests werden systematisch aufgebaut.

• geeignete Grenzen für Produkte, Teams und Dokumentationsbereiche festlegen
• mehrere Docs-Instanzen mit eindeutigen IDs, Routen und Sidebars konfigurieren
• gemeinsame Komponenten und Konfigurationen ohne unkontrollierte Kopplung bereitstellen
• Builds, Releases und Verantwortlichkeiten in einem Monorepository effizient organisieren

Seminarinhalte

Schritt 1: Anwendungsfälle und Grenzen prüfen

Mehrere Sidebars, mehrere Docs-Instanzen und mehrere eigenständige Sites lösen unterschiedliche Probleme. Der tatsächliche Bedarf wird anhand von Versionierungszyklus, Navigation, Zugriffsmodell und Teamautonomie bestimmt.

• fachliche Bereiche und Release-Zyklen erfassen
• gemeinsame und unabhängige Navigation unterscheiden
• eine oder mehrere Sites anhand klarer Kriterien wählen

Schritt 2: Workspace-Struktur entwerfen

Site, Inhalte, Komponenten, Konfiguration und Werkzeuge werden in nachvollziehbaren Paketen organisiert. Abhängigkeiten verlaufen bewusst in eine Richtung und vermeiden zirkuläre Kopplung.

• Workspace-Pakete und Verantwortlichkeiten definieren
• gemeinsame Konfiguration von projektspezifischer Konfiguration trennen
• Build- und Cache-Verzeichnisse sauber abgrenzen

Schritt 3: Mehrere Docs-Instanzen konfigurieren

Jede Content-Plugin-Instanz erhält eine eindeutige ID, einen eigenen Inhaltsordner, Route-Basis und Sidebar-Konfiguration. Die Standardinstanz wird bewusst festgelegt und Route-Konflikte werden ausgeschlossen.

• Plugin-IDs und Pfade vergeben
• Inhalts- und Sidebar-Verzeichnisse zuordnen
• Navbar-Einstiege und Route-Basen prüfen

Schritt 4: Versionierungszyklen trennen

Dokumentationsbereiche können unabhängig versioniert werden, wenn sie eigene Release-Zyklen besitzen. Snapshot-Befehle, Versionsordner und Auswahlkomponenten werden pro Instanz nachvollziehbar verwaltet.

• Versionierungsbedarf je Bereich bewerten
• Versionsnamen und Freigaberegeln definieren
• alte Versionen und gemeinsame Inhalte behandeln

Schritt 5: Gemeinsame Komponenten und Inhalte bereitstellen

Design-Komponenten, MDX-Bausteine und Konfigurationshelfer werden als klar versionierte interne Pakete angeboten. Gemeinsame Inhalte werden nicht unkontrolliert kopiert, sondern mit dokumentierten Abhängigkeiten eingebunden.

• öffentliche Komponenten-API definieren
• gemeinsame Inhalte nach Lebenszyklus klassifizieren
• Änderungs- und Kompatibilitätsregeln festlegen

Schritt 6: Selektive Builds und Caches planen

Änderungspfade bestimmen, welche Site, Instanz oder Qualitätsprüfung neu ausgeführt werden muss. Cache-Schlüssel berücksichtigen sowohl lokale Inhalte als auch gemeinsame Pakete und Konfigurationen.

• betroffene Pakete und Inhalte aus Änderungen ableiten
• Build-Matrix und parallele Jobs entwerfen
• Cache-Invalidierung bei gemeinsamen Änderungen testen

Schritt 7: Eigentümerschaft und Releases organisieren

Teams erhalten klare Verantwortung für Inhaltsbereiche und gemeinsame Plattformpakete. Freigaben können unabhängig erfolgen, während zentrale Standards und Sicherheitsupdates koordiniert bleiben.

• Code- und Content-Owner je Pfad festlegen
• Release-Verantwortung und Abhängigkeiten dokumentieren
• zentrale Änderungen mit Migrationshinweisen ausrollen

Schritt 8: Integration und Wartbarkeit testen

Neben Paket- und Komponententests prüft ein vollständiger Site-Build das Zusammenspiel aller Instanzen. Navigation, Suche, Versionen, Sprachen und gemeinsam genutzte Komponenten werden als Integration betrachtet.

• vollständigen Produktions-Build automatisieren
• Routen und Navigation aller Bereiche testen
• Kompatibilitätsmatrix für gemeinsame Pakete pflegen

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.

• Entwurf eines Monorepository mit Site-, Content-, Komponenten- und Konfigurationspaketen
• Konfiguration zweier Docs-Plugin-Instanzen mit getrennten Sidebars und Versionierungszyklen
• Aufbau einer selektiven Build-Matrix mit gemeinsamen Qualitätsgates

Zielgruppe und Voraussetzungen

Zielgruppe: Plattformteams, Softwarearchitekten, Docusaurus-Entwickler, DevOps-Verantwortliche und technische Redaktionen mit mehreren Produktbereichen

Voraussetzungen: Sichere Docusaurus-Grundkenntnisse, Erfahrung mit Git und Paketmanagern; Grundverständnis von Workspaces und CI/CD