Seminar Antora – Erweiterungen und Pipeline-Automatisierung

Beschreibung

Das Seminar vermittelt die Entwicklung, Integration und Absicherung von Antora-Erweiterungen. Ausgehend vom Generator-Lebenszyklus werden Ereignisse, Kontextobjekte, Inhalts- und Site-Kataloge, Konfigurationsschema, Logging, Tests, Paketierung und kontrollierte Veröffentlichung behandelt. Mehrere Erweiterungen werden schrittweise entwickelt: Validierung, Inhaltsanreicherung, UI-Modell-Erweiterung und nachgelagerte Artefaktverarbeitung.

Inhaltsübersicht

1. Erweiterungsarchitektur und Lebenszyklus
2. Generator Context und Dienstzugriff
3. Content Catalog und Ressourcenvalidierung
4. Inhaltsanreicherung und virtuelle Dateien
5. Site Catalog und UI-Modell
6. Konfiguration, Schema und sichere Standardwerte
7. Logging, Fehlerbehandlung und Beobachtbarkeit
8. Automatisierte Tests und Testfixtures
9. Paketierung, Versionierung und Lieferkette
10. CI-Integration und Betriebsübergabe

Lernziele

• Den Generator-Lebenszyklus und geeignete Erweiterungspunkte sicher einordnen.
• Antora-Kontextobjekte kontrolliert lesen und verändern.
• Erweiterungen konfigurierbar, testbar und fehlertolerant implementieren.
• Pakete versionieren, absichern und reproduzierbar in Build-Pipelines betreiben.

1. Erweiterungsarchitektur und Lebenszyklus

Antora-Erweiterungen reagieren auf definierte Ereignisse des Generators und arbeiten innerhalb klarer Lebenszyklusgrenzen.

Schritt-für-Schritt: Eine Erweiterung am richtigen Lebenszykluspunkt registrieren

1. Build-Phasen von der Playbook-Verarbeitung bis zur Site-Veröffentlichung als Ereignisfolge darstellen.
2. Für den vorgesehenen Anwendungsfall benötigte Eingaben, Ausgaben und Seiteneffekte bestimmen.
3. Eine Erweiterung als Node.js-Modul mit Registrierungsfunktion anlegen.
4. Ereignis-Listener für einen geeigneten Lebenszykluspunkt registrieren.
5. Die Erweiterung im Playbook aktivieren und einen kontrollierten Testbuild ausführen.
6. Aufrufreihenfolge und verfügbare Kontextdaten protokollieren und mit der Planung abgleichen.

Praxisaufgabe

Eine Diagnoseerweiterung zeichnet ausgewählte Lebenszyklusereignisse auf und erzeugt ein nachvollziehbares Ablaufprotokoll.

2. Generator Context und Dienstzugriff

Der Generator Context stellt kontrollierte Zugänge zu Katalogen, Konfiguration und Hilfsfunktionen bereit.

Schritt-für-Schritt: Kontextobjekte sicher inspizieren und verwenden

1. Benötigte Kontextdienste und deren Lebensdauer für den Anwendungsfall identifizieren.
2. Nur die tatsächlich benötigten Objekte aus dem Generator Context beziehen.
3. Lese- und Schreibzugriffe auf Inhaltsdaten ausdrücklich voneinander trennen.
4. Fehlende Dienste oder unerwartete Zustände mit verständlichen Diagnosen behandeln.
5. Seiteneffekte durch kleine Testfälle isolieren.
6. Zugriffsannahmen und kompatible Antora-Versionen in der Paketdokumentation festhalten.

Praxisaufgabe

Eine Erweiterung liest Build-Metadaten aus und erzeugt daraus einen strukturierten Diagnosebericht.

3. Content Catalog und Ressourcenvalidierung

Der Content Catalog enthält die klassifizierten Ressourcen aller Komponenten und Versionen.

Schritt-für-Schritt: Eine regelbasierte Inhaltsvalidierung implementieren

1. Zu prüfende Ressourcen nach Familie, Komponente, Version und Modul filtern.
2. Verbindliche Regeln für Namen, Attribute, Dateigröße oder Metadaten definieren.
3. Validierungsergebnisse mit Ressourcen-ID, Fundstelle und Handlungsempfehlung erfassen.
4. Fehler, Warnungen und Hinweise nach konfigurierbaren Schweregraden unterscheiden.
5. Den Build bei kritischen Verstößen kontrolliert abbrechen und bei Warnungen fortsetzen.
6. Tests mit gültigen, ungültigen und grenzwertigen Ressourcen ausführen.

Praxisaufgabe

Ein Validator prüft Dateinamen, Pflichtattribute und Größenbegrenzungen in mehreren Ressourcenfamilien.

4. Inhaltsanreicherung und virtuelle Dateien

Erweiterungen können Metadaten ergänzen oder virtuelle Ressourcen erzeugen, ohne Quell-Repositories zu verändern.

Schritt-für-Schritt: Virtuelle Inhalte deterministisch erzeugen

1. Eingabedaten und Zielidentität der virtuellen Ressource eindeutig festlegen.
2. Inhalte aus einer kontrollierten Vorlage und sortierten Quelldaten erzeugen.
3. Ressourcenmetadaten einschließlich Komponente, Version, Modul und Familie korrekt setzen.
4. Doppelte Identitäten und Konflikte mit physischen Quellen erkennen.
5. Die erzeugte Ressource dem Content Catalog hinzufügen und im Build verwenden.
6. Determinismus durch wiederholte Builds und Inhaltsvergleich nachweisen.

Praxisaufgabe

Aus Komponentenmetadaten wird eine virtuelle Übersichtsseite erzeugt und in die Navigation eingebunden.

5. Site Catalog und UI-Modell

Nach der Konvertierung können Erweiterungen Seitenmodelle und UI-relevante Daten für zusätzliche Darstellungselemente ergänzen.

Schritt-für-Schritt: Das UI-Modell kontrolliert erweitern

1. Benötigte Darstellungsdaten und ihre Quelle bestimmen.
2. Geeigneten Lebenszykluspunkt nach der Seitenkonvertierung auswählen.
3. Zielseiten anhand stabiler Metadaten statt fragiler Pfade identifizieren.
4. Zusätzliche Daten unter einem eindeutig benannten Modellbereich ablegen.
5. UI-Templates so anpassen, dass fehlende Erweiterungsdaten defensiv behandelt werden.
6. Darstellung mit mehreren Komponenten, Versionen und Seitentypen prüfen.

Praxisaufgabe

Seiten erhalten ein standardisiertes Metadatenpanel mit Version, Modul, Änderungsstatus und Content Owner.

6. Konfiguration, Schema und sichere Standardwerte

Produktionsfähige Erweiterungen benötigen nachvollziehbare Optionen, Validierung und sichere Voreinstellungen.

Schritt-für-Schritt: Eine konfigurierbare Erweiterung entwerfen

1. Pflichtoptionen, optionale Werte und Standardverhalten spezifizieren.
2. Konfiguration aus dem Playbook lesen und gegen Typen sowie Wertebereiche validieren.
3. Unbekannte Optionen erkennen und mit konkretem Korrekturhinweis melden.
4. Sicherheitskritische Funktionen standardmäßig deaktivieren oder einschränken.
5. Wirksame Konfiguration ohne Geheimnisse in der Diagnose ausgeben.
6. Mehrere Konfigurationsprofile durch automatisierte Tests abdecken.

Praxisaufgabe

Der Ressourcenvalidator erhält ein validiertes Regelprofil mit Schweregraden und Ausnahmelisten.

7. Logging, Fehlerbehandlung und Beobachtbarkeit

Erweiterungen müssen Fehler präzise melden, ohne Build-Protokolle zu überlasten oder sensible Daten offenzulegen.

Schritt-für-Schritt: Diagnosen und Fehlerpfade standardisieren

1. Meldungskategorien, Schweregrade und stabile Fehlercodes definieren.
2. Kontext wie Ressourcen-ID und Regelname ergänzen, sensible Werte jedoch auslassen.
3. Erwartete Validierungsfehler von Programmier- und Systemfehlern trennen.
4. Teilfehler nur dort tolerieren, wo das Ergebnis weiterhin fachlich korrekt bleibt.
5. Laufzeit und Ressourcennutzung für größere Inhaltsbestände messen.
6. Protokolle anhand vorbereiteter Fehlerfälle auf Verständlichkeit und Vollständigkeit prüfen.

Praxisaufgabe

Für eine fehlerhafte Erweiterung wird ein Diagnosekonzept umgesetzt und mit Positiv- und Negativfällen getestet.

8. Automatisierte Tests und Testfixtures

Tests sichern Erweiterungsverhalten gegen unterschiedliche Playbooks, Inhalte und Antora-Versionen ab.

Schritt-für-Schritt: Eine belastbare Testsuite aufbauen

1. Kernfunktionen in kleine, unabhängig testbare Einheiten zerlegen.
2. Minimale Test-Repositories und Playbooks als reproduzierbare Fixtures anlegen.
3. Erfolgs-, Warn-, Fehler- und Grenzfälle als automatisierte Tests formulieren.
4. Build-Ausgaben, Protokolle und erzeugte Dateien mit stabilen Erwartungen vergleichen.
5. Tests gegen unterstützte Node.js- und Antora-Versionen in einer Matrix ausführen.
6. Fehlgeschlagene Tests mit aufbewahrten Artefakten und Diagnoseprotokollen auswertbar machen.

Praxisaufgabe

Eine vollständige Testmatrix für Validator, virtuelle Seite und UI-Modellerweiterung wird implementiert.

9. Paketierung, Versionierung und Lieferkette

Eine Erweiterung wird erst durch kontrollierte Paketierung und nachvollziehbare Abhängigkeiten betriebssicher.

Schritt-für-Schritt: Ein Erweiterungspaket veröffentlichungsfähig machen

1. Paketname, Exporte, unterstützte Laufzeiten und Peer-Abhängigkeiten festlegen.
2. Nicht benötigte Dateien aus dem Paket ausschließen und Paketinhalt vorab prüfen.
3. Abhängigkeiten sperren, Schwachstellenprüfung integrieren und Lizenzanforderungen dokumentieren.
4. Semantische Versionierung und Änderungsprotokoll für kompatible sowie inkompatible Änderungen definieren.
5. Ein lokales Paketartefakt erzeugen und in einer sauberen Testumgebung installieren.
6. Freigabe, Signierung oder Provenienz sowie Rücknahme eines fehlerhaften Pakets planen.

Praxisaufgabe

Die Seminarerweiterung wird als versioniertes Paket gebaut und in einem isolierten Beispielprojekt verifiziert.

10. CI-Integration und Betriebsübergabe

Die Erweiterung wird abschließend als überwachte Komponente der Dokumentationspipeline betrieben.

Schritt-für-Schritt: Eine Erweiterung kontrolliert in Produktion überführen

1. Installations- und Konfigurationsschritte in der CI-Pipeline reproduzierbar abbilden.
2. Tests, Paketprüfung und Beispielbuild als verpflichtende Qualitätsgates einrichten.
3. Rollout zunächst in einer Vorschau- oder Staging-Site ausführen.
4. Abnahmekriterien für Funktion, Laufzeit, Protokollierung und Fehlerverhalten prüfen.
5. Rollback auf die vorherige Paketversion vorbereiten und testen.
6. Betriebshandbuch mit Eigentum, Monitoring, Update- und Incident-Prozess freigeben.

Praxisaufgabe

Als Abschluss wird eine Erweiterung über eine gestufte Pipeline ausgerollt und kontrolliert zurückgesetzt.

Zielgruppe und Voraussetzungen

Zielgruppe: JavaScript- und Node.js-Entwickler, Documentation Engineers, Plattform- und DevOps-Teams, Tooling-Verantwortung und technische Architektur.

Voraussetzungen: Gute JavaScript- oder Node.js-Kenntnisse, sicherer Umgang mit npm, Git und Antora-Playbooks sowie Verständnis der Antora-Inhaltsstruktur.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.