Confluence Docs as Code Action
This Action publishes your MkDocs documentation to your Atlassian Confluence Cloud wiki.
Features
- Publishes only new or changed pages
- Optionally force update all pages
- Force update all pages on new major/minor release
- Converts internal links to Confluence links
- Uploads images as Confluence page attachments
- Converts fenced code blocks to Confluence code macros
- Renders graphs:
- Mermaid see
mermaid_renderer
for available options - PlantUML see
plantuml_renderer
for available options
- Mermaid see
- Add a common prefix to all page titles
- Restricts page update to confluence_user
Limitations
- Does not fully support nesting in the
nav
section of the MkDocs Configuration, flattens all pages to one level. - Does not publish pages not described in the
nav
section.
Requirements
In order to use this action to your repository you need to meet the following requirements.
MkDocs Configuration
Your repository is expected to include an mkdocs.yml
configuration file (in the root dir) with the following settings:
site_name
repo_url
nav
site_name: Fixture Site Name
repo_url: https://github.com/fixture-account/fixture-repo
nav:
- Page title: page.md
- Some other page title: other-page.md
- Yet an other page title: more/page.md
For more MkDocs configuration options check out the official documentation.
Atlassian Confluence
In order for the action to be able to publish your documents to a Confluence space you need to create an API token for a user with read/write access to that space.
It is highly recommended that you create a dedicated (robot) user just for this purpose.
Refer to Atlassian documentation on managing API tokens.
Inputs
confluence_tenant
Required. Typically this is your is your organization name that is used as a subdomain to your Atlassian cloud url, for example if your Atlassian url is https://my-organization.atlassian.net
use my-organization
as confluence_tenant
confluence_space
Required. The key of the space that will host your documentation. If your space has an auto-generated key, navigate to your space an you can find it in the URL on your browser's location.
For example if your space URL is: https://my-organization.atlassian.net/wiki/spaces/~55700475998cb3f40a
Use ~55700475998cb3f40a
as your confluence_space
.
confluence_user
Required. The username of the user that will be used to publish to Confluence (see also Atlassian Confluence section)
confluence_token
Required. The API token of the user that will be used to publish to Confluence (see also Atlassian Confluence section)
confluence_parent_page
Optional. The title of an existing page in the same Confluence space to be used as a parent for your documentation.
For example if your space has a page with title "My Documentation" and you want to use it as the parent for your published documents, then set confluence_parent_page
to 'My Documentation'
confluence_title_prefix
Optional. When set, this prefix will be prepended to all confluence page titles except your root page which is titled according to the site_name
in your MkDocs configuration.
For example, if you have a page with title 'My Page'
and the confluence_title_prefix
is set to 'FOO:'
then the page will be created to confluence with the title 'FOO: My Page'
.
This could be useful in cases that you want to publish multiple repos to the same confluence space, which requires each page title to be unique.
confluence_force_update
Optional. When set to yes
all pages will be published to confluence including those that have not changed. Can be handy when used with the workflow_dispatch
event as shown in the example usage below.
confluence_cleanup
Optional. When set to yes
all pages will be deleted from confluence. Can be handy when used with the workflow_dispatch
event as shown in the example usage below.
kroki_enabled
(Deprecated)
Optional. When set to yes
enables rendering of Mermaid and PlantUML graphs into images (.png
) via Kroki.io service.
Defaults to yes
.
⚠️ Will be removed in future releases in favour of the more fine-grained
mermaid_renderer
andplantuml_renderer
options below.
kroki_host
Optional. When set this host is used as a kroki server instead of the default one.
Defaults to https://kroki.io
mermaid_renderer
Optional. Can be one of:
'none'
: will not render'kroki'
: will use Kroki.io to render aspng
'mermaid-plugin'
: will upload the diagram source and render using Mermaid Diagrams for Confluence add-on
⚠️ If not explicitly defined, falls back to
kroki_enabled
option in order to provide backwards compatibility
plantuml_renderer
Optional. Can be one of:
'none'
: will not render'kroki'
: will use Kroki.io to render aspng
'plantuml'
: will use plantuml.com to render aspng
⚠️ If not explicitly defined, falls back to
kroki_enabled
option in order to provide backwards compatibility
Example usage
# File: .github/workflows/publish_to_confluence.yml
name: Publish MkDocs to Confluence
on:
push:
branches:
- master
paths:
- "docs/**"
- mkdocs.yml
workflow_dispatch:
inputs:
confluence_force_update:
description: 'Force update all pages (yes/no)?'
required: false
default: 'no'
confluence_cleanup:
description: 'Delete all pages (yes/no)?'
required: false
default: 'no'
jobs:
publish-to-confluence:
runs-on: ubuntu-latest
steps:
- name: Checkout Source
uses: actions/checkout@v3
- name: Publish to Confluence
uses: Workable/confluence-docs-as-code@v1.5.0
with:
confluence_tenant: 'Your Confluence Account Name'
confluence_space: 'The Confluence Space Key'
confluence_user: ${{ secrets.CONFLUENCE_USER }}
confluence_token: ${{ secrets.CONFLUENCE_TOKEN }}
confluence_parent_page: 'The title of the page to use as parent' # Optional
confluence_title_prefix: 'My Prefix:' # Optional
confluence_force_update: ${{ github.event.inputs.confluence_force_update }} # Optional
confluence_cleanup: ${{ github.event.inputs.confluence_cleanup }} # Optional
kroki_enabled: 'no' # Optional
kroki_host: 'https://kroki.io' # Optional
mermaid_renderer: 'none' # Optional
plantuml_renderer: 'none' # Optional