conflutora/README.md

Provider to convert and publish Antora documentation on Confluence

# Conflutora

## Confluence Antora Plugin To Aid Integration Nicely

*The code of the plugin was heavily inspired by [antora-confluence](https://github.com/PacoVK/antora-confluence)*

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

# Description

This plugin aims to automatically publish your [Antora](https://antora.org/) docs into Confluence.
By doing this we leverage the power of Confluence and the Confluence REST API to create and update pages in Confluence, which is a great way to keep your documentation up-to-date and in sync with your code.
Most non technical stakeholders are using Confluence, so this plugin aims to make it easy for them to contribute to your documentation.


## Installation

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

```sh
npm install -D conflutora
```

## Usage

> INFO: The default output provider `fs` in mandatory for the Confluence provider. 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`:

```yaml
output:
  destinations:
    - provider: fs
    - provider: conflutora
      confluence-url: https://<redacted>.atlassian.net
      confluence-space-key: my-spacekey
```

For full reference, please head over to the [docs](https://docs.antora.org/antora/latest/playbook/configure-output/).


### Configuration

| Option                 | Description                                                                                                           | Info                       |
| -----------------------| --------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| confluence-url         | URL to your Confluence API endpoint                                                                                   | **required**               |
| confluence-space-key   | The Confluence space key to publish the pages to                                                                      | **required**               |
| confluence-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 |


```yaml
output:
  clean: true
  dir: ./docs/site # Mandatory for the Confluence provider
  destinations:
    - provider: fs
    - provider: "conflutora"
      confluence-url: https://<redacted>.atlassian.net
      confluence-space-key: my-spacekey
      confluence-ancestor-id: 123456
```

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