This Action publishes your MkDocs documentation to your Atlassian Confluence Cloud wiki.
- 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
- 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.
In order to use this action to your repository you need to meet the following requirements.
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.
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.
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
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
.
Required. The username of the user that will be used to publish to Confluence (see also Atlassian Confluence section)
Required. The API token of the user that will be used to publish to Confluence (see also Atlassian Confluence section)
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'
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.
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.
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.
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-grainedmermaid_renderer
andplantuml_renderer
options below.
Optional. When set this host is used as a kroki server instead of the default one. See kroki docs on how to setup a local kroki instance.
Defaults to https://kroki.io
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 tokroki_enabled
option in order to provide backwards compatibility
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 tokroki_enabled
option in order to provide backwards compatibility
# 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/[email protected]
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