Seminar MkDocs – Kompaktseminar mit Material for MkDocs

Das Kompaktseminar vermittelt den praxistauglichen Kern für Aufbau und Veröffentlichung eines professionellen Dokumentationsportals. Installation, Markdown, Konfiguration, Navigation, Material-Komponenten, Git-Arbeit, Qualitätsprüfung und ein einfacher automatisierter Build werden ohne unnötige Spezialthemen verbunden.

Inhaltsübersicht

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

Zielsetzung

Innerhalb von drei Tagen entsteht ein vollständiges kleines Portal mit klarer Struktur, konsistenter Gestaltung, nachvollziehbarer Versionsverwaltung und reproduzierbarem Build.

Zielgruppe

Technische Redaktionen, Entwickler, Administratoren, Trainer und Projektteams, die in kurzer Zeit einen belastbaren Gesamtstart benötigen.

Voraussetzungen

Allgemeine IT-Kenntnisse und sicherer Umgang mit Dateien; Markdown-, Git- oder Kommandozeilenerfahrung ist hilfreich, aber nicht zwingend.

Seminarinhalte

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

Arbeitsumgebung und reproduzierbare Installation

1. Schritt 1: Geeignete Python-Version prüfen und eine isolierte Umgebung anlegen.
2. Schritt 2: MkDocs, Theme und Erweiterungen mit festgeschriebenen Versionen installieren.
3. Schritt 3: Installierte Komponenten und ausführbare Befehle kontrollieren.
4. Schritt 4: Abhängigkeiten für einen reproduzierbaren Neuaufbau dokumentieren.

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.

Technisches Markdown und Seitentypen

1. Schritt 1: Überschriften, Listen, Links, Bilder, Tabellen und Code semantisch korrekt einsetzen.
2. Schritt 2: Anleitungen mit Voraussetzungen, nummerierten Schritten und Prüfergebnis strukturieren.
3. Schritt 3: Konzepte, Referenzen, Tutorials und Fehlerbehebungen klar unterscheiden.
4. Schritt 4: Interne Verweise und Medienpfade relativ, stabil und wartbar aufbauen.

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.

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.

Material for MkDocs einrichten

1. Schritt 1: Theme aktivieren und Sprache, Farbschema, Logo sowie Grundfunktionen konfigurieren.
2. Schritt 2: Suche, Navigationsmerkmale und geeignete Markdown-Erweiterungen einschalten.
3. Schritt 3: Darstellung auf Desktop, Tablet, Mobilgerät und in Druckansichten prüfen.
4. Schritt 4: Konfigurationsentscheidungen in einer wartbaren Theme-Baseline festhalten.

Erweiterte Inhaltskomponenten

1. Schritt 1: Hinweise, Details, Tabs, Grids und Annotationen nach fachlichem Zweck auswählen.
2. Schritt 2: Codeblöcke mit Sprache, Markierung, Zeilennummern und erklärenden Anmerkungen gestalten.
3. Schritt 3: Tabellen, Aufgabenlisten, Definitionen und Fußnoten konsistent einsetzen.
4. Schritt 4: Komponentenregeln gegen Überladung und uneinheitliche Verwendung formulieren.

Repository-Struktur und Git-Grundablauf

1. Schritt 1: Dokumentationsquellen, Konfiguration, Assets und Hilfsskripte sinnvoll ordnen.
2. Schritt 2: Kleine, thematisch geschlossene Änderungen erstellen und prüfen.
3. Schritt 3: Aussagekräftige Commits mit fachlichem Bezug formulieren.
4. Schritt 4: Generierte Ausgabe und sensible lokale Dateien aus dem Repository fernhalten.

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.

Build-Artefakte und Vorschauumgebungen

1. Schritt 1: Statische Ausgabe als unveränderliches, versioniertes Artefakt behandeln.
2. Schritt 2: Quellrevision, Build-Zeitpunkt und Abhängigkeitsstand nachweisbar einbetten.
3. Schritt 3: Isolierte Vorschauen für Reviews mit eindeutiger Lebensdauer bereitstellen.
4. Schritt 4: Artefakte zwischen Pipeline-Stufen weitergeben statt erneut zu bauen.

Praxisübungen

• Ein vollständiges Portalgerüst mit Material for MkDocs aufbauen
• Mehrere Seitentypen mit Navigation, Medien und Komponenten erstellen
• Änderung versionieren, prüfen und als reproduzierbares Artefakt ausgeben

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.