#AsciiDoc #Confluence #Maven #Docs-as-Code

AsciiDoc nach Atlassian Confluence publizieren

Mit AsciiDoc lässt sich einfach und schnell Dokumentation als Code erstellen. Um diese auch nicht technischen Personen zur Verfügung zu stellen, helfen Tools wie Antora oder Jekyll. Weit verbreitet ist jedoch Atlassian Confluence. Damit nicht noch ein weiteres Tool in der Firma eingeführt werden muss, gibt es einen einfach weg mit Maven die Dokumentation ins Confluence zu pushen.

Konfiguration von Maven

Um AsciiDocs nach Confluence zu pushen benötigt man das Maven-Plugin Confluence Publisher:

<plugin>
    <groupId>org.sahli.asciidoc.confluence.publisher</groupId>
    <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId>
    <version>0.15.1</version>
</plugin>

Da ich die Möglichkeit habe verschiedene Ausgabeformate für meine Dokumentation zu wählen, habe ich ein Maven Profile für die Ausgabe ins Confluence erstellt:

<profiles>
    <profile>
        <id>confluence</id>
        <build>
            <plugins>
                <plugin>
                    <executions>
                        <execution>
                            <id>publish-documentation</id>
                            <phase>generate-resources</phase>
                            <goals>
                                <goal>publish</goal>
                            </goals>
                        </execution>
                    </executions>
                    <groupId>org.sahli.asciidoc.confluence.publisher</groupId>
                    <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId>
                    <version>0.15.1</version>
                    <configuration>
                        <asciidocRootFolder>${project.basedir}/docs</asciidocRootFolder> (1)
                        <sourceEncoding>UTF-8</sourceEncoding>
                        <rootConfluenceUrl>https://confluence-url</rootConfluenceUrl> (2)
                        <skipSslVerification>true</skipSslVerification> (3)
                        <spaceKey>TEC</spaceKey> (4)
                        <ancestorId>444375435</ancestorId> (5)
                        <serverId>confluence</serverId> (6)
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>
1 Pfad, wo die Dokumentation zu finden ist
2 Url zum Confluence
3 Wenn ein s.g. SelfSignedCertificate verwendet wird, soll die SSL-Prüfung übersprungen werden
4 Der Confluence-SpaceKey, zum Beispiel https://confluence-url/display/TEC/DOC ⇐ Hier ist der SpaceKey TEC
5 Die Seite, unter der die Dokumentation im Confluence erstellt werden soll. Siehe Punkt "Wie finde ich die ancestorId"
6 Die Maven-Server-Id. Siehe Punkt "Maven Server Konfiguration"

Jetzt kann mit dem Maven Befehl mvn -P confluence clean generate-resources die Dokumentation ins Confluence gepushed werden.

Wie finde ich die ancestorId

  1. Öffne die Confluence Seite unter der die erzeugten Seiten angehängt werden soll

  2. Beim Öffnen der Seitendetails, den Menüpunkt "Page Informations" öffnen
    confluence page informations

  3. In der URL findet ihr nun die "pageId", diese wird als ancestorId verwendet
    confluence page id.

Maven Server Konfiguration

Um einen Maven-Server zu konfigurieren (Anmeldung am Confluence mit User + Passwort) muss man diesen in der .m2/settings.xml konfiguriert werden. In der settings.xml muss dann folgender Eintrag vorhanden sein:

settings.xml
<settings>
    <server>
      <id>confluence</id>
      <username>EIN USER</username>
      <password>DAS PASSWORT</password>
    </server>
</settings>

Maven Passwort Encryption

Jetzt möchte man natürlich nicht das Passwort als Plain-Text in der settings.xml platzieren. Dafür bietet Maven eine Password Encryption an.

Auf Windows am besten die Powershell verwenden!

Im ersten Schritt muss ein Masterpasswort zur Entschlüsselung festgelegt werden

mvn --encrypt-master-password

Dieser Befehl erzeugt eine verschlüsselte Variante deines Passworts:

{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}

Diese muss in der Datei ${user.home}/.m2/settings-security.xml kopiert werden.

Falls die Datei nicht vorhanden ist, bitte erstellen!
settings-security.xml
<settingsSecurity>
  <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity>

Jetzt kann das Passwort für den Maven-Server verschlüsselt werden. Hierzu den folgenden Befehl aufrufen:

mvn --encrypt-password
Ergebnis
{COQLCE6DU6GtcS5P=}

Das Ergebnis muss dann in die Passwort-Sektion des Maven-Servers:

settings.xml
<settings>
    <server>
      <id>confluence</id>
      <username>EIN USER</username>
      <password>{COQLCE6DU6GtcS5P=}</password>
    </server>
</settings>

Konfiguration von Graphviz

Damit AsciiDoc Diagramme erstellen kann, benötigt es die Software Graphviz. Diese ist sehr einfach zu installieren.

  • Download von Graphviz https://graphviz.org/download/

  • Im PATH der Umgebungsvariablen, sollte nun der Eintrag C:\Program Files\Graphviz\bin stehen. Wenn nicht, dann bitte ergänzen.

Genutzte Tools

Um diesen Artikel ins Confluence zu publizieren, kamen die folgenden Technologien zum Einsatz: