Markdown to Confluence

↗️️ Click at the [bullet list icon] at the top right corner of the Readme visualization for the github generated table of contents.

This script can convert Markdown file and publish it to Confluence through REST API

Warning. The search for an existing page is done by title, so if the title has been changed, the page will not be found and a new one will be created!

Note. We do not support links local images!

Run in a docker container

Image available on DockerHub:

docker pull thunderspb/md2confluence:latest

and on GitHub Container Registry:

docker pull ghcr.io/thunder-spb/md2confluence:latest

or

docker run -ti --rm --volume `pwd`:/docs thunderspb/md2confluence:latest --help

pwd is a directory containing your md files.

Preparing to run locally

To run this script, you need to install two libraries:

• Markdown
• requests

These libraries are already listed in the file requirements.txt

It is recommended to install all libraries in Python Virtualenv

Creating virtualenv

Create a Virtualenv with the command

python3 -m venv venv

...and activate

source ./venv/bin/activate

Installing dependencies

After activating the Virtualenv, install the dependencies from the requirements.txt file using pip:

pip install -r requirements.txt

The preparation is complete, you can run the script

Running the script

As usual, help can be obtained by running the script with the --help argument.

For convenience when using in CI/CD, some parameters can be set through environment variables. The environment variables and their names are specified in the script help.

Arguments

Argument	Abbreviation	Description
--markdown-file	-m	Full path to Markdown file
--space	-s	Confluence space key. Can be set through environment variable CONFLUENCE_SPACE. Not required if no --publish argument provided.
--username	-u	Username for authentication in Confluence. This user will be the author of the page. Can be set through environment variable CONFLUENCE_USR. Not required if no --publish argument provided.
--password	-p	Password for authentication in Confluence. Can be set through environment variable CONFLUENCE_PSW. For cloud version this is an API Token for user. Not required if no --publish argument provided.
--url		Confluence address. Can be set through environment variable CONFLUENCE_URL. Not required if no --publish argument provided.
--ancestor-id	-a	(Optional) Page ID which will be used as parent for new page
--title		(Optional) Override title of the page. By default, first found title in Markdown file is used.
--toc		(Optional) Generate Table of Contents for Markdown file. Given without any parameters.
--publish		Markdown file will be converted to HTML and written to stdout. Given without any parameters. Requires input of --space, --username, --password, --url
--force-update		Force update of the page in Confluence even if no changes are found. Requires input of --space, --username, --password, --url, --publish
--out-file	-o	Full path to file, where result of Markdown file conversion will be written
--loglevel	-l	Logging level: INFO, WARN, DEBUG, etc.
--job-url		(Optional) Link to Jenkins Job, which will be added to notification block about automated page creation. Can be set through environment variable JOB_URL. This environment variable is automatically set when run from Jenkins
--repo-url		(Optional) Link to repository, which will be added to notification block about automatic page creation.

Supported blocks

Along with standart markdown syntax, this script enables 3 additional extensions:

• Tables
• Fenced Code Blocks
• Admonition

Tables

Extension documentation: Tables

Use as usual :)

| First Header | Second Header |
| ------------ | ------------- |
| Content Cell | Content Cell  |
| Content Cell | Content Cell  |

Fenced Code Blocks

Extension documentation: Fenced Code Blocks

Use as usual. Note, you can define code's language. It's hard to provide example here :)

Admonition

Extension documentation: Admonition

Common usage:

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

    This is the second paragraph.

Supported types:

• info
• danger
• important
• note

Usage example:

my super text outside admonition

!!! note "my title"
    block 1

    block 2

another super text outside admonition

!!! danger "my title"
    block 1

    block 2