Seminar Docusaurus – Kompaktseminar: Dokumentationsportal in drei Tagen

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Zielbild und Projektbasis festlegen
3. Schritt 2: Site-Konfiguration und Navigation aufbauen
4. Schritt 3: Content-Modell und Markdown anwenden
5. Schritt 4: MDX und Komponenten nutzen
6. Schritt 5: Branding und responsive Gestaltung umsetzen
7. Schritt 6: Versionen und Sprachen einordnen
8. Schritt 7: Suche und Metadaten konfigurieren
9. Schritt 8: Qualität, Sicherheit und Governance etablieren
10. Schritt 9: CI/CD und Deployment aufbauen
11. Schritt 10: Betriebsbasis und Weiterentwicklung planen
12. Praxisphasen
13. Zielgruppe und Voraussetzungen

Zielsetzung

Das Kompaktseminar führt in drei Tagen von der Projektentscheidung zu einem geprüften Docusaurus-Dokumentationsportal. Grundlagen, Informationsarchitektur, Markdown und MDX, Branding, Versionen, Sprachen, Suche, Qualität, Sicherheit, CI/CD und Betrieb werden in verdichteter Form an einer gemeinsamen Praxisplattform umgesetzt.

• eine Docusaurus-Site vollständig aufsetzen, strukturieren und gestalten
• wartbare Inhalte und wiederverwendbare MDX-Bausteine erstellen
• zentrale Funktionen wie Versionierung, Internationalisierung und Suche einordnen und konfigurieren
• Qualitätsprüfungen, Build und Deployment als durchgängigen Lieferprozess aufbauen

Seminarinhalte

Schritt 1: Zielbild und Projektbasis festlegen

Anwendungsfall, Zielgruppen, Inhalte und Betriebsgrenzen werden geklärt. Anschließend entsteht eine reproduzierbare Projektbasis mit Versionierung, typisierter Konfiguration und sauberer Verzeichnisstruktur.

• Projektziele und Erfolgskriterien definieren
• Arbeitsumgebung und Repository einrichten
• klassisches Preset erzeugen und bereinigen

Schritt 2: Site-Konfiguration und Navigation aufbauen

Globale Daten, URL-Modell, Navbar, Footer und Sidebars werden konsistent konfiguriert. Die Navigation folgt priorisierten Aufgaben und bleibt für spätere Versionen und Sprachen erweiterbar.

• Site-Konfiguration strukturieren
• manuelle und automatische Sidebar kombinieren
• Landingpage und globale Navigation verbinden

Schritt 3: Content-Modell und Markdown anwenden

Inhaltstypen, Front Matter, IDs, Slugs und Überschriften werden vereinheitlicht. Dokumente, freie Seiten und zeitbezogene Mitteilungen erhalten klar getrennte Aufgaben.

• Vorlagen für zentrale Inhaltstypen erstellen
• Links, Assets, Codeblöcke und Hinweise einsetzen
• Inhaltsstruktur auf Verständlichkeit prüfen

Schritt 4: MDX und Komponenten nutzen

Wiederkehrende Darstellungen werden in einfache MDX- und React-Komponenten überführt. Props, Fallbacks und redaktionelle Nutzungsregeln werden so gestaltet, dass der Content lesbar bleibt.

• Komponente importieren und parametrisieren
• Tabs und strukturierte Beispiele umsetzen
• SSR- und Zugänglichkeitsgrenzen beachten

Schritt 5: Branding und responsive Gestaltung umsetzen

Design-Tokens, Farben, Typografie, Logo und zentrale Layoutwerte werden angepasst. Dunkelmodus, mobile Ansicht, Fokusdarstellung und Bildvarianten werden gemeinsam geprüft.

• Infima-Variablen und Custom-CSS einsetzen
• globale und lokale Styles trennen
• responsive und barrierearme Darstellung testen

Schritt 6: Versionen und Sprachen einordnen

Ein kleiner Versions- und Locale-Prototyp zeigt Auswirkungen auf Routen, Sidebars, Navigation und Pflege. Es wird entschieden, welche Funktionen produktiv benötigt werden und welche zunächst vorbereitet bleiben.

• Snapshot und Versionsauswahl demonstrieren
• zweite Locale konfigurieren und Übersetzungsdateien erzeugen
• Pflegeaufwand und Freigaberegeln bewerten

Schritt 7: Suche und Metadaten konfigurieren

Suchanforderungen, Seitentitel, Beschreibungen, Slugs, Sitemap und Indexierungsregeln werden aufeinander abgestimmt. Ein Testkatalog prüft, ob zentrale Inhalte zuverlässig gefunden werden.

• Sucharchitektur auswählen
• globale und seitenspezifische Metadaten pflegen
• Sitemap, Robots-Regeln und Suchtests kontrollieren

Schritt 8: Qualität, Sicherheit und Governance etablieren

Linting, Linkprüfung, Produktions-Build, Inhaltsfreigabe und Abhängigkeitskontrolle werden als Mindestgates definiert. Rollen, Geheimnisse, Drittkomponenten und Aktualitätsfristen erhalten klare Regeln.

• Qualitäts- und Sicherheitscheckliste erstellen
• Review und Eigentümerschaft festlegen
• Vorschauen und externe Komponenten kontrollieren

Schritt 9: CI/CD und Deployment aufbauen

Die Site wird reproduzierbar installiert, geprüft, gebaut und als unveränderliches Artefakt veröffentlicht. Vorschau, Freigabe, Rollback und Smoke-Test werden in einen einfachen Betriebsablauf überführt.

• CI-Jobs und Artefaktfluss definieren
• produktionsnahen Build lokal abnehmen
• Deployment- und Rollback-Schritte dokumentieren

Schritt 10: Betriebsbasis und Weiterentwicklung planen

Zum Abschluss entstehen ein Wartungsplan, ein Troubleshooting-Ablauf und eine priorisierte Erweiterungsliste. Plugins, Monorepo, API-Dokumentation und Skalierung werden anhand des konkreten Bedarfs eingeordnet.

• Runbook für häufige Fehlerbilder erstellen
• Update- und Prüfzyklus festlegen
• nächste Ausbaustufen nach Nutzen und Risiko priorisieren

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.

• Aufbau eines vollständigen Docusaurus-Portals mit Navigation, Content und Branding
• Integration von MDX-Komponenten, Versionierungs- und Locale-Prototyp sowie Such- und Metadatenkonzept
• Einrichtung einer CI-Prüfkette mit Produktions-Build, Artefakt, Deployment- und Rollback-Ablauf

Zielgruppe und Voraussetzungen

Zielgruppe: Projektteams, technische Redaktionen, Entwickler, DevOps-Verantwortliche und Product Owner, die Docusaurus in kurzer Zeit ganzheitlich einführen möchten

Voraussetzungen: Grundkenntnisse in Markdown, Git und Kommandozeile sind hilfreich; React-Kenntnisse sind für die vertiefenden Komponentenübungen von Vorteil