Publish Markdown files to Confluence wiki
Project description
Publish Markdown files to Confluence wiki
Contributors to software projects typically write documentation in Markdown format and host Markdown files in collaborative version control systems (VCS) such as GitHub or GitLab to track changes and facilitate the review process. However, not everyone at a company has access to VCS, and documents are often circulated in Confluence wiki instead.
Replicating documentation to Confluence by hand is tedious, and a lack of automated synchronization with the project repositories where the documents live leads to outdated documentation.
This Python package
- parses Markdown files,
- converts Markdown content into the Confluence Storage Format (XHTML),
- invokes Confluence API endpoints to upload images and content.
Features
- Sections and subsections
- Text with bold, italic,
monospace
, underline andstrikethrough - Link to external locations
- Ordered and unordered lists
- Code blocks (e.g. Python, JSON, XML)
- Image references (uploaded as Confluence page attachments)
- Table of Contents
Getting started
In order to get started, you will need
- your organization domain name (e.g.
instructure.atlassian.net
), - your Confluence username (e.g.
levente.hunyadi@instructure.com
), - a Confluence API token (a string of alphanumeric characters), and
- the space key in Confluence (e.g.
DAP
) you are publishing content to.
Obtaining an API token
- Log in to https://id.atlassian.com/manage/api-tokens.
- Click Create API token.
- From the dialog that appears, enter a memorable and concise Label for your token and click Create.
- Click Copy to clipboard, then paste the token to your script, or elsewhere to save.
Setting up the environment
Confluence organization URL, username, API token and space key can be specified at runtime or set as Confluence environment variables (e.g. add to your ~/.profile
on Linux, or ~/.bash_profile
or ~/.zshenv
on MacOS):
export CONFLUENCE_DOMAIN='instructure.atlassian.net'
export CONFLUENCE_USER_NAME='levente.hunyadi@instructure.com'
export CONFLUENCE_API_KEY='0123456789abcdef'
export CONFLUENCE_SPACE_KEY='DAP'
On Windows, these can be set via system properties.
The tool requires appropriate permissions in Confluence in order to invoke endpoints.
Associating a Markdown file with a wiki page
Each Markdown file is associated with a Confluence wiki page with a Markdown comment:
<!-- confluence-page-id: 85668266616 -->
The above tells the tool to synchronize the Markdown file with the given Confluence page ID. This implies that the Confluence wiki page must exist such that it has an ID. The comment can be placed anywhere in the source file.
Setting the Confluence space
If you work in an environment where there are multiple Confluence spaces, and some Markdown pages may go into one space, whereas other pages may go into another, you can set the target space on a per-document basis:
<!-- confluence-space-key: DAP -->
This overrides the default space set via command-line arguments or environment variables.
Setting generated-by prompt text for wiki pages
In order to ensure readers are not editing a generated document, the tool adds a warning message at the top of the Confluence page as an info panel. You can customize the text that appears. The text can contain markup as per the Confluence Storage Format, and is emitted directly into the info panel macro.
Provide generated-by prompt text in the Markdown file with a tag:
<!-- generated-by: Do not edit! Check out the <a href="https://example.com/project">original source</a>. -->
Alternatively, use the --generated-by GENERATED_BY
option. The tag takes precedence.
Running the tool
You execute the command-line tool md2conf
to synchronize the Markdown file with Confluence:
$ python3 -m md2conf example.md
Use the --help
switch to get a full list of supported command-line options:
$ python3 -m md2conf --help
usage: md2conf [-h] [-d DOMAIN] [-u USERNAME] [-a APIKEY] [-s SPACE] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
[--generated-by GENERATED_BY] [--no-generated-by]
mdfile
positional arguments:
mdfile Markdown file to convert and publish.
options:
-h, --help show this help message and exit
-d DOMAIN, --domain DOMAIN
Confluence organization domain.
-u USERNAME, --username USERNAME
Confluence user name.
-a APIKEY, --apikey APIKEY
Confluence API key. Refer to documentation how to obtain one.
-s SPACE, --space SPACE
Confluence space key for pages to be published. If omitted, will default to user space.
-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
Use this option to set the log verbosity.
--generated-by GENERATED_BY
Add prompt to pages (default: 'This page has been generated with a tool.').
--no-generated-by Do not add 'generated by a tool' prompt to pages.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for markdown-to-confluence-0.1.7.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 887786fdab6006d1887dc75edb171458d7a64f3bd73e3d28e72f4b44144b3a34 |
|
MD5 | 582938118d05f9b5d2d6021d4d6dbdf9 |
|
BLAKE2b-256 | f3db32f3cdc444b8d198207f2b1a7d55042eafea865cbc8be9d0aae4535394ae |
Hashes for markdown_to_confluence-0.1.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 65557e233309a7268c3a5056f34ea2a977f418d3158ef269d578f573e031ff24 |
|
MD5 | 31a291f39fdd6964394e628a0972f4cf |
|
BLAKE2b-256 | 56856d550979dea1422241f850ec95b04faaeafb7a249c8edb6f7a41bde908bb |