Seminar MkDocs – Konfiguration, Navigation und Projektstruktur

Die zentrale Konfiguration entscheidet darüber, ob ein MkDocs-Projekt übersichtlich, reproduzierbar und erweiterbar bleibt. Das Seminar behandelt YAML-Struktur, Verzeichnisse, Navigationsmodelle, Konfigurationsvarianten und systematische Fehlerdiagnose.

Inhaltsübersicht

• Zielsetzung
• Zielgruppe
• Voraussetzungen
• Seminarinhalte
• Praxisübungen
• Methodik

Zielsetzung

Ein gewachsenes Beispielprojekt wird in eine klare Projektstruktur überführt. Konfiguration und Navigation werden schrittweise bereinigt, modularisiert, für mehrere Umgebungen vorbereitet und mit Prüfbauten abgesichert.

Zielgruppe

Administratoren, technische Redakteure, Entwickler und Projektverantwortliche, die bestehende MkDocs-Projekte aufbauen oder konsolidieren.

Voraussetzungen

Grundkenntnisse in MkDocs und Markdown; elementare YAML- und Kommandozeilenkenntnisse sind hilfreich.

Seminarinhalte

Die Themen werden in einer festen Arbeitsfolge aus Analyse, Einrichtung, Umsetzung und Prüfung bearbeitet.

Zentrale MkDocs-Konfiguration

1. Schritt 1: YAML-Struktur, Einrückung, Datentypen und mehrzeilige Werte sicher beherrschen.
2. Schritt 2: Site-Angaben, Verzeichnisse, Theme, Plugins und Erweiterungen nachvollziehbar ordnen.
3. Schritt 3: Konfigurationsvarianten für Entwicklung, Test und Produktion kontrolliert trennen.
4. Schritt 4: Fehler mit minimaler Konfiguration und Vergleichsbuilds systematisch eingrenzen.

Projektstruktur und erster Build

1. Schritt 1: Projektgerüst mit Konfiguration, Inhaltsverzeichnis und Ausgabeordner anlegen.
2. Schritt 2: Quellen, Konfiguration, Assets und generierte Ausgabe sauber trennen.
3. Schritt 3: Lokalen Entwicklungsserver starten und Änderungen unmittelbar prüfen.
4. Schritt 4: Produktionsbuild ausführen und Warnungen geordnet auswerten.

Navigation und Benutzerführung

1. Schritt 1: Nutzeraufgaben, Einstiegspunkte und erwartete Informationswege erfassen.
2. Schritt 2: Explizite Navigation mit sinnvoller Tiefe, Gruppierung und Reihenfolge aufbauen.
3. Schritt 3: Seitennavigation, Inhaltsverzeichnis, Tabs und Abschnittsübersichten abstimmen.
4. Schritt 4: Navigation anhand realer Such- und Arbeitsaufgaben überprüfen.

Große Portale und modulare Quellen

1. Schritt 1: Repository-Grenzen, Verzeichnisse und Eigentümerschaft für mehrere Teams festlegen.
2. Schritt 2: Gemeinsame Inhalte, Produktvarianten und Medien kontrolliert voneinander trennen.
3. Schritt 3: Navigation und Konfiguration für große Bestände wartbar modularisieren.
4. Schritt 4: Pilotmigration und schrittweisen Umbau mit stabilen Pfaden planen.

Systematische Fehleranalyse

1. Schritt 1: Warnungen, Fehler und Folgefehler nach Entstehungsphase unterscheiden.
2. Schritt 2: Konfiguration, Inhalt, Plugin, Theme und Umgebung nacheinander isolieren.
3. Schritt 3: Minimale Reproduktionsprojekte für komplexe Fehler erstellen.
4. Schritt 4: Korrekturen gegen Referenzbuild und Regressionstests absichern.

Qualitätsmodell und Prüfstrategie

1. Schritt 1: Inhaltliche, strukturelle, technische, visuelle und betriebliche Fehler unterscheiden.
2. Schritt 2: Fehler nach Auswirkung, Erkennbarkeit und Korrekturaufwand priorisieren.
3. Schritt 3: Lokale Prüfung, Review-Gate und vollständige Pipeline-Prüfung trennen.
4. Schritt 4: Akzeptanzkriterien und zeitlich begrenzte Ausnahmen dokumentieren.

Praxisübungen

• Eine unübersichtliche Konfiguration analysieren und neu ordnen
• Navigation und Verzeichnisstruktur für mehrere Inhaltsbereiche aufbauen
• Entwicklungs- und Produktionsvarianten mit Vergleichsbuilds prüfen

Methodik

Fachliche Einführung, nachvollziehbare Demonstration, angeleitete Umsetzung, selbstständige Übungsphasen, strukturierte Fehleranalyse und gemeinsame Qualitätskontrolle wechseln einander ab. Alle Arbeitsschritte werden an einem zusammenhängenden Beispielprojekt durchgeführt.