Seminar MkDocs – Grundlagen, Installation und Projektstart

Ein sauberer Projektstart verhindert spätere Struktur- und Build-Probleme. Das Seminar führt von der reproduzierbaren Installation über Projektstruktur und Markdown bis zur ersten Material-for-MkDocs-Site und einem kontrollierten Produktionsbuild.

Inhaltsübersicht

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

Zielsetzung

Ein vollständiges Einstiegsprojekt wird schrittweise angelegt, lokal bearbeitet, konfiguriert, geprüft und als statische Ausgabe erzeugt. Dabei werden die grundlegenden Arbeitsabläufe so eingeübt, dass eine Wiederholung im eigenen Umfeld möglich ist.

Zielgruppe

Technische Redakteure, Entwickler, Administratoren, Trainer und Projektverantwortliche ohne oder mit geringer MkDocs-Erfahrung.

Voraussetzungen

Sicherer Umgang mit Dateien und Verzeichnissen; grundlegende Kommandozeilenkenntnisse sind hilfreich.

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.

Praxisübungen

• Eine isolierte, reproduzierbare Arbeitsumgebung aufbauen
• Ein mehrseitiges Projekt mit Navigation, Medien und Codebeispielen erstellen
• Lokalen Server und Produktionsbuild ausführen sowie Warnungen beheben

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.