Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pacovk/antora-confluence

Plugin to publish your Antora docs to Confluence
https://github.com/pacovk/antora-confluence

antora antora-extension asciidoc confluence docs-as-code npm-package

Last synced: about 3 hours ago
JSON representation

Plugin to publish your Antora docs to Confluence

Host: GitHub
URL: https://github.com/pacovk/antora-confluence
Owner: PacoVK
License: apache-2.0
Created: 2024-02-22T10:41:49.000Z (7 months ago)
Default Branch: main
Last Pushed: 2024-09-18T08:55:22.000Z (15 days ago)
Last Synced: 2024-09-18T11:44:18.952Z (15 days ago)
Topics: antora, antora-extension, asciidoc, confluence, docs-as-code, npm-package
Language: TypeScript
Homepage:
Size: 787 KB
Stars: 12
Watchers: 3
Forks: 3
Open Issues: 16
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md

Awesome Lists containing this project

README

# Captain - Confluence Antora Plugin To Aid Integration Nicely

[![Build](https://github.com/PacoVK/antora-confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/PacoVK/antora-confluence/actions/workflows/ci.yml)

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

![Captain Logo](assets/captain.png)

This plugin is designed to help to publish your [Antora](https://antora.org/) 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](https://doctoolchain.org/docToolchain/v2.0.x/), 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:

```sh
npm install -D antora-confluence
```

or using yarn:

```sh
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`:

```yaml
output:
destinations:
- provider: fs
- provider: antora-confluence
confluence-api: https://.atlassian.net
confluence-space: my-spacekey
```

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

> 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://.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

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

```yaml
output:
destinations:
- provider: antora-confluence
confluence-api: https://.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`

```yaml
output:
destinations:
- provider: antora-confluence
confluence-api: https://.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

```yaml
output:
destinations:
- provider: antora-confluence
confluence-api: https://.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.

```yaml
output:
destinations:
- provider: antora-confluence
confluence-api: https://.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](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html#UsingPersonalAccessTokens-CreatingPATsintheapplication).

#### 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](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account).

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