Seminar MkDocs – Eigene Plugins mit Python entwickeln

Plugins greifen in den MkDocs-Build ein und können Metadaten prüfen, Inhalte erzeugen, Navigation verändern oder Ausgaben ergänzen. Solche Erweiterungen benötigen eine klare Ereignisarchitektur, robuste Konfiguration, Tests und definierte Fehlergrenzen.

Inhaltsübersicht

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

Zielsetzung

Ein eigenes, paketierbares Plugin wird von der Anforderungsanalyse über Ereignishandler und Konfiguration bis zu automatisierten Tests und dokumentierter Einbindung entwickelt.

Zielgruppe

Python-Entwickler, Plattformteams und technische Architekten, die MkDocs gezielt erweitern oder interne Qualitätsregeln automatisieren möchten.

Voraussetzungen

Sichere Python-Kenntnisse, Grundkenntnisse in Paketierung und Tests sowie praktische Erfahrung mit MkDocs.

Seminarinhalte

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

Plugin-Architektur und Paketstruktur

1. Schritt 1: Erweiterungsbedarf gegen Konfiguration, Markdown-Erweiterung und Skript abgrenzen.
2. Schritt 2: Python-Paket, Plugin-Klasse und Entry Point korrekt anlegen.
3. Schritt 3: Ein- und Ausgaben sowie erlaubte Seiteneffekte dokumentieren.
4. Schritt 4: Eine kleine, testbare erste Plugin-Version planen.

Plugin-Konfiguration und Build-Ereignisse

1. Schritt 1: Optionen mit Typen, Pflichtwerten, Standardwerten und verständlichen Fehlern definieren.
2. Schritt 2: Lebenszyklus des Builds und Reihenfolge der Ereignisse nachvollziehen.
3. Schritt 3: Konfiguration, Dateien, Navigation, Markdown oder Seitenkontext gezielt verändern.
4. Schritt 4: Seiteneffekte zwischen Builds und Live-Reload vermeiden.

Plugin-Tests, Performance und Packaging

1. Schritt 1: Unit-Tests für reine Transformationslogik schreiben.
2. Schritt 2: Temporäre MkDocs-Projekte für Integrations- und Build-Tests erzeugen.
3. Schritt 3: Dateisystemzugriffe, Laufzeit und Eingaben defensiv behandeln.
4. Schritt 4: Versionen, Abhängigkeiten, Dokumentation und interne Verteilung vorbereiten.

Architektur für API- und Code-Referenzen

1. Schritt 1: Tutorials, Anleitungen, Konzepte und automatisch erzeugte Referenz klar trennen.
2. Schritt 2: Quellcode, handgeschriebene Texte und generierte Seiten im Repository ordnen.
3. Schritt 3: Öffentliche Schnittstellen als verständliches Navigationsmodell abbilden.
4. Schritt 4: Verantwortlichkeiten zwischen Entwicklung und Redaktion festlegen.

CI/CD-Stufenmodell

1. Schritt 1: Ereignisse für Prüfung, Vorschau, Freigabe und Veröffentlichung festlegen.
2. Schritt 2: Pipeline-Stufen nach Geschwindigkeit, Risiko und Abhängigkeit ordnen.
3. Schritt 3: Artefakte, Protokolle und Freigaben als überprüfbare Ergebnisse definieren.
4. Schritt 4: Abbruch-, Wiederanlauf- und Fehlerregeln vor der Implementierung festlegen.

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.

Lieferkette, Abhängigkeiten und Plugins

1. Schritt 1: Direkte und transitive Python-Abhängigkeiten vollständig inventarisieren.
2. Schritt 2: Versionen, Herkunft und unterstützte Bereiche festschreiben.
3. Schritt 3: Plugins als ausführbaren Code mit Berechtigungen und Seiteneffekten bewerten.
4. Schritt 4: Aktualisierungs- und Sicherheitsprüfung in den Lebenszyklus integrieren.

Governance und Pflegeprozess

1. Schritt 1: Eigentümerschaft, Review-Intervall und Freigabestufe pro Bereich festlegen.
2. Schritt 2: Verfallsdaten, Archivierung und Kennzeichnung veralteter Inhalte definieren.
3. Schritt 3: Änderungsprozesse zwischen Redaktion, Entwicklung und Betrieb koordinieren.
4. Schritt 4: Kennzahlen und regelmäßige Bestandsbereinigung etablieren.

Praxisübungen

• Eine fachliche Anforderung einem geeigneten Build-Ereignis zuordnen
• Ein konfigurierbares Plugin mit verständlichen Fehlermeldungen implementieren
• Unit-, Integrations- und Beispielprojekt-Tests in eine Pipeline integrieren

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.