Seminar Docusaurus – Grundlagen und Projektstart

Inhaltsübersicht

1. Zielsetzung
2. Schritt 1: Einsatzbereich und Architektur einordnen
3. Schritt 2: Arbeitsumgebung vorbereiten
4. Schritt 3: Projekt erzeugen und Struktur verstehen
5. Schritt 4: Grundkonfiguration aufbauen
6. Schritt 5: Erste Dokumente und Seiten erstellen
7. Schritt 6: Sidebars und Navigation konfigurieren
8. Schritt 7: Darstellung und Assets anpassen
9. Schritt 8: Build, Vorschau und Basisqualität prüfen
10. Praxisphasen
11. Zielgruppe und Voraussetzungen

Zielsetzung

Das Seminar führt systematisch von der Einordnung eines Docusaurus-Projekts bis zu einer produktionsfähigen Grundstruktur. Installation, Projektaufbau, Konfiguration, Dokumente, Seiten, Blog, Navigation, Styling, Build und erste Qualitätsprüfungen werden in einer zusammenhängenden Übungsplattform umgesetzt.

• Docusaurus als statischen Dokumentationsgenerator fachlich und technisch einordnen
• ein neues Projekt reproduzierbar installieren und konfigurieren
• Dokumente, Seiten, Navigation und grundlegendes Styling selbstständig aufbauen
• einen produktionsnahen Build prüfen und für die weitere Entwicklung strukturieren

Seminarinhalte

Schritt 1: Einsatzbereich und Architektur einordnen

Docusaurus wird als statisch generierte React-Anwendung mit Markdown- und MDX-Inhalten betrachtet. Geeignete Einsatzfelder, Systemgrenzen und typische Rollen werden gegenüber dynamischen Content-Systemen abgegrenzt.

• Zielgruppen und Dokumentationsarten erfassen
• statische Auslieferung und clientseitige Interaktion unterscheiden
• Entscheidungskriterien für den Projekteinsatz formulieren

Schritt 2: Arbeitsumgebung vorbereiten

Laufzeit, Paketmanager, Versionsverwaltung und Editor werden in kompatiblen Versionen eingerichtet. Eine saubere Projektbasis verhindert spätere Abweichungen zwischen lokaler Entwicklung und CI.

• Laufzeit- und Paketmanager-Version prüfen
• Git-Repository und Ignore-Regeln anlegen
• Installations- und Startbefehle dokumentieren

Schritt 3: Projekt erzeugen und Struktur verstehen

Ein Projekt mit dem klassischen Preset wird erzeugt und die Aufgaben der zentralen Ordner und Dateien werden nachvollzogen. Beispieldaten werden kontrolliert entfernt oder in eine eigene Struktur überführt.

• Konfigurationsdatei und Preset lokalisieren
• docs, blog, src und static fachlich zuordnen
• Build-, Cache- und Übersetzungsverzeichnisse unterscheiden

Schritt 4: Grundkonfiguration aufbauen

Titel, URL, Basis-Pfad, Sprache, Navigation, Footer und Preset-Optionen werden konsistent eingestellt. Konfigurationen werden typisiert und in kleine nachvollziehbare Blöcke gegliedert.

• globale Site-Daten setzen
• Navbar und Footer strukturieren
• Konfigurationsfehler über Entwicklungsserver und Build erkennen

Schritt 5: Erste Dokumente und Seiten erstellen

Markdown-Dokumente und freie Seiten erhalten klare IDs, Slugs, Beschreibungen und eine verständliche Überschriftenstruktur. Der Unterschied zwischen Dokumentation, Seiten und Blog wird praktisch sichtbar.

• Dokument mit Front Matter anlegen
• freie Landingpage erstellen
• Blog oder Änderungsnachricht als separaten Inhaltstyp einordnen

Schritt 6: Sidebars und Navigation konfigurieren

Manuelle und automatisch erzeugte Sidebars werden verglichen. Kategorien, Sortierung, Breadcrumbs und Querverweise werden so aufgebaut, dass Aufgabenpfade statt Dateistrukturen im Vordergrund stehen.

• Sidebar automatisch aus Ordnern erzeugen
• gezielte manuelle Einträge ergänzen
• Navigationspfade und tote Enden prüfen

Schritt 7: Darstellung und Assets anpassen

Logo, Bilder, globale CSS-Variablen und einfache Komponenten werden eingebunden. Hell- und Dunkelmodus, responsive Verhalten und grundlegende Zugänglichkeit werden von Beginn an berücksichtigt.

• statische und dokumentnahe Assets unterscheiden
• Farben und Typografie über zentrale Variablen anpassen
• Bilder mit verständlichen Alternativtexten einbinden

Schritt 8: Build, Vorschau und Basisqualität prüfen

Der Produktions-Build wird lokal erzeugt und mit dem integrierten Server kontrolliert. Warnungen, defekte Links und Pfadfehler werden behoben, bevor ein erstes Deployment vorbereitet wird.

• Produktions-Build ausführen
• Build-Ausgabe lokal prüfen
• Grundregeln für Versionspflege und weitere Automatisierung 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.

• Aufbau einer vollständigen Docusaurus-Grundinstallation mit typisierter Konfiguration
• Erstellung einer kleinen Dokumentationsstruktur mit Seiten, Sidebar, Assets und Navigation
• Durchführung eines Produktions-Builds mit Fehleranalyse und lokaler Abnahme

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redaktionen, Entwickler, Projektteams, DevOps-Einsteiger und Verantwortliche für neue Dokumentationsportale

Voraussetzungen: Sicherer Umgang mit Dateien und Kommandozeile; Grundkenntnisse in Markdown und Git sind hilfreich, aber nicht zwingend