Confluence Publisher

Version 0.24.0

The Confluence Publisher allows documentation written in AsciiDoc and versioned directly with the documented code base to be published to a Confluence space. It converts the resulting AsciiDoc HTML output to XHTML compatible with Confluence, manages included resources as Confluence attachments and ensures that only content modified since the last publication is again re-published.

The Confluence Publisher has been tested with Confluence 6.0.5

Supported Features

Currently, the Confluence Publisher supports the following AsciiDoc 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.

While the Confluence Publisher does not modify or delete pages outside the page tree structure defined by the ancestor id, it is recommended to use a separate Confluence space for published documentation and avoid manually adding or editing additional pages in that Confluence space.

In case multiple sources publish to the same Confluence space, ensure that each source uses its own ancestor id and that these ancestor ids are not in any parent-child relation.

Currently, the ordering of child pages cannot be influenced due to missing support in the Confluence REST API (see https://jira.atlassian.com/browse/CONFCLOUD-40101 and https://jira.atlassian.com/browse/CONFSERVER-40101 for information and voting)

Maven Plugin Configuration

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

pom.xml
<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.xml
<settings>
...
  <servers>
...
    <server>
      <id>myServerId</id>
      <username>myusername</username>
      <password>myEncryptedPassword</password>
    </server>
...
  </servers>
...
</settings>
Configuration PropertyDescriptionConstraint
asciidocRootFolderThe documentation root folder with the AsciiDoc file structure.mandatory
sourceEncodingThe encoding of the AsciiDoc files.optional (defaults to UTF-8)
rootConfluenceUrlThe root URL of the Confluence instance to publish to.

Note: when publishing to Confluence Cloud, the root URL is https://<project>.atlassian.net/wiki.
mandatory
skipSslVerificationDefines whether to disable SSL certificate verification when connecting to Confluence via HTTPS while using self- signed certificates.optional (defaults to false)
enableHttpClientSystemPropertiesDefines whether to enable support for configuring the underlying HTTP client using system properties passed to Maven. Useful for configuring custom keys and trust stores for SSL.

Note: see HTTP client documentation for supported system properties. Also, mixing skipSslVerification or the proxy-related configuration options with enableHttpClientSystemProperties is currently not supported.
optional (defaults to false, only supported for Maven plugin)
maxRequestsPerSecondDefines the number (positive integer or double) of REST API calls to execute within a second.optional (defaults to no rate limit)
connectionTimeToLiveDefines the time to live (TTL) for HTTP connections. Can be used to resolve problems with stale HTTP connections if the server uses a low TTL (<2000ms).optional (defaults to infinite)
spaceKeyThe key of the Confluence space to publish to.mandatory
ancestorIdThe id of the ancestor page under which the pages are appended. Be aware that publishing will remove all pages under the configured ancestor id that are not part of the published documentation ("orphaned pages").mandatory
usernameThe username of the user to use for publishing.

Note: Overrules username defined by serverId, when set in conjunction with serverId
optional (unspecified behaves like an empty string, see password)
passwordThe password of the user to use for publishing or a personal access token when the username is empty or unspecified.

Note: when publishing to Confluence Cloud, an API token generated via the corresponding Atlassian account has to be used as password.

Note: when publishing to on-premise Confluence with an API token, leave the username empty ("") or unspecified (for Maven plugin)

Note: Overrules password defined by serverId, when set in conjunction with serverId
mandatory, if serverId is not specified
serverIdThe id of the server with username and encrypted password defined in settings.xml

Note: see Maven Password Encryption Guide for details how to setup a server with username and encrypted password.
optional (defaults to not set, only supported for Maven plugin)
publishingStrategy

The strategy to use when publishing to confluence. Possible values:

  • APPEND_TO_ANCESTOR: append the published pages to the ancestor
  • REPLACE_ANCESTOR: replace the title and the content of the ancestor with those of the one single root page (requires the documentation source structure to contain exactly one single root page)
optional (defaults to APPEND_TO_ANCESTOR)
orphanRemovalStrategy

The strategy to use when detecting orphan pages (pages in Confluence not / no longer part of the documentation source structure) while publishing. Possible values:

  • REMOVE_ORPHANS: remove all orphan pages under the ancestor from Confluence
  • KEEP_ORPHANS: keep all orphan pages under the ancestor in Confluence (this might require manual cleanup of orphan pages in order to avoid future page name conflicts or obsolete pages)
optional (defaults to REMOVE_ORPHANS)
versionMessageThe message that will be published with the changes into Page History comment. Note: Confluence only supports version messages for updated pages, but not when creating new pages.optional (defaults to empty)
notifyWatchersDefines whether to notify page/space watchers upon changes when re-publishing. If set to false, subscribers will not receive notifications, except for new page or attachment creations.optional (defaults to true)
attributesUser-defined attributes passed to AsciidoctorJ for replacing corresponding attribute placeholders.

Note: when using Docker-based publishing, user attributes have to be provided as JSON object structure.
Note: user attributes are currently not supported for use in the page title.
optional (default to empty)
pageTitlePrefixThe prefix to be prepended to every page title.

Note: in order to preserve leading or trailing spaces in the page title prefix, the attribute xml:space="preserve" has to be added to the pageTitlePrefix element.
optional (defaults to empty)
pageTitleSuffixThe suffix to be appended to every page title.

Note: in order to preserve leading or trailing spaces in the page title suffix, the attribute xml:space="preserve" has to be added to the pageTitleSuffix element.
optional (defaults to empty)
skipDefines whether the plugin execution should be skipped.optional (defaults to false, only supported for Maven plugin)
convertOnlyDefines whether to only convert AsciiDoc sources, but not publish to Confluence (for checking documentation sanity without publishing).optional (defaults to false)
proxySchemeThe scheme (http or https) used to connect to a forward proxy (in case a forward proxy is required to access the Confluence instance).optional (defaults to empty)
proxyHostThe host of the forward proxy.optional (defaults to empty)
proxyPortThe port of the forward proxy.optional (defaults to empty)
proxyUsernameThe username of the forward proxy (in case the forward proxy requires basic authentication).optional (defaults to empty)
proxyPasswordThe password of the forward proxy (in case the forward proxy requires basic authentication).optional (defaults to empty)

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.

When specifying the ROOT_CONFLUENCE_URL environment variable, be sure to provide the host as it is resolvable from within the Docker container.

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