Version 0.35.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 Server 6.0.5 and Confluence Cloud.

Publishing to a locally installed Confluence instance might require the use of REST API v1 (see [restApiVersion] configuration property)

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 Property	Description	Constraint
asciidocRootFolder	The documentation root folder with the AsciiDoc file structure.	mandatory
sourceEncoding	The encoding of the AsciiDoc files.	optional (defaults to UTF-8)
rootConfluenceUrl	The root URL of the Confluence instance to publish to. Note: when publishing to Confluence Cloud using an API token, the root URL is `https://<project>.atlassian.net/wiki`. Note: when publishing to Confluence Cloud using a scoped API token, the root URL is `https://api.atlassian.com/ex/confluence/<cloud-id>` (see Atlassian documentation on how to identify the cloud id).	mandatory
skipSslVerification	Defines whether to disable SSL certificate verification when connecting to Confluence via HTTPS while using self- signed certificates.	optional (defaults to `false`)
enableHttpClientSystemProperties	Defines 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)
maxRequestsPerSecond	Defines the number (positive integer or double) of REST API calls to execute within a second.	optional (defaults to no rate limit)
connectionTimeToLive	Defines 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)
spaceKey	The key of the Confluence space to publish to.	mandatory
ancestorId	The 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
username	The username of the user to use for publishing. Note: when publishing to Confluence Cloud, specify the email address of the corresponding Atlassian account (even when using an API token or a scoped API token as password). Note: when publishing to Confluence Server using a personal access token, the username must be left unspecified/empty. Note: overrules username defined by serverId, when set in conjunction with serverId	optional (unspecified behaves like an empty string)
password	The password, API token or scoped API token of the user to use for publishing, or a personal access token when the username is unspecified/empty. Note: when publishing to Confluence Cloud, an API token or a scoped API token generated via the corresponding Atlassian account has to be used as password. Make sure to set the correct root URL for Confluence depending on the token type (see [rootConfluenceUrl] configuration property). Note: when using a scoped API token, the following OAuth 2.0 scopes are required: read:hierarchical-content:confluence read:space:confluence read:page:confluence read:content-details:confluence read:label:confluence read:attachment:confluence delete:attachment:confluence delete:page:confluence write:attachment:confluence write:confluence-file write:confluence-content write:label:confluence write:page:confluence Note: overrules password defined by serverId, when set in conjunction with serverId	mandatory, if serverId is not specified
serverId	The 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`)
versionMessage	The 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)
notifyWatchers	Defines 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. Note: suppressing notifications to watchers on page changes is not supported by Confluence Cloud.	optional (defaults to true)
attributes	User-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)
pageTitlePrefix	The 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)
pageTitleSuffix	The 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)
skip	Defines whether the plugin execution should be skipped.	optional (defaults to `false`, only supported for Maven plugin)
convertOnly	Defines whether to only convert AsciiDoc sources, but not publish to Confluence (for checking documentation sanity without publishing).	optional (defaults to `false`)
failOnError	Defines whether the build should fail when an error occurs during publishing (e.g. when Confluence server is not reachable or there are errors in provided pages/markdown). When set to `false`, errors are logged but the build continues successfully.	optional (defaults to `true`)
proxyScheme	The 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)
proxyHost	The host of the forward proxy.	optional (defaults to empty)
proxyPort	The port of the forward proxy.	optional (defaults to empty)
proxyUsername	The username of the forward proxy (in case the forward proxy requires basic authentication).	optional (defaults to empty)
restApiVersion	The version of the Confluence REST API to be used, either `v1` or `v2`. Default is version 2. Note: version 1 is no longer supported for Confluence Cloud. Only use version 1 for Confluence Server and only in case of issues with version 2.	optional (defaults to `v2`)