Seminar Antora – Grundlagen, Installation und erste Dokumentationssite

Beschreibung

Das Seminar führt praxisorientiert in Antora ein. Von der lokalen Node.js-Umgebung über Komponenten- und Modulstruktur, AsciiDoc-Seiten, Playbook, Navigation und UI bis zum reproduzierbaren Build entsteht eine vollständige erste Dokumentationssite. Fehlerbilder werden bewusst eingebaut und mit einem systematischen Diagnoseablauf behoben.

Inhaltsübersicht

1. Systemüberblick und Arbeitsumgebung
2. Erstes Content-Repository
3. Playbook und Inhaltsquelle
4. Navigation und Querverweise
5. Komponenten, Versionen und weitere Module
6. Build, Ausgabe und lokale Vorschau
7. Grundlegende Fehlerdiagnose

Lernziele

• Eine geeignete lokale Antora-Umgebung installieren und verifizieren.
• Komponenten, Module und AsciiDoc-Seiten regelkonform strukturieren.
• Ein Playbook mit Inhaltsquellen, UI und Ausgabeziel konfigurieren.
• Build-Ergebnisse prüfen und grundlegende Fehler systematisch beheben.

1. Systemüberblick und Arbeitsumgebung

Zu Beginn wird die Antora-Pipeline eingeordnet und eine reproduzierbare lokale Arbeitsumgebung vorbereitet.

Schritt-für-Schritt: Die Seminarumgebung installieren und prüfen

1. Verzeichnisstruktur für Playbook-Projekt, Inhaltsquelle und Build-Ausgabe anlegen.
2. Unterstützte Node.js- und Paketmanager-Version in der Arbeitsumgebung prüfen.
3. Antora und das benötigte Site-Generator-Paket projektbezogen installieren.
4. Installierte Versionen und ausführbare Befehle kontrollieren.
5. Ein minimales Versionsprotokoll für spätere Reproduzierbarkeit erstellen.
6. Fehlende Rechte, Proxy- oder Paketauflösungsprobleme mit einer Diagnosecheckliste beheben.

Praxisaufgabe

Eine saubere Projektumgebung wird installiert und mit einem dokumentierten Versionscheck abgenommen.

2. Erstes Content-Repository

Eine Antora-Inhaltsquelle erhält einen Komponenten-Deskriptor und mindestens ein Modul mit Seiten.

Schritt-für-Schritt: Eine gültige Inhaltsquelle aufbauen

1. Ein Git-Repository initialisieren und eine nachvollziehbare Startstruktur anlegen.
2. Eine antora.yml mit Komponentenname, Anzeigename, Version und Navigation erstellen.
3. Unter modules/ROOT/pages eine Startseite und eine zweite Inhaltsseite anlegen.
4. Dokumenttitel, Abschnittsstruktur und grundlegende AsciiDoc-Elemente ergänzen.
5. Änderungen mit einem aussagekräftigen Commit sichern.
6. Die Struktur gegen eine Checkliste für Deskriptor, Modul und Seitenfamilie prüfen.

Praxisaufgabe

Ein kleines Produkt-Handbuch wird als eigenständige Antora-Komponente angelegt.

3. Playbook und Inhaltsquelle

Das Playbook beschreibt Site, Quellen, UI, Ausgabe und Laufzeitoptionen.

Schritt-für-Schritt: Ein minimales Playbook konfigurieren

1. Ein separates Playbook-Projekt mit YAML-Datei anlegen.
2. Site-Titel, Startseite und Ausgabeziel definieren.
3. Das lokale Content-Repository mit passender Referenz als Quelle eintragen.
4. Den Default UI-Bundle als UI-Quelle konfigurieren.
5. Den ersten Build ausführen und Exit-Code sowie Protokoll prüfen.
6. Ausgabeverzeichnis öffnen und die erzeugte Startseite kontrollieren.

Praxisaufgabe

Die zuvor erstellte Komponente wird zu einer lokal aufrufbaren statischen Site gebaut.

4. Navigation und Querverweise

Navigation und Ressourcen-IDs verbinden einzelne Seiten zu einem nutzbaren Informationsraum.

Schritt-für-Schritt: Navigation und erste Xrefs implementieren

1. Eine nav.adoc im Modul anlegen und im Komponenten-Deskriptor registrieren.
2. Start- und Folgeseite in einer sinnvollen Reihenfolge eintragen.
3. Zwischen den Seiten einen lokalen Querverweis mit xref erstellen.
4. Ein Bild oder Beispiel als zusätzliche Ressourcenfamilie ergänzen.
5. Den Build erneut ausführen und Navigation sowie Linkziel prüfen.
6. Eine absichtlich fehlerhafte Referenz anhand der Build-Meldung korrigieren.

Praxisaufgabe

Die Beispielsite erhält eine funktionsfähige Navigation, Querverweise und eine eingebundene Ressource.

5. Komponenten, Versionen und weitere Module

Die Basissite wird um eine zweite Version oder ein zusätzliches Modul erweitert.

Schritt-für-Schritt: Die Inhaltsarchitektur kontrolliert ausbauen

1. Einen fachlich abgegrenzten zweiten Modulbereich planen.
2. Modulverzeichnis, Seiten und eigene Navigationsdatei anlegen.
3. Navigationsdateien in der gewünschten Reihenfolge registrieren.
4. Optional eine zweite Git-Referenz mit abweichender Komponenten-Version vorbereiten.
5. Beide Strukturen bauen und Komponenten- sowie Versionsauswahl prüfen.
6. Namens- und Strukturregeln für weitere Inhalte dokumentieren.

Praxisaufgabe

Eine Administrationsdokumentation wird als zusätzliches Modul integriert und in der Navigation getrennt dargestellt.

6. Build, Ausgabe und lokale Vorschau

Ein reproduzierbarer Build benötigt klare Befehle, bereinigte Ausgaben und verlässliche Prüfpunkte.

Schritt-für-Schritt: Einen wiederholbaren Buildablauf etablieren

1. Projektbezogene Build-Skripte im Paketmanifest definieren.
2. Vor dem Build ein kontrolliertes Bereinigen des Ausgabeverzeichnisses einrichten.
3. Laufzeitoptionen und Umgebungswerte dokumentiert übergeben.
4. Die Site mit einem lokalen statischen Server bereitstellen.
5. Stichproben für Startseite, Navigation, Assets und Versionsanzeige durchführen.
6. Build-Befehl, Voraussetzungen und Prüfschritte in einer README festhalten.

Praxisaufgabe

Ein zweiter Teilnehmer kann die Site ausschließlich anhand der dokumentierten Schritte reproduzieren.

7. Grundlegende Fehlerdiagnose

Typische Einstiegsfehler werden anhand eines festen Diagnosepfads statt durch Versuch und Irrtum behoben.

Schritt-für-Schritt: Build- und Strukturfehler systematisch analysieren

1. Fehler zunächst nach Installation, YAML, Quelle, Inhaltsstruktur, Referenz oder UI klassifizieren.
2. Exit-Code und erste ursächliche Meldung im Protokoll identifizieren.
3. Playbook und Komponenten-Deskriptor auf Einrückung, Schlüssel und Pfade prüfen.
4. Git-Referenz, Startpfad und vorhandene Dateien gegen die Konfiguration abgleichen.
5. Nach jeder Korrektur einen sauberen Build durchführen und nur eine Variable verändern.
6. Ursache, Korrektur und Präventionsregel in einem Fehlerjournal dokumentieren.

Praxisaufgabe

Mehrere vorbereitete Installations-, YAML-, Quellen- und Xref-Fehler werden in vorgegebener Reihenfolge behoben.

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redakteure, Entwickler, DevOps- und Plattformteams, IT-Administratoren sowie Projektverantwortung für neue Dokumentationsplattformen.

Voraussetzungen: Grundkenntnisse im Umgang mit Kommandozeile, Git und Textdateien; Programmierkenntnisse sind nicht erforderlich.

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.