Seminar Antora – Playbook, Site-Konfiguration und lokale Builds

Beschreibung

Das Seminar behandelt das Antora-Playbook als zentrale, versionierbare Steuerung einer Dokumentationssite. Site-Metadaten, Inhaltsquellen, Startpfade, AsciiDoc-Attribute, UI, Ausgabe, Laufzeitoptionen, Umgebungsprofile, lokale Vorschau und Diagnostik werden strukturiert konfiguriert. Mehrere Playbook-Varianten werden ohne unkontrollierte Duplizierung aufgebaut und reproduzierbar getestet.

Inhaltsübersicht

1. Playbook-Struktur und Konfigurationsprinzipien
2. Site-Metadaten, Startseite und Ausgabe
3. Inhaltsquellen, Referenzen und Startpfade
4. AsciiDoc-Attribute und Inhaltssteuerung
5. UI, Runtime und Erweiterungen
6. Umgebungsprofile und Diagnose

Lernziele

• Playbook-Bereiche und ihre Auswirkungen auf den Build sicher unterscheiden.
• Mehrere Inhaltsquellen, Referenzen und Startpfade präzise konfigurieren.
• AsciiDoc-, UI-, Ausgabe- und Laufzeitoptionen reproduzierbar steuern.
• Umgebungsvarianten und lokale Builds mit einem festen Diagnoseprozess absichern.

1. Playbook-Struktur und Konfigurationsprinzipien

Das Playbook wird als versionierter Buildvertrag zwischen Inhalt, UI, Laufzeit und Veröffentlichung verstanden.

Schritt-für-Schritt: Ein übersichtliches Basis-Playbook aufbauen

1. Site-, Content-, AsciiDoc-, UI-, Output- und Runtime-Bereiche im Playbook voneinander abgrenzen.
2. Verbindliche und optionale Werte für das Projekt identifizieren.
3. Schlüssel in einer stabilen Reihenfolge anordnen und projektspezifische Kommentare sparsam ergänzen.
4. Pfade relativ zum Playbook-Projekt nachvollziehbar definieren.
5. Geheimnisse und rein umgebungsspezifische Werte aus dem versionierten Basis-Playbook ausschließen.
6. Das YAML mit einem Parser prüfen und einen Minimalbuild als Baseline ausführen.

Praxisaufgabe

Ein unübersichtliches Playbook wird in eine klare, kommentierte und lauffähige Basiskonfiguration überführt.

2. Site-Metadaten, Startseite und Ausgabe

Site-Identität und Ausgabeverhalten müssen für alle Umgebungen eindeutig sein.

Schritt-für-Schritt: Site- und Ausgabeparameter kontrolliert festlegen

1. Site-Titel, URL-Kontext und Startseite anhand des Veröffentlichungsmodells bestimmen.
2. Startseite als stabile Antora-Ressource auswählen und auf Verfügbarkeit prüfen.
3. Ausgabeverzeichnis außerhalb der Quellverzeichnisse definieren.
4. Bereinigung und Überschreibverhalten für lokale Builds festlegen.
5. Erzeugte Site auf Basis-URL, Startpfad und relative Asset-Verweise kontrollieren.
6. Abweichende Werte für Vorschau und Produktion dokumentieren.

Praxisaufgabe

Eine Site wird einmal unter einem Wurzelpfad und einmal unter einem Unterpfad gebaut und verglichen.

3. Inhaltsquellen, Referenzen und Startpfade

Der Content-Bereich steuert präzise, welche Git-Stände und Unterverzeichnisse in den Build gelangen.

Schritt-für-Schritt: Komplexe Quellenkonfiguration erstellen

1. Repository, Branches, Tags und Startpfade in einer Quellenmatrix vorbereiten.
2. Eine erste lokale oder entfernte Quelle mit expliziter Referenz konfigurieren.
3. Weitere Quellen nach gemeinsamen und abweichenden Parametern gruppieren.
4. Referenzmuster so einschränken, dass keine unbeabsichtigten Versionen aggregiert werden.
5. Startpfade auf vorhandene Komponenten-Deskriptoren und Überschneidungen prüfen.
6. Build-Protokoll und Komponentenliste mit der Quellenmatrix abgleichen.

Praxisaufgabe

Drei Repositories mit unterschiedlichen Branch- und Startpfadmodellen werden in einem Playbook zusammengeführt.

4. AsciiDoc-Attribute und Inhaltssteuerung

Globale Attribute können Inhalte vereinheitlichen, erzeugen aber bei unkontrollierter Nutzung versteckte Kopplungen.

Schritt-für-Schritt: Attribute nachvollziehbar und sicher konfigurieren

1. Globale, komponentenspezifische und seitenbezogene Attribute unterscheiden.
2. Nur stabile, siteweite Angaben in den AsciiDoc-Bereich des Playbooks aufnehmen.
3. Sperr- und Überschreibverhalten für kritische Attribute festlegen.
4. Umgebungsspezifische Werte mit eindeutiger Benennung und dokumentiertem Ursprung bereitstellen.
5. Bedingte Inhalte in mehreren Profilen bauen und auf unbeabsichtigte Unterschiede prüfen.
6. Eine Attributmatrix mit Wert, Geltungsbereich, Eigentümer und Testfall dokumentieren.

Praxisaufgabe

Produktname, Supportkanal und Umgebungskennzeichnung werden über kontrollierte Attribute gesteuert.

5. UI, Runtime und Erweiterungen

UI-Bundle, Cache, Logging und Erweiterungen werden als explizite Build-Abhängigkeiten konfiguriert.

Schritt-für-Schritt: Laufzeitkomponenten reproduzierbar anbinden

1. UI-Bundle über eine feste, nachvollziehbare Quelle und Version referenzieren.
2. Lokale UI-Entwicklung von produktiven Bundle-Quellen trennen.
3. Runtime-Cache und temporäre Verzeichnisse für lokale sowie automatisierte Builds planen.
4. Log-Level und Diagnosedaten an Entwicklungs- und Produktionsbedarf anpassen.
5. Erweiterungen mit eindeutiger Reihenfolge und validierten Optionen registrieren.
6. Build mit und ohne optionale Erweiterung vergleichen und Abhängigkeiten dokumentieren.

Praxisaufgabe

Ein versioniertes UI-Bundle und eine konfigurierbare Validierungserweiterung werden in das Playbook integriert.

6. Umgebungsprofile und Diagnose

Entwicklung, Staging und Produktion sollen dieselbe Basis verwenden, aber kontrollierte Unterschiede zulassen.

Schritt-für-Schritt: Mehrere Build-Profile ohne Konfigurationsdrift betreiben

1. Gemeinsame Basis und erlaubte Unterschiede zwischen den Umgebungen festlegen.
2. Profile über getrennte, kleine Playbooks oder klar dokumentierte Laufzeitwerte abbilden.
3. Wirksame Konfiguration vor jedem Build nachvollziehbar ausgeben.
4. Alle Profile aus einer sauberen Arbeitskopie automatisiert bauen.
5. Fehler nach YAML, Quelle, Attribut, UI, Erweiterung oder Ausgabe klassifizieren.
6. Konfigurationsänderungen über Review, Testmatrix und Freigabe absichern.

Praxisaufgabe

Lokales, Staging- und Produktionsprofil werden gebaut und auf unbeabsichtigte Abweichungen verglichen.

Zielgruppe und Voraussetzungen

Zielgruppe: Documentation Engineers, Plattform- und DevOps-Teams, technische Redakteure mit Build-Verantwortung, Git-Administratoren und technische Projektleitung.

Voraussetzungen: Grundkenntnisse in Antora, YAML, Git und Kommandozeile; eine kleine Antora-Inhaltsquelle sollte bekannt sein.

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.