Seminar Antora – Multi-Format-Publishing mit Antora Assembler

Beschreibung

Das Seminar vermittelt die Erzeugung zusätzlicher Publikationsformate aus Antora-Inhalten mit Antora Assembler. Navigation wird als Assembly-Blueprint verwendet, Inhalte werden für lineare Ausgabe zusammengestellt und über geeignete Exporter in PDF, EPUB oder eigenständiges HTML überführt. Thematisiert werden Dokumentstruktur, Metadaten, Assets, Formatvorlagen, Build-Automatisierung, Validierung und Fehlerdiagnose.

Inhaltsübersicht

1. Publikationsarchitektur und Formatentscheidung
2. Navigation als Assembly-Blueprint
3. Assembler-Installation und Grundkonfiguration
4. PDF-Ausgabe und Gestaltung
5. EPUB und eigenständiges HTML
6. Inhaltsvarianten, Attribute und Assets
7. CI-Automatisierung und Qualitätskontrolle

Lernziele

• Navigation als kontrollierten Assembly-Blueprint für lineare Publikationen nutzen.
• Geeignete Exporter für PDF, EPUB und eigenständiges HTML konfigurieren.
• Metadaten, Assets und Formatgestaltung reproduzierbar steuern.
• Mehrformat-Builds automatisieren und formatspezifisch validieren.

1. Publikationsarchitektur und Formatentscheidung

Nicht jedes Online-Inhaltsmodell eignet sich unverändert für lineare Dokumente.

Schritt-für-Schritt: Ein Mehrformat-Konzept entwickeln

1. Zielgruppen, Nutzungssituationen, Archivbedarf und Verteilwege für zusätzliche Formate erfassen.
2. PDF, EPUB und eigenständiges HTML anhand von Layout, Navigation, Offline-Nutzung und Barrierefreiheit vergleichen.
3. Inhalte bestimmen, die gemeinsam genutzt, formatspezifisch ergänzt oder ausgeschlossen werden.
4. Versionierung und Kennzeichnung der Publikationsartefakte festlegen.
5. Abnahmekriterien je Format definieren.
6. Die gewählten Formate und Grenzen in einer Publikationsentscheidung dokumentieren.

Praxisaufgabe

Für ein Produkthandbuch wird ein begründetes Format- und Distributionskonzept erstellt.

2. Navigation als Assembly-Blueprint

Die Reihenfolge und Hierarchie der Navigation steuert die lineare Zusammenstellung.

Schritt-für-Schritt: Eine Assembly-Navigation vorbereiten

1. Bestehende Navigation auf lineare Lesereihenfolge und vollständige Kapitelstruktur prüfen.
2. Formatfremde Einstiegsseiten, Indexseiten oder redundante Pfade identifizieren.
3. Eine eigene Assembly-Navigation oder gezielte Navigationsvariante anlegen.
4. Kapitel, Unterkapitel und optionale Inhalte eindeutig strukturieren.
5. Querverweise innerhalb und außerhalb der Assembly klassifizieren.
6. Einen Probe-Assembly-Lauf ausführen und Reihenfolge sowie Vollständigkeit kontrollieren.

Praxisaufgabe

Eine Online-Navigation wird in eine lineare Handbuchstruktur mit klarer Kapitelreihenfolge überführt.

3. Assembler-Installation und Grundkonfiguration

Assembler wird als separates Build-Werkzeug mit expliziten Eingaben, Ausgaben und Exportern eingerichtet.

Schritt-für-Schritt: Eine reproduzierbare Assembly-Umgebung aufbauen

1. Assembler und benötigte Exporter projektbezogen installieren.
2. Versionen in Paketmanifest und Sperrdatei festhalten.
3. Assembly-Konfiguration mit Antora-Playbook, Navigation und Ausgabeziel anlegen.
4. Ein minimales lineares Zwischendokument erzeugen.
5. Protokoll und erzeugte Artefakte auf Vollständigkeit prüfen.
6. Installations- und Build-Befehle als wiederholbare Skripte dokumentieren.

Praxisaufgabe

Ein erster Assembly-Build wird aus der Seminar-Site erzeugt und technisch verifiziert.

4. PDF-Ausgabe und Gestaltung

PDF benötigt zusätzlich zu korrektem Inhalt eine kontrollierte Seiten-, Schrift- und Druckgestaltung.

Schritt-für-Schritt: Eine PDF-Publikation konfigurieren und prüfen

1. PDF-Exporter aktivieren und Basisoptionen für Titel, Sprache und Dokumentmetadaten setzen.
2. Formatvorlage für Seitenformat, Ränder, Überschriften, Tabellen und Codeblöcke vorbereiten.
3. Schriften und notwendige Assets innerhalb der Build-Umgebung verfügbar machen.
4. Seitenumbrüche, Inhaltsverzeichnis, Kopf- und Fußbereiche kontrollieren.
5. Lange Tabellen, Codeblöcke, Bilder und Warnhinweise mit Grenzfällen testen.
6. PDF auf Metadaten, Verlinkung, Lesbarkeit und technische Integrität prüfen.

Praxisaufgabe

Ein gebrandetes PDF-Handbuch wird erzeugt und anhand einer formatspezifischen Prüfliste abgenommen.

5. EPUB und eigenständiges HTML

Reflowfähige und eigenständige Formate stellen andere Anforderungen an Navigation, Assets und Darstellung.

Schritt-für-Schritt: Weitere Exportformate implementieren

1. EPUB- oder HTML-Exporter mit eindeutigen Ausgabezielen konfigurieren.
2. Titel, Autor, Sprache, Kennung und weitere Publikationsmetadaten festlegen.
3. CSS und eingebettete Assets für portable Darstellung vorbereiten.
4. Interne Navigation, Kapitelwechsel und Querverweise prüfen.
5. Darstellung in mehreren Readern oder Browserkontexten testen.
6. Formatvalidierung ausführen und gefundene Struktur- oder Metadatenfehler korrigieren.

Praxisaufgabe

Neben dem PDF wird ein zweites portables Format erzeugt und in unterschiedlichen Lesekontexten geprüft.

6. Inhaltsvarianten, Attribute und Assets

Mehrformat-Ausgabe erfordert kontrollierte Varianten, ohne parallele Inhaltskopien zu erzeugen.

Schritt-für-Schritt: Formatspezifische Inhalte wartbar steuern

1. Inhalte identifizieren, die online, gedruckt oder offline unterschiedlich erscheinen müssen.
2. Attribute und bedingte Inhalte mit klaren Benennungs- und Testregeln definieren.
3. Alternative Bilder oder vereinfachte Darstellungen nur bei nachgewiesenem Bedarf einsetzen.
4. Links, interaktive Elemente und eingebettete Medien durch geeignete Offline-Alternativen ersetzen.
5. Gemeinsame Partials und Beispiele auf formatneutrale Struktur prüfen.
6. Alle Zielvarianten in einer Testmatrix bauen und inhaltlich vergleichen.

Praxisaufgabe

Eine Seite mit Online-Interaktionen wird in wartbare Varianten für Web, PDF und EPUB überführt.

7. CI-Automatisierung und Qualitätskontrolle

Mehrere Ausgaben werden als versionierte, nachvollziehbare Artefakte derselben Pipeline erzeugt.

Schritt-für-Schritt: Einen kontrollierten Mehrformat-Build etablieren

1. Site-Build und Assembly-Build in klar getrennte Pipeline-Schritte gliedern.
2. Exporter-Abhängigkeiten, Formatvorlagen und Assets reproduzierbar bereitstellen.
3. PDF, EPUB oder HTML parallel oder in definierter Reihenfolge erzeugen.
4. Dateinamen, Versionen, Prüfsummen und Veröffentlichungsziele standardisieren.
5. Technische Validatoren und fachliche Stichproben je Format als Qualitätsgates integrieren.
6. Artefakte, Protokolle und Quellmanifest für Audit und Rollback aufbewahren.

Praxisaufgabe

Ein CI-Lauf erzeugt zwei freigegebene Publikationsformate mit Prüfbericht und nachvollziehbarer Versionskennzeichnung.

Zielgruppe und Voraussetzungen

Zielgruppe: Documentation Engineers, technische Redakteure, Publishing- und Plattformteams, DevOps, Informationsarchitektur und Verantwortliche für Offline- oder Archivformate.

Voraussetzungen: Sicherer Umgang mit Antora-Komponenten, Navigation und Playbooks sowie Grundkenntnisse in AsciiDoc; Kenntnisse des Zielpublikationsformats sind hilfreich.

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.