{"id":15679293,"url":"https://github.com/pacovk/antora-confluence","last_synced_at":"2025-04-15T06:17:00.413Z","repository":{"id":223862033,"uuid":"761708414","full_name":"PacoVK/antora-confluence","owner":"PacoVK","description":"Plugin to publish your Antora docs to Confluence","archived":false,"fork":false,"pushed_at":"2025-04-13T19:34:51.000Z","size":887,"stargazers_count":16,"open_issues_count":24,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-15T06:16:52.755Z","etag":null,"topics":["antora","antora-extension","asciidoc","confluence","docs-as-code","npm-package"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PacoVK.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"pacoVK","custom":["https://www.paypal.com/donate/?hosted_button_id=NC846BADKGTJG"]}},"created_at":"2024-02-22T10:41:49.000Z","updated_at":"2025-04-08T00:05:24.000Z","dependencies_parsed_at":"2024-08-03T12:49:54.370Z","dependency_job_id":"c28cb687-51c6-45fc-b56f-4e2fba90873f","html_url":"https://github.com/PacoVK/antora-confluence","commit_stats":null,"previous_names":["pacovk/antora-to-confluence","pacovk/captain"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PacoVK%2Fantora-confluence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PacoVK%2Fantora-confluence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PacoVK%2Fantora-confluence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PacoVK%2Fantora-confluence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PacoVK","download_url":"https://codeload.github.com/PacoVK/antora-confluence/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016644,"owners_count":21198833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antora","antora-extension","asciidoc","confluence","docs-as-code","npm-package"],"created_at":"2024-10-03T16:28:21.271Z","updated_at":"2025-04-15T06:17:00.393Z","avatar_url":"https://github.com/PacoVK.png","language":"TypeScript","funding_links":["https://github.com/sponsors/pacoVK","https://www.paypal.com/donate/?hosted_button_id=NC846BADKGTJG"],"categories":[],"sub_categories":[],"readme":"# Captain - Confluence Antora Plugin To Aid Integration Nicely\n\n[![Build](https://github.com/PacoVK/antora-confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/PacoVK/antora-confluence/actions/workflows/ci.yml)\n\n\u003e NOTE: This plugin is in an early phase. It is still in development.\n\n![Captain Logo](assets/captain.png)\n\nThis 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.\n\nThe captain offers the following options:\n\n- Publish your whole Antora docs to Confluence\n- Publish only selected pages/ folders, by using filters\n- Control where the docs should be published by setting an overall parent page in Confluence\n- Decide if you want to inform your readers that those pages are generated by automation by applying a banner.\n\n## References and Kudos\n\nThe code of the plugin was heavily inspired by [docToolchain](https://doctoolchain.org/docToolchain/v2.0.x/), a swiss-army knife for docs-as-code.\n\n## How it works\n\nThe 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.\n\nThe 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.\n\nExample:\n\n```\n- module-a\n  - 1.0\n    - user-guide\n      - manual.html\n- module-b\n  - 1.0\n    - user-guide\n      - manual.html\n```\n\nIn 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.\nBoth `manual.html` have the same pageTitle `User manual` defined in their source Asciidoc files. The plugin will create the following page tree in Confluence:\n\n```\n- module-a\n  - [module-a]-1.0\n    - [module-a]-user-guide\n      - [module-a]-manual\n- module-b\n  - [module-b]-1.0\n    - [module-b]-user-guide\n      - [module-b]-manual\n```\n\nYou 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.\n\n## Installation\n\nTo install the plugin, you can use the following command in your Antora project:\n\n```sh\nnpm install -D antora-confluence\n```\n\nor using yarn:\n\n```sh\nyarn add -D antora-confluence\n```\n\n## Usage\n\n\u003e INFO: Captain relies on the default output provider `fs`. Make sure to have the `fs` provider in your `playbook.yml` file.\n\nTo 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`:\n\n```yaml\noutput:\n  destinations:\n    - provider: fs\n    - provider: antora-confluence\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: my-spacekey\n```\n\nIf you would like to have more than one instance you can have more than one captain-name to track the state inside multiple ancestors.\n\n```yaml\noutput:\n  destinations:\n    - provider: antora-confluence\n      editor-version: v1\n      show-banner: true # Warns that the page isn't editable and may be overwritten\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: EX # Example space\n      ancestor-id: 1234567890 # Page 1 under example space\n      captain-name: State (Page 1)\n      exclude-files:\n        - \"!page-1-*/**\" # Exclude everything except antora names starting page-1-\n      mapper:\n        - path: page-1-example/latest\n          target: Example\n        - path: page-1-example2/latest\n          target: Example Two\n    - provider: antora-confluence\n      editor-version: v1\n      show-banner: true # Warns that the page isn't editable and may be overwritten\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: EX # Example space\n      ancestor-id: 1234567891 # Page 2 under example space\n      captain-name: State (Page 2)\n      exclude-files:\n        - \"!page-2-*/**\" # Exclude everything except antora names starting page-2-\n      mapper:\n        - path: page-2-placeholder/latest\n          target: Placeholder\n```\n\nFor full reference, please head over to the [docs](https://docs.antora.org/antora/latest/playbook/configure-output/).\n\n\u003e 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://\u003credacted\u003e.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.\n\n### State Management\n\n\u003e 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`.\n\nThe 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.\n\n### Configuration\n\n| Option           | Description                                                                                                                  | Info                           |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |\n| confluence-api   | URL to your Confluence API endpoint                                                                                          | **required**                   |\n| confluence-space | The Confluence space key to publish the pages to                                                                             | **required**                   |\n| editor-version   | The Confluence editor version to use to create pages                                                                         | v1 (default) / v2              |\n| filters          | Specify paths or files that you want to publish to Confluence                                                                | [] (default)                   |\n| 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     |\n| 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)                |\n| mapper           | Specify a custom mapper to map the Antora pages to Confluence pages.                                                         | [] (default)                   |\n| exclude-files    | Specify files that should be excluded from the publishing process. Wildcards and Glob-patterns are supported                 | [] (default)                   |\n| 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) |\n\n#### Using Mappers\n\nYou 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.\n\n\u003e Info: The below example would map the Antora page `module-a/1.0/example/manual` to the Confluence page `Manual`.\n\n```yaml\noutput:\n  destinations:\n    - provider: antora-confluence\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: my-spacekey\n      mapper:\n        - path: module-a/1.0/example/manual\n          target: Manual\n```\n\nIf you would not specify a mapper, the example above would create the following page tree in Confluence:\n\n- module-a\n  - 1.0\n    - example\n      - manual\n        - AnyPage-That-exists-underneath-manual-directory\n\nUsing the mapper, you can control the page tree structure in Confluence. Hence, sticking to the example above, the page tree would look like this:\n\n- Manual\n  - AnyPage-That-exists-underneath-manual-directory\n\n#### Using Filters\n\nYou 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`.\n\n\u003e 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.\n\nTo filter on a **specific directory**:\n\n\u003e Info: The below example would only publish all files within the folders `module-a/1.0/example` and `module-c/2.1/foo`\n\n```yaml\noutput:\n  destinations:\n    - provider: antora-confluence\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: my-spacekey\n      filters:\n        - path: module-a/1.0/example\n        - path: module-c/2.1/foo\n```\n\nTo filter on **specific files**:\n\n\u003e Info: The below example would only publish the three files, specfied by the filter\n\n```yaml\noutput:\n  destinations:\n    - provider: antora-confluence\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: my-spacekey\n      filters:\n        - files:\n            - module-a/1.0/example/manual.html\n            - module-a/1.0/example/troubleshoot.html\n            - module-c/1.0/foo/examples.html\n```\n\n#### Using Excludes\n\nYou can specify files and folders that should be excluded from the publishing process. Wildcards and Glob-patterns are supported.\n\n```yaml\noutput:\n  destinations:\n    - provider: antora-confluence\n      confluence-api: https://\u003credacted\u003e.atlassian.net\n      confluence-space: my-spacekey\n      exclude-files:\n        - \"**/*-tpl.html\"\n        - \"**/*_template.html\"\n```\n\n### Authentication\n\nYou can authenticate with the Confluence API using the following methods:\n\n#### Personal Access Token (PAT)\n\n\u003e Info: PAT is only available for self-hosted Confluence.\n\nThe plugin uses `CONFLUENCE_PAT` to authenticate with the Confluence API via token. You can set this value in the environment variables.\n\nTo 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).\n\n#### API token\n\nThe 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.\n\nTo 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).\n\n\u003e Info: The order above is the priority. If you set both, the plugin will use the PAT.\n\n### Disable this plugin at runtime\n\nYou 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.\n\nExample\n\n```\nSKIP_CONFLUENCE=1 yarn generate-sites\n```\n\nThe 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.\n\n#### Logging\n\nYou can set the log level of the plugin by setting the `LOG_LEVEL` environment variable. The following levels are available:\n\n- debug\n- info (**default**)\n- warn\n\n## Planned Roadmap\n\n- [ ] Handle embedded images\n\n## Contributing\n\nContributions in any area are welcome. Please open an issue or a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacovk%2Fantora-confluence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpacovk%2Fantora-confluence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpacovk%2Fantora-confluence/lists"}