Captain - Confluence Antora Plugin To Aid Integration Nicely

NOTE: This plugin is in an early phase. It is still in development.

This plugin is designed to help to publish your Antora docs into Confluence. The main reason is, that we want to have a single source of truth for our documentation. We want to write our documentation in AsciiDoc and publish it to Confluence as some of our Stakeholders are using Confluence.

The captain offers the following options:

• Publish your whole Antora docs to Confluence
• Publish only selected pages/ folders, by using filters
• Control where the docs should be published by setting an overall parent page in Confluence
• Decide if you want to inform your readers that those pages are generated by automation by applying a banner.

References and Kudos

The code of the plugin was heavily inspired by docToolchain, a swiss-army knife for docs-as-code.

How it works

The plugin uses the Confluence REST API to create and update pages in Confluence. It uses the confluence-space to determine where to publish the pages. The plugin will create a page for each Antora page and will use the title and content of the page to create the Confluence page.

The plugin will also create a page tree to reflect the structure of the Antora pages in Confluence. Each Antora module version will be a child page of the page tree and the pages will be children of the module pages.

Example:

- module-a
  - 1.0
    - user-guide
      - manual.html
- module-b
  - 1.0
    - user-guide
      - manual.html

In the above example, we have two modules module-a and module-b. Each module has a page called manual.html under the user-guide directory. Both manual.html have the same pageTitle User manual defined in their source Asciidoc files. The plugin will create the following page tree in Confluence:

- module-a
  - [module-a]-1.0
    - [module-a]-user-guide
      - [module-a]-manual
- module-b
  - [module-b]-1.0
    - [module-b]-user-guide
      - [module-b]-manual

You can customize the page tree by using the mapper option. This will allow you to map Antora pages to Confluence pages and control the structure of the page tree.

Installation

To install the plugin, you can use the following command in your Antora project:

npm install -D antora-confluence

or using yarn:

yarn add -D antora-confluence

Usage

INFO: Captain relies on the default output provider fs. Make sure to have the fs provider in your playbook.yml file.

To use the plugin, you need to add it to your Antora project. You can do this by adding the following to your output section in playbook.yml:

output:
  destinations:
    - provider: fs
    - provider: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey

If you would like to have more than one instance you can have more than one captain-name to track the state inside multiple ancestors.

output:
  destinations:
    - provider: antora-confluence
      editor-version: v1
      show-banner: true # Warns that the page isn't editable and may be overwritten
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: EX # Example space
      ancestor-id: 1234567890 # Page 1 under example space
      captain-name: State (Page 1)
      exclude-files:
        - "!page-1-*/**" # Exclude everything except antora names starting page-1-
      mapper:
        - path: page-1-example/latest
          target: Example
        - path: page-1-example2/latest
          target: Example Two
    - provider: antora-confluence
      editor-version: v1
      show-banner: true # Warns that the page isn't editable and may be overwritten
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: EX # Example space
      ancestor-id: 1234567891 # Page 2 under example space
      captain-name: State (Page 2)
      exclude-files:
        - "!page-2-*/**" # Exclude everything except antora names starting page-2-
      mapper:
        - path: page-2-placeholder/latest
          target: Placeholder

For full reference, please head over to the docs.

Info: If you are using Confluence on-prem, your confluence-api can either require a context path or not. If your Confluence API is available at https://confluence.example.com/docs, you need to specify the confluence-api as https://<redacted>.com/confluence/docs. If your Confluence API is available at https://confluence.example.com/rest/api, you need to specify the confluence-api as https://confluence.example.com/rest/api (mind there is no context path in the URL). Confluence Cloud does not require a context path, it always uses /wiki as context.

State Management

Info: Prior to 0.4.0 the Captain supported only one state file. If you are upgrading from a version prior to 0.4.0 and want to use the feature of multiple state files, please make sure to set the state file for already existing docs to the default Captain State Page.

The Captain will keep track of the pages it has created in Confluence. This is to ensure that it does not create duplicate pages and to detect page renames. The state is stored in a dedicated page with DRAFT status called Captain State Page (or the name of your choosing) in the root of your Space, or if defined, right under your starting point defined via ancestor-id option. If you delete this page, the Captain will recreate it, but it will assume no page exist in the target space. This may lead to errors and the only solution is to delete all Pages managed by Captain. Per default Confluence Pages created in DRAFT status are only visible to the owner.

Configuration

Option	Description	Info
confluence-api	URL to your Confluence API endpoint	required
confluence-space	The Confluence space key to publish the pages to	required
editor-version	The Confluence editor version to use to create pages	v1 (default) / v2
filters	Specify paths or files that you want to publish to Confluence	[] (default)
ancestor-id	Specify the overall parent page for your docs. Needs to be the pageId of the parent page, not the DisplayName.	defaults to the space root
show-banner	Specify if all your pages should contain an info banner, that this pages were created by automation and changes may be lost.	false (default)
mapper	Specify a custom mapper to map the Antora pages to Confluence pages.	[] (default)
exclude-files	Specify files that should be excluded from the publishing process. Wildcards and Glob-patterns are supported	[] (default)
captain-name	Override the name of the Captain State Page, useful if you have multiple antora-confluence providers in the same space	"Captain State Page" (default)

Using Mappers

You can specify a list of custom mappers to map the Antora pages to Confluence pages. A mapper consists of path and target. The path is actually the Antora page path that you want to map and the target is the Confluence page title that you want to map to.

Info: The below example would map the Antora page module-a/1.0/example/manual to the Confluence page Manual.

output:
  destinations:
    - provider: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey
      mapper:
        - path: module-a/1.0/example/manual
          target: Manual

If you would not specify a mapper, the example above would create the following page tree in Confluence:

• module-a
  • 1.0
    • example
      • manual
        • AnyPage-That-exists-underneath-manual-directory

Using the mapper, you can control the page tree structure in Confluence. Hence, sticking to the example above, the page tree would look like this:

• Manual
  • AnyPage-That-exists-underneath-manual-directory

Using Filters

You can specify filters to only push certain files or folders instead of all. The filters must match the natural output structure of Antora. You can specify as many filters as you need. There are two different types of filters: PathFilter and FileFilter.

Info: If the filtered pages do have cross-references to pages that are not within your filter, you may encounter broken links on Confluence. You are responsible that the subset of pages, applied through your filters are self-contained and all dependencies are covered.

To filter on a specific directory:

Info: The below example would only publish all files within the folders module-a/1.0/example and module-c/2.1/foo

output:
  destinations:
    - provider: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey
      filters:
        - path: module-a/1.0/example
        - path: module-c/2.1/foo

To filter on specific files:

Info: The below example would only publish the three files, specfied by the filter

output:
  destinations:
    - provider: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey
      filters:
        - files:
            - module-a/1.0/example/manual.html
            - module-a/1.0/example/troubleshoot.html
            - module-c/1.0/foo/examples.html

Using Excludes

You can specify files and folders that should be excluded from the publishing process. Wildcards and Glob-patterns are supported.

output:
  destinations:
    - provider: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey
      exclude-files:
        - "**/*-tpl.html"
        - "**/*_template.html"

Authentication

You can authenticate with the Confluence API using the following methods:

Personal Access Token (PAT)

Info: PAT is only available for self-hosted Confluence.

The plugin uses CONFLUENCE_PAT to authenticate with the Confluence API via token. You can set this value in the environment variables.

To read more about how to create a PAT, please refer to the official documentation.

API token

The plugin uses CONFLUENCE_USERNAME and CONFLUENCE_PASSWORD to authenticate with the Confluence API via basic auth. You can set these values in the environment variables.

To read more about how to create an API token, please refer to the official documentation.

Info: The order above is the priority. If you set both, the plugin will use the PAT.

Disable this plugin at runtime

You can disable the plugin at runtime by setting the environment variable SKIP_CONFLUENCE to true. This will prevent the plugin from running. As of now the actual value of the environment variable is not evaluated, only the presence of the variable is checked.

Example

SKIP_CONFLUENCE=1 yarn generate-sites

The command above will not publish to Confluence, but generate the site as usual. This may be useful in CI/CD environments to test if the docs are building.

Logging

You can set the log level of the plugin by setting the LOG_LEVEL environment variable. The following levels are available:

• debug
• info (default)
• warn

Planned Roadmap

• Handle embedded images

Contributing

Contributions in any area are welcome. Please open an issue or a pull request.