Erstellung von Antora-Komponenten

IFS-Logo Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Jeder Inhalt der Online-Dokumentation ist Teil genau einer Antora-Komponente. Dieser Guide beschreibt, was zur Erstellung einer Antora-Komponente nötig ist.

1. Aufbau der Antora-Komponente

Jede Antora-Komponente liegt in einem Git-Repository. Der Pfad, unter dem die Komponente liegt, heißt content source root, und wird in der Regel durch die Struktur des Projekts, das sie dokumentiert, bestimmt. Unterhalb dieses Pfades sollten nur Bestandteile der Antora-Komponente liegen.

In der Regel enthält ein Repository genau eine Antora-Komponente. Dies liegt daran, dass mehrere, versionierte Antora-Komponenten in einem Repository nur schwer gleichzeitig zu veröffentlichen sind. Einen Sonderfall stellen Antora-Komponenten ohne Version dar. Diese können zur Vereinfachung in einem gemeinsamen Repository liegen.

Eine minimale Antora-Komponente enthält eine Konfigurationsdatei (antora.yml), ein Modul (ROOT), eine Navigationsdatei (nav.adoc) und eine Seite (index.adoc), die anfangs als Startseite für die neue Antora-Komponente dient.

Listing 1. Minimaler Aufbau einer Antora-Komponente
📒 content-source-root (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📄 nav.adoc (5)
      📂 pages
        📄 index.adoc (6)
1 Verzeichnis der Komponente
2 Konfigurationsdatei der Komponente
3 Verzeichnis für Module
4 Verzeichnis des ROOT-Moduls
5 "Startseite" des Moduls

Das ROOT-Modul ist eine Konvention von Antora und sorgt dafür, dass der Modulname nicht Bestandteil der URL der einzelnen Seiten wird.

2. Aufbau der Konfigurationsdatei

Eine minimale Konfigurationsdatei enthält den technischen Namen (name), den Titel (title) sowie die initiale Version (version und prerelease) der Antora-Komponente. Außerdem definiert sie die Startseite (start_page) der Antora-Komponente und wie ihre Navigation (nav) aufgebaut ist.

Listing 2. Minimale Konfigurationsdatei
name: new-component
title: Neue Komponente
version: 0.1 | ~
prerelease: false | (DEV)
start_page: ROOT:index.adoc
nav:
  - modules/ROOT/nav.adoc

Der Name der Antora-Komponente tritt als Teil der URL jeder Seite in Erscheinung. Der Titel erscheint an verschiedenen Stellen der Online-Dokumentation und ist meist mit einem Verweis auf die Startseite der Antora-Komponente versehen. Das Setzen der Version behandelt der Guide zur Versionierung von Inhalten.

Die Navigation enthält zu Beginn die Navigationsdatei des ROOT-Moduls. Perspektivisch referenziert sie die Navigationsdateien aller Module. Das folgende Beispiel zeigt die Konfiguration zur Navigation der IsyFact-Standards.

Listing 3. Navigation der IsyFact
nav:
  - modules/einstieg/nav.adoc
  - modules/referenzarchitektur/nav.adoc
  - modules/bausteine/nav.adoc
  - modules/plattform/nav.adoc
  - modules/methodik/nav.adoc
  - modules/werkzeuge/nav.adoc
  - modules/release/nav.adoc

3. Aufbau der Navigationsdatei

Eine minimale Navigationsdatei enthält als einzigen Eintrag die Startseite des ROOT-Moduls.

Listing 4. Minimale Navigationsdatei
* xref:index.adoc[]

Die Navigationsdatei kann im späteren Verlauf nicht nur eine Liste von Seiten enthalten, sondern auch Untermenüs definieren. Das folgende Beispiel zeigt die Navigationsdatei dieses Leitfadens.

Listing 5. Navigationsdatei des Leitfadens
* xref:index.adoc[Online-Dokumentation mit AsciiDoc und Antora]
** xref:create-antora-component.adoc[]
** xref:seitenvorlage.adoc[]
** xref:guides/bearbeitung-antora.adoc[]
** xref:guides/content-changes.adoc[]
** xref:glossary.adoc[]
** xref:content-versioning.adoc[]
** xref:content-sources.adoc[]
** xref:guides/generierung-antora.adoc[]
** xref:namenskonventionen.adoc[]
* xref:kopiervorlage.adoc[]

4. Ausblick: Inhalte hinzufügen

Nach der Erstellung der Antora-Komponente kann diese mit weiteren Inhalten versehen werden. Einen Startpunkt hierzu bietet die Antora-Dokumentation zur Struktur einer Komponente.