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!
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.
To run this script, you need to install two libraries:
These libraries are already listed in the file requirements.txt
It is recommended to install all libraries in Python Virtualenv
Create a Virtualenv with the command
python3 -m venv venv...and activate
source ./venv/bin/activateAfter activating the Virtualenv, install the dependencies from the requirements.txt file using pip:
pip install -r requirements.txtThe preparation is complete, you can run 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.
| 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. |
Along with standart markdown syntax, this script enables 3 additional extensions:
Extension documentation: Tables
Use as usual :)
| First Header | Second Header |
| ------------ | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Extension documentation: Fenced Code Blocks
Use as usual. Note, you can define code's language. It's hard to provide example here :)
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:
infodangerimportantnote
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