Supported Features

Currently, the Confluence Publisher supports the following AsciiDoc features:

• Pages
• Includes
• Sections
• Paragraphs
• Tables
• Images
• Listings
• Admonitions
• External Links
• PlantUML
• Attachments
• Table of Contents
• Additional Features

The Confluence Publisher uses AsciidoctorJ and therefore supports documentation written using the Asciidoctor syntax. See Asciidoctor User Manual for more information about Asciidoctor.

Documentation Source Structure

The Confluence Publisher expects the AsciiDoc sources to be stored in a specific source structure. This source structure is used to derive the page hierarchy in Confluence.

<root>
 +- top-level-page.adoc    // top-level page AsciiDoc file
 +- top-level-page         // folder for sub-pages and resources of top-level page
    +- sub-page-one.adoc   // first sub page AsciiDoc file
    +- sub-page-two.adoc   // second sub page AsciiDoc file
    +- sub-page-two        // folder for sub-pages and resources of sub-page-two
  +- any-other-folder      // folder for additional files (e.g. images, PlantUML files, ...)
    +- ...

AsciiDoc files are expected to be encoded in UTF-8, unless explicitly configured to a different encoding. Resources like images, PlantUML files, other attachment types and include files can be placed in any location and are resolved relative to the location of the referencing AsciiDoc file. See Includes, Images and PlantUML for more information about resource file path resolution.

Maven Plugin Configuration

The Confluence Publisher is configured with the help of a Maven plugin. A typical configuration could look like this:

<build>
  <plugins>
    <plugin>
      <groupId>org.sahli.asciidoc.confluence.publisher</groupId>
      <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId>
      <version><!-- insert version here --></version>
      <configuration>
        <asciidocRootFolder>etc/docs</asciidocRootFolder>
        <sourceEncoding>UTF-8</sourceEncoding> <!-- default -->
        <rootConfluenceUrl>http://localhost:8090</rootConfluenceUrl>
        <skipSslVerification>false</skipSslVerification>
        <maxRequestsPerSecond>10</maxRequestsPerSecond>
        <spaceKey>SPACE</spaceKey>
        <ancestorId>327706</ancestorId>
        <username>username</username> <!-- or read from property -->
        <password>password</password> <!-- or read from property -->
        <serverId>myServerId</serverId> <!-- requires server definition in settings.xml -->
        <pageTitlePrefix xml:space="preserve">Doc :: </pageTitlePrefix>
        <pageTitleSuffix xml:space="preserve"> [${project.version}]</pageTitleSuffix>
        <versionMessage>Version ${project.version}</versionMessage>
        <notifyWatchers>false</notifyWatchers>
        <attributes>
            <version>${project.version}</version>
            <someOtherKey>value</someOtherKey>
        </attributes>
      </configuration>
    </plugin>
  </plugins>
</build>

When relying on Maven support for encrypted credentials using the serverId configuration property, username and password need to be defined in settings.xml:

<settings>
...
  <servers>
...
    <server>
      <id>myServerId</id>
      <username>myusername</username>
      <password>myEncryptedPassword</password>
    </server>
...
  </servers>
...
</settings>

As usually with Maven, configuration properties can either be defined directly in the Confluence Publisher maven plugin configuration, defined as separate Maven properties, read from the settings.xml or passed as system properties with help of -Dasciidoc-confluence-publisher. prefix.

Maven Plugin Execution

The Confluence Publisher Maven plugin goal publish can be bound to a specific lifecycle, if it should be executed automatically when building the project, e.g. for execution during the site phase:

<!-- ... -->
<executions>
    <execution>
        <id>publish-documentation</id>
        <goals>
            <goal>publish</goal>
        </goals>
        <phase>site</phase>
    </execution>
</executions>
<!-- ... -->

Alternatively, the Confluence Publisher Maven plugin can also be executed manually via the command line:

mvn org.sahli.asciidoc.confluence.publisher:asciidoc-confluence-publisher-maven-plugin:publish

Using Snapshot Version

The code on master is automatically published as version 0.0.0-SNAPSHOT to the Sonatype Maven snapshot repository. Use the following configuration in your pom.xml in order to use the latest snapshot version:

<pluginRepository>
  <id>sonatype-snapshot-repo</id>
  <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  <releases>
    <enabled>false</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
  </snapshots>
</pluginRepository>

<!-- ... -->

<build>
  <plugins>
    <plugin>
      <groupId>org.sahli.asciidoc.confluence.publisher</groupId>
      <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId>
      <version>0.0.0-SNAPSHOT</version>
      <!-- ... -->
    </plugin>
  </plugins>
</build>

Docker Image

The Confluence Publisher supports publishing documentation via the confluencepublisher/confluence-publisher Docker image. The Docker image does not provide a latest tag, but uses the Confluence Publisher version number as the tag. The Docker image for the code on master is automatically published as version 0.0.0-SNAPSHOT to Docker Hub.

Instead of providing the asciidocRootFolder configuration property as with the Maven plugin, the AsciiDoc sources have to be mounted to the /var/asciidoc-root-folder volume.

In case your documentation sources are already available under a different path in your Docker container, you can specify the path to the documentation sources via the environment variable ASCIIDOC_ROOT_FOLDER.

The generated Confluence XHTML will be stored in a temporary directory inside the container, and will be deleted after command exits. To keep the generated pages, for inspection, set ASCIIDOC_BUILD_FOLDER to a path that is mounted into the container. This path will not be deleted after the command exits.

All other mandatory and optional configuration properties from the Maven plugin have to be / can be specified as environment variable in all-uppercase writing, e.g. ROOT_CONFLUENCE_URL for rootConfluenceUrl.

The following command shows an example for publishing AsciiDoc sources via the Confluence Publisher Docker image:

docker run --rm -e ROOT_CONFLUENCE_URL=http://confluence-host \
   -e SKIP_SSL_VERIFICATION=false \
   -e MAX_REQUESTS_PER_SECOND=10 \
   -e CONNECTION_TIME_TO_LIVE=500 \
   -e USERNAME=username \
   -e PASSWORD=1234 \
   -e SPACE_KEY=XYZ \
   -e ANCESTOR_ID=012345 \
   -e PAGE_TITLE_PREFIX="Draft - " \
   -e PAGE_TITLE_SUFFIX=" (V 1.0)" \
   -e PUBLISHING_STRATEGY=REPLACE_ANCESTOR \
   -e ORPHAN_REMOVAL_STRATEGY=KEEP_ORPHANS \
   -e VERSION_MESSAGE="V 1.0" \
   -e NOTIFY_WATCHERS=true \
   -e ATTRIBUTES='{"attribute1": "value1", "attribute2": "value2"}' \
   -e PROXY_SCHEME=https \
   -e PROXY_HOST=my.proxy.com \
   -e PROXY_PORT=8443 \
   -e CONVERT_ONLY=false \
   -v /absolute/path/to/asciidoc-root-folder:/var/asciidoc-root-folder \
   confluencepublisher/confluence-publisher:0.0.0-SNAPSHOT

In case you want to extend the Confluence Publisher Docker image or if you use it as part of your CI build, you should use the script publish.sh for triggering the actual publishing. The following shows an example for a GitLab CI build step that uses the Confluence Publisher Docker image as its execution environment, assuming the documentation sources already being available in ./docs/ from the project checkout:

publish-docs:
  stage: publish-docs
  image:
    name: confluencepublisher/confluence-publisher:0.0.0-SNAPSHOT
    entrypoint: [""]
  variables:
    ASCIIDOC_ROOT_FOLDER: ./docs/
    ROOT_CONFLUENCE_URL: http://confluence-host
    ASCIIDOC_BUILD_FOLDER: $CI_PROJECT_DIR/build/docs
    ...
  script:
    - publish.sh
  archive:
    paths:
    - $CI_PROJECT_DIR/build/docs