Seminar Antora – Xrefs, Ressourcen-IDs und robuste Verlinkung

Beschreibung

Das Seminar behandelt Antoras Ressourcen-Identitätsmodell und die robuste Verlinkung innerhalb komplexer Dokumentationssites. Lokale, modul-, komponenten- und versionsübergreifende Xrefs, Bilder, Beispiele, Anhänge, Partials, Seitenanker, Aliase, Redirect-Strategien und automatisierte Linkprüfung werden anhand mehrerer Komponenten praktisch umgesetzt. Der Schwerpunkt liegt auf wartbaren Referenzen, die Repository- und Versionsänderungen überstehen.

Inhaltsübersicht

1. Ressourcen-Identitätsmodell
2. Lokale und modulübergreifende Xrefs
3. Komponenten- und versionsübergreifende Referenzen
4. Bilder, Beispiele, Anhänge und Partials
5. Aliase, Umbenennungen und URL-Weiterführung
6. Migration relativer Links und automatisierte Prüfung

Lernziele

• Ressourcen-IDs aus Komponente, Version, Modul, Familie und Pfad sicher ableiten.
• Lokale und bereichsübergreifende Xrefs mit minimal notwendiger Qualifikation schreiben.
• Nichtseitige Ressourcen, Anker, Aliase und Redirects korrekt behandeln.
• Linknetze automatisiert prüfen und migrationssicher weiterentwickeln.

1. Ressourcen-Identitätsmodell

Antora adressiert Ressourcen unabhängig von ihrem lokalen Dateisystempfad über eine zusammengesetzte Identität.

Schritt-für-Schritt: Eine Ressourcen-ID schrittweise bestimmen

1. Komponente, Version, Modul, Ressourcenfamilie und relativen Ressourcenpfad einer Datei erfassen.
2. Vollständige Ressourcen-ID aus den Identitätsbestandteilen zusammensetzen.
3. Zwischen Dateisystempfad, Quell-URL, Ressourcen-ID und Ausgabepfad unterscheiden.
4. ROOT-Modul und Standardfamilien in mehreren Beispielen korrekt zuordnen.
5. Mehrdeutige Dateinamen in unterschiedlichen Modulen oder Versionen analysieren.
6. Eine Referenzmatrix für die Seminar-Site erstellen.

Praxisaufgabe

Für Seiten, Bilder, Partials, Beispiele und Anhänge werden vollständige Ressourcen-IDs abgeleitet.

2. Lokale und modulübergreifende Xrefs

Referenzen sollen so kurz wie möglich, aber so eindeutig wie nötig geschrieben werden.

Schritt-für-Schritt: Xrefs mit angemessener Qualifikation erstellen

1. Zielseite im selben Modul mit einer lokalen Ressourcenangabe referenzieren.
2. Ziel im anderen Modul durch Ergänzen des Modulnamens eindeutig adressieren.
3. Linktext explizit setzen oder bewusst aus dem Ziel ableiten.
4. Seitenanker mit stabiler Abschnitts-ID ergänzen.
5. Mehrdeutige und nicht auflösbare Ziele durch einen Testbuild identifizieren.
6. Referenzen nach einer Regel für minimale, aber stabile Qualifikation vereinheitlichen.

Praxisaufgabe

Ein Satz relativer Dateilinks wird in robuste lokale und modulübergreifende Xrefs überführt.

3. Komponenten- und versionsübergreifende Referenzen

Große Sites benötigen kontrollierte Querverweise zwischen Produkten und Release-Linien.

Schritt-für-Schritt: Bereichsübergreifende Xrefs sicher einsetzen

1. Fachlichen Bedarf und Lebensdauer eines komponentenübergreifenden Verweises bewerten.
2. Komponentenname und erforderliche Version in der Ziel-ID ergänzen.
3. Explizite Version, aktuelle Version und versionsrelative Verknüpfung bewusst unterscheiden.
4. Zielverfügbarkeit in allen betroffenen Builds und Release-Linien prüfen.
5. Verweise auf nicht gemeinsam veröffentlichte Komponenten als Risiko dokumentieren.
6. Fallback- oder Entkopplungsstrategie für entfernte Versionen festlegen.

Praxisaufgabe

Zwei Produktkomponenten und drei Versionen werden mit kontrollierten Querverweisen verbunden.

4. Bilder, Beispiele, Anhänge und Partials

Nichtseitige Ressourcen verwenden eigene Makros und Familien, folgen aber demselben Identitätsprinzip.

Schritt-für-Schritt: Ressourcenfamilien korrekt referenzieren

1. Bild, Codebeispiel, Download und Partial in die passende Familienstruktur einordnen.
2. Lokale Ressourcen mit dem vorgesehenen Makro einbinden.
3. Modul- oder komponentenübergreifende Ziel-IDs vollständig qualifizieren.
4. Alternativtext, Beschriftung, Dateityp und Downloadhinweis fachgerecht ergänzen.
5. Fehlende und doppelte Ressourcen über Build-Meldungen isolieren.
6. Wiederverwendung gegen Kopplung, Eigentum und Versionsstabilität abwägen.

Praxisaufgabe

Eine Seite bindet Ressourcen aus mehreren Familien und einem gemeinsamen Modul regelkonform ein.

5. Aliase, Umbenennungen und URL-Weiterführung

Strukturänderungen dürfen etablierte Verweise und öffentliche Einstiegspunkte nicht unkontrolliert brechen.

Schritt-für-Schritt: Ressourcen sicher umbenennen oder verschieben

1. Betroffene interne Xrefs, externe Einstiegspunkte und Suchtreffer vor der Änderung inventarisieren.
2. Neue Ressourcen-ID und gewünschte Ausgabeposition festlegen.
3. Geeigneten Alias oder eine externe Weiterleitungsregel für die alte Identität definieren.
4. Quellen schrittweise auf das neue Ziel umstellen.
5. Build, Aliasauflösung und öffentliche Weiterleitung auf Schleifen und Ketten prüfen.
6. Übergangsfrist und spätere Bereinigung dokumentieren.

Praxisaufgabe

Eine zentrale Seite wird in ein anderes Modul verschoben, ohne bestehende Verweise unkontrolliert zu brechen.

6. Migration relativer Links und automatisierte Prüfung

Historische relative Pfade werden systematisch erkannt, umgewandelt und dauerhaft überwacht.

Schritt-für-Schritt: Ein Linknetz migrationssicher bereinigen

1. Relative Links und Dateipfade aus dem Quellbestand extrahieren.
2. Ziele gegen das geplante Ressourcenmodell auflösen.
3. Konvertierungsregeln für lokale, modul- und komponentenübergreifende Ziele definieren.
4. Automatisierte Umwandlung zunächst auf einer kontrollierten Stichprobe ausführen.
5. Build-Warnungen, nicht aufgelöste Ziele und falsche Linktexte in einem Bericht sammeln.
6. Linkprüfung als verpflichtendes Qualitätsgate in den Änderungs- und Releaseprozess integrieren.

Praxisaufgabe

Ein vorbereiteter Altbestand wird in Xrefs migriert und über einen automatisierten Linkbericht abgenommen.

Zielgruppe und Voraussetzungen

Zielgruppe: Technische Redakteure, Documentation Engineers, Content-Architekten, Softwareteams mit Dokumentationsverantwortung und Migrationsprojekte.

Voraussetzungen: Grundkenntnisse in AsciiDoc, Antora-Komponenten und Modulen sowie sicherer Umgang mit Dateien und relativen Pfaden.

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.