Seminar Antora – Asciidoctor-Erweiterungen und benutzerdefinierte Makros

Beschreibung

Das Seminar zeigt, wie Asciidoctor.js-Erweiterungen innerhalb einer Antora-Pipeline entworfen, implementiert und abgesichert werden. Der Schwerpunkt liegt auf Block- und Inline-Makros, Preprocessoren, Tree Processors, Postprocessoren, Attributverarbeitung, Registrierung, Tests und kontrollierter Paketierung. Jede Erweiterung wird mit Eingabegrenzen, Fehlermeldungen und automatisierten Prüfungen entwickelt.

Inhaltsübersicht

1. Erweiterungsmodell und Auswahl des Erweiterungspunkts
2. Projektaufbau und Registrierungsmechanik
3. Inline- und Block-Makros
4. Preprocessor und Tree Processor
5. Postprocessor und Ausgabegrenzen
6. Konfiguration und Antora-Integration
7. Tests, Paketierung und Sicherheitsprüfung

Lernziele

• Geeignete Asciidoctor-Erweiterungspunkte für fachliche Anforderungen auswählen.
• Block- und Inline-Makros sowie Prozessoren in JavaScript implementieren.
• Erweiterungen in Antora registrieren und konfigurierbar gestalten.
• Automatisierte Tests, Fehlerbehandlung und Sicherheitskontrollen aufbauen.

1. Erweiterungsmodell und Auswahl des Erweiterungspunkts

Vor der Implementierung wird entschieden, ob eine Anforderung durch Syntaxkonvention, UI-Helfer, Antora-Erweiterung oder Asciidoctor-Erweiterung gelöst werden sollte.

Schritt-für-Schritt: Eine Erweiterungsanforderung klassifizieren

1. Gewünschte Autorensyntax, Eingabedaten, Ausgabe und Fehlerverhalten schriftlich definieren.
2. Prüfen, ob Standard-AsciiDoc, Attribute oder Includes die Anforderung bereits ausreichend abdecken.
3. Block Macro, Inline Macro, Block Processor, Preprocessor, Tree Processor oder Postprocessor nach Eingriffszeitpunkt vergleichen.
4. Seiteneffekte auf Quelltext, Dokumentbaum, HTML und andere Ausgabeformate bewerten.
5. Eine minimale Schnittstelle und klare Nichtziele als technische Spezifikation festhalten.

Praxisaufgabe

Mehrere Beispielanforderungen werden dem jeweils kleinsten geeigneten Erweiterungspunkt zugeordnet.

2. Projektaufbau und Registrierungsmechanik

Eine reproduzierbare Node.js-Projektstruktur trennt Implementierung, Registrierung, Konfiguration, Tests und Beispieldokumente.

Schritt-für-Schritt: Ein Erweiterungsprojekt initialisieren

1. Paketverzeichnis mit eindeutiger Modulstruktur, Metadaten und unterstützter Laufzeit anlegen.
2. Registrierungsfunktion exportieren und den Asciidoctor Extension Registry-Kontext korrekt verwenden.
3. Eine minimale Erweiterung implementieren, die eine kontrollierte Testausgabe erzeugt.
4. Das Paket im Antora-Playbook verfügbar machen und beim Build laden.
5. Registrierung und Deaktivierung über einen Test-Build nachvollziehbar prüfen.

Praxisaufgabe

Ein lauffähiges Erweiterungsgerüst wird erstellt und in einer lokalen Antora-Site aktiviert.

3. Inline- und Block-Makros

Makros bilden fachliche Kurzsyntax auf kontrollierte Ausgabestrukturen ab und müssen ungültige Eingaben eindeutig zurückweisen.

Schritt-für-Schritt: Ein benutzerdefiniertes Makro implementieren

1. Makroname, Zielsyntax und zulässige Attribute definieren.
2. Eingabewerte normalisieren und Pflichtangaben vor der Verarbeitung validieren.
3. Geeignete Asciidoctor-Knoten erzeugen, statt unkontrolliertes HTML zusammenzusetzen.
4. Sonderzeichen, leere Werte und nicht erlaubte Pfade mit klaren Diagnosemeldungen behandeln.
5. Positiv-, Grenz- und Negativfälle in Beispieldokumenten ausführen.
6. Ausgabe in Antora-Kontext, Navigation und alternativen Backends auf Nebenwirkungen prüfen.

Praxisaufgabe

Ein Makro für standardisierte technische Kennzeichnungen wird mit Attributen, Validierung und Fallback-Ausgabe entwickelt.

4. Preprocessor und Tree Processor

Prozessoren vor und nach dem Parsing eignen sich für kontrollierte Quellergänzungen und strukturelle Dokumentprüfungen.

Schritt-für-Schritt: Eine strukturelle Verarbeitung umsetzen

1. Verarbeitungszeitpunkt und benötigte Daten des Prozessors festlegen.
2. Beim Preprocessing nur klar begrenzte, deterministische Quelltransformationen durchführen.
3. Im Dokumentbaum gezielt nach Knotenarten, Rollen oder Attributen suchen.
4. Befunde als Warnung oder Fehler mit Seite und Kontext protokollieren.
5. Änderungen am Baum so ausführen, dass IDs, Verweise und Backend-Verarbeitung stabil bleiben.
6. Mehrfachausführung und parallele Builds auf idempotentes Verhalten testen.

Praxisaufgabe

Ein Tree Processor prüft verpflichtende Metadaten und erzeugt präzise Meldungen für unvollständige Seiten.

5. Postprocessor und Ausgabegrenzen

Nachgelagerte Transformationen sind nur dann geeignet, wenn die gewünschte Änderung nicht semantisch im Dokumentbaum abgebildet werden kann.

Schritt-für-Schritt: Eine Ausgabeanpassung sicher begrenzen

1. Gewünschte Ausgabeveränderung und unterstützte Backends festlegen.
2. Prüfen, ob eine UI-Template-Anpassung die wartbarere Lösung darstellt.
3. Transformation auf eindeutig erkennbare Strukturen beschränken.
4. Kodierung, escaping und potenzielle Skriptinjektion explizit behandeln.
5. Ausgabe mit realistischen Sonderfällen und großen Dokumenten vergleichen.
6. Bei nicht unterstütztem Backend eine kontrollierte, dokumentierte Reaktion implementieren.

Praxisaufgabe

Eine Ausgabeergänzung wird implementiert und gegen fehlerhafte Markup-Erzeugung abgesichert.

6. Konfiguration und Antora-Integration

Erweiterungen müssen ohne Quellcodeänderung konfigurierbar sein und ihren Kontext aus klar definierten Einstellungen beziehen.

Schritt-für-Schritt: Konfiguration in die Pipeline integrieren

1. Konfigurationsschlüssel, Standardwerte und zulässige Datentypen festlegen.
2. Einstellungen aus der Antora-Konfiguration oder aus dokumentierten Attributen einlesen.
3. Konfiguration früh validieren und widersprüchliche Werte mit konkreter Meldung ablehnen.
4. Logger und Build-Kontext verwenden, ohne globale Zustände zu erzeugen.
5. Mehrere Playbook-Varianten mit unterschiedlichen Einstellungen testen.
6. Abwärtskompatible Änderungen und Deprecation-Regeln für spätere Versionen definieren.

Praxisaufgabe

Das Praxisprojekt erhält konfigurierbare Regeln und wird in Entwicklungs- und Produktionsprofilen ausgeführt.

7. Tests, Paketierung und Sicherheitsprüfung

Der Abschluss verbindet Unit-Tests, Build-Tests, Versionsregeln und Sicherheitskontrollen zu einem freigabefähigen Paket.

Schritt-für-Schritt: Eine Erweiterung produktionsreif absichern

1. Kernlogik als isoliert testbare Funktionen strukturieren.
2. Fixture-Dokumente für gültige, ungültige und mehrdeutige Eingaben anlegen.
3. Vollständige Antora-Builds als Integrationstest automatisieren und Ausgaben vergleichen.
4. Dateizugriffe, externe Prozesse, Umgebungsvariablen und dynamische Inhalte auf Missbrauchsrisiken prüfen.
5. Paketversion, unterstützte Antora- und Node.js-Linien sowie Änderungsregeln dokumentieren.
6. Freigabe, Rollback und Fehleranalyse für eine neue Paketversion proben.

Praxisaufgabe

Das entwickelte Paket wird automatisiert getestet, versioniert und mit einer technischen Freigabecheckliste bewertet.

Zielgruppe und Voraussetzungen

Zielgruppe: JavaScript- und Node.js-Entwicklung, Content Engineering, Tooling-Teams, technische Redaktionen mit Entwicklungsschwerpunkt und Plattformverantwortung.

Voraussetzungen: Sichere JavaScript- oder Node.js-Grundkenntnisse, praktische AsciiDoc-Erfahrung und Verständnis eines Antora-Builds.

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.