/antora-confluence

Plugin to publish your Antora docs to Confluence

Primary LanguageTypeScriptApache License 2.0Apache-2.0

Captain - Confluence Antora Plugin To Aid Integration Nicely

Build

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

Captain Logo

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.

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

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: antora-confluence
      confluence-api: https://<redacted>.atlassian.net
      confluence-space: my-spacekey

For full reference, please head over to the docs.

State Management

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

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

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

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.