Confluence publisher Gradle plugin User guide

1. The Confluence publisher plugin

The Confluence publisher plugin is a plugin to convert documentation written in asciidoc into the Confluence format. The converted documentation can be directly published to Confluence. This plugin makes use of the confluence-publisher project and is a conversion of that Maven plugin to Gradle.

To use the plugin make use of the Gradle plugin DSL.

plugins {
    id 'ch.nomisp.confluence.publisher' version '<version>'
}

2. Available tasks

The Confluence publisher plugin provides one single task publishToConfluence. This task converts the .adoc pages to the Confluence format.

3. Configuration of the 'publishToConfluence' task

The task can be configured with the following properties:

Property	Description	Constraint
asciiDocRootFolder	The documentation root folder with the AsciiDoc file structure.	mandatory
outputDir	The output directory for the converted documents.	optional (default buildDir/docs/confluence)
rootConfluenceUrl	The root URL of the Confluence instance to publish to.	mandatory
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.	mandatory
password	The password of the user to use for publishing. 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 ("").	mandatory
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.	optional (default true)
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) The values are defined in the enum: org.sahli.asciidoc.confluence.publisher.client.PublishingStrategy which can be imported for an easier use	optional (default 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) The values are defined in the enum: org.sahli.asciidoc.confluence.publisher.client.OrphanRemovalStrategy which can be imported for an easier use	optional (default REMOVE_ORPHANS)
pageTitlePrefix	The prefix to be prepended to every page title.	optional (default empty)
pageTitleSuffix	The suffix to be appended to every page title.	optional (default empty)
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. Untested	optional (default empty)
sourceEncoding	The encoding of the AsciiDoc files. Untested	optional (default UTF-8)
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). Untested	optional (default http)
proxyHost	The host of the forward proxy. Mandatory if a proxy is used. Untested	optional (default empty)
proxyPort	The port of the forward proxy. Untested	optional (default 80)
proxyUsername	The username of the forward proxy (in case the forward proxy requires basic authentication). Untested	optional (default empty)
proxyPassword	The password of the forward proxy (in case the forward proxy requires basic authentication). Untested	optional (default empty)

Property

Description

Constraint

asciiDocRootFolder

The documentation root folder with the AsciiDoc file structure.

mandatory

outputDir

The output directory for the converted documents.

optional (default buildDir/docs/confluence)

rootConfluenceUrl

The root URL of the Confluence instance to publish to.

mandatory

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.

mandatory

password

The password of the user to use for publishing.

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 ("").

mandatory

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.

optional (default true)

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)

The values are defined in the enum: org.sahli.asciidoc.confluence.publisher.client.PublishingStrategy which can be imported for an easier use

optional (default 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)

The values are defined in the enum: org.sahli.asciidoc.confluence.publisher.client.OrphanRemovalStrategy which can be imported for an easier use

optional (default REMOVE_ORPHANS)

pageTitlePrefix

The prefix to be prepended to every page title.

optional (default empty)

pageTitleSuffix

The suffix to be appended to every page title.

optional (default empty)

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.

Untested

optional (default empty)

sourceEncoding

The encoding of the AsciiDoc files.

Untested

optional (default UTF-8)

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).

Untested

optional (default http)

proxyHost

The host of the forward proxy. Mandatory if a proxy is used.

Untested

optional (default empty)

proxyPort

The port of the forward proxy.

Untested

optional (default 80)

proxyUsername

The username of the forward proxy (in case the forward proxy requires basic authentication).

Untested

optional (default empty)

proxyPassword

The password of the forward proxy (in case the forward proxy requires basic authentication).

Untested

optional (default empty)

3.1. Commandline arguments

Argument	Description	Constraint
--skipSslVerification	Defines whether to disable SSL certificate verification when connecting to Confluence via HTTPS while using self- signed certificates.	optional (default false)
--convertOnly	Defines whether to only convert AsciiDoc sources, but not publish to Confluence (for checking documentation sanity without publishing).	optional (default false)

Argument

Description

Constraint

--skipSslVerification

Defines whether to disable SSL certificate verification when connecting to Confluence via HTTPS while using self- signed certificates.

optional (default false)

--convertOnly

Defines whether to only convert AsciiDoc sources, but not publish to Confluence (for checking documentation sanity without publishing).

optional (default false)

Example:

confluencePublisher {
    asciiDocRootFolder = tasks.asciidoctor.sourceDir
    outputDir = "${buildDir}/docs/confluence"
    rootConfluenceUrl = 'https://myconfluence.url.com'
    spaceKey = 'MySpace'
    ancestorId = '1234567'
    username = 'MyConfluenceUser'
    password = 'MySecretPassword'
    notifyWatchers = false
}