<commit_before>= Confluence Publisher

_Version {confluencePublisherVersion}_

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.

[NOTE]
====
The Confluence Publisher has been tested with Confluence 6.0.5
====


== Supported Features

Currently, the Confluence Publisher supports the following AsciiDoc features:

* <<00-index/01-pages.adoc#, Pages>>
* <<00-index/02-includes.adoc#, Includes>>
* <<00-index/03-sections.adoc#, Sections>>
* <<00-index/04-paragraphs.adoc#, Paragraphs>>
* <<00-index/05-tables.adoc#, Tables>>
* <<00-index/06-images.adoc#, Images>>
* <<00-index/07-listings.adoc#, Listings>>
* <<00-index/08-admonitions.adoc#, Admonitions>>
* <<00-index/09-external-links.adoc#, External Links>>
* <<00-index/10-plantuml.adoc#, PlantUML>>
* <<00-index/11-attachments.adoc#, Attachments>>
* <<00-index/12-table-of-contents.adoc#, Table of Contents>>
* <<00-index/13-additional-features.adoc#, Additional Features>>

The Confluence Publisher uses AsciidoctorJ and therefore supports documentation written using the Asciidoctor syntax.
See link:http://asciidoctor.org/docs/user-manual/[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 <<00-index/02-includes.adoc#, Includes>>,
<<00-index/06-images.adoc#, Images>> and <<00-index/10-plantuml.adoc#, PlantUML>> for more information about resource
file path resolution.

[NOTE]
====
Currently, the ordering of child pages cannot be influenced due to missing support in the Confluence REST API (see
https://jira.atlassian.com/browse/CRA-1276 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:

[source,xml]
.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`:

[source, xml]
.settings.xml
----
<settings>
...
  <servers>
...
    <server>
      <id>myServerId</id>
      <username>myusername</username>
      <password><PASSWORD></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, the root URL is https://<project>.atlassian.net/wiki.
| 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 https://hc.apache.org/httpcomponents-client-4.5.x/current/httpclient/apidocs/org/apache/http/impl/client/HttpClientBuilder.html[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)

| 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:_ Overrules username defined by serverId, when set in conjunction with serverId
| mandatory, if serverId is not specified

| 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 ("").
  +
  +
  _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 https://maven.apache.org/guides/mini/guide-encryption.html[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
a| 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
a| 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.
| 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`)

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

| proxyPassword
| The 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:

[source,xml]
----
<!-- ... -->
<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:

[source,xml]
----
<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`.

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

[NOTE]
====
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 USERNAME=username \
   -e PASSWORD=<PASSWORD> \
   -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
    ...
  script:
    - publish.sh
----
<commit_msg>added recommendation on using separate confluence space<commit_after>= Confluence Publisher

_Version {confluencePublisherVersion}_

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.

[NOTE]
====
The Confluence Publisher has been tested with Confluence 6.0.5
====


== Supported Features

Currently, the Confluence Publisher supports the following AsciiDoc features:

* <<00-index/01-pages.adoc#, Pages>>
* <<00-index/02-includes.adoc#, Includes>>
* <<00-index/03-sections.adoc#, Sections>>
* <<00-index/04-paragraphs.adoc#, Paragraphs>>
* <<00-index/05-tables.adoc#, Tables>>
* <<00-index/06-images.adoc#, Images>>
* <<00-index/07-listings.adoc#, Listings>>
* <<00-index/08-admonitions.adoc#, Admonitions>>
* <<00-index/09-external-links.adoc#, External Links>>
* <<00-index/10-plantuml.adoc#, PlantUML>>
* <<00-index/11-attachments.adoc#, Attachments>>
* <<00-index/12-table-of-contents.adoc#, Table of Contents>>
* <<00-index/13-additional-features.adoc#, Additional Features>>

The Confluence Publisher uses AsciidoctorJ and therefore supports documentation written using the Asciidoctor syntax.
See link:http://asciidoctor.org/docs/user-manual/[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 <<00-index/02-includes.adoc#, Includes>>,
<<00-index/06-images.adoc#, Images>> and <<00-index/10-plantuml.adoc#, PlantUML>> for more information about resource
file path resolution.

[NOTE]
====
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.
====

[NOTE]
====
Currently, the ordering of child pages cannot be influenced due to missing support in the Confluence REST API (see
https://jira.atlassian.com/browse/CRA-1276 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:

[source,xml]
.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`:

[source, xml]
.settings.xml
----
<settings>
...
  <servers>
...
    <server>
      <id>myServerId</id>
      <username>myusername</username>
      <password><PASSWORD></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, the root URL is https://<project>.atlassian.net/wiki.
| 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 https://hc.apache.org/httpcomponents-client-4.5.x/current/httpclient/apidocs/org/apache/http/impl/client/HttpClientBuilder.html[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)

| 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:_ Overrules username defined by serverId, when set in conjunction with serverId
| mandatory, if serverId is not specified

| 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 ("").
  +
  +
  _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 https://maven.apache.org/guides/mini/guide-encryption.html[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
a| 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
a| 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.
| 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`)

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

| proxyPassword
| The 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:

[source,xml]
----
<!-- ... -->
<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:

[source,xml]
----
<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`.

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

[NOTE]
====
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 USERNAME=username \
   -e PASSWORD=<PASSWORD> \
   -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
    ...
  script:
    - publish.sh
----

{'fraction_non_alphanumeric': 0.09052902395883583, 'fraction_numerical': 0.007911239749155813, 'mean_word_length': 4.0423220366466674, 'pattern_counts': {'":': 4, '<': 289, '<?xml version=': 0, '>': 289, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 30}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1214054', 'n_tokens_mistral': 9113, 'n_tokens_neox': 8561, 'n_words': 3335}