Convert Markdown documents to Confluence
A tool and library to convert documents written in Markdown to Confluence Storage format, and optionally upload them to a Confluence Server instance.
- Convert Markdown documents. The library implements a Mistune renderer that outputs Confluence Storage Format.
- Basic Confluence API support. Embedded micro-implementation of the Confluence Server REST API with basic support for creating and updating pages.
- Upload automation. Includes a small script that can automate the upload process for you.
pip install md2cf
usage: md2cf [-h] [-o HOST] [-u USERNAME] [-p PASSWORD] -s SPACE [-a PARENT_TITLE | -A PARENT_ID] [-t TITLE] [-m MESSAGE] [-i PAGE_ID] [--prefix PREFIX] [--preface-markdown [PREFACE_MARKDOWN] | --preface-file PREFACE_FILE] [--collapse-single-pages] [--beautify-folders | --use-pages-file] [--collapse-empty | --skip-empty] [--dry-run] [file_list [file_list ...]]
In order to upload a document, you'll need to supply at least the following five parameters:
- The hostname of your Confluence instance, including the path to
the REST API (e.g.
- The username to use for logging into the instance
- The corresponding password
- The space in which to publish the page
- The files or directories to be uploaded -- or standard input if the list is missing
Example basic usage:
md2cf --host 'https://confluence.example.com/rest/api' --username foo --password bar --space TEST document.md
Note that entering the password as a parameter on the command line is
generally a bad idea. If you're running the script interactively, you
can omit the
--password parameter and the script will prompt for it.
For the security conscious out there or those who plan on
using this as part of a pipeline, you can also supply the hostname,
username, and password as environment variables:
You can specify multiple files and/or entire folders. If you specify a folder, it will be traversed recursively and all files ending in
.md will be uploaded. See Uploading folders for more information.
If you just want to get a preview of what
md2cf would try to upload, the
--dry-run option will print a list of page data but leave Confluence untouched.
The title of the page can come from a few sources, in order of priority from highest to lowest:
--titlecommand line parameter
titleentry in your document's front matter, i.e. a YAML block delimited by
---lines at the top of the file
--- title: This is a title --- # Rest of the document here
- the first top-level header found in the document (i.e. the first
- the filename if there are no top-level headers.
Note that if you're reading from standard input, you must either specify the title through the command line or have a title in the content as a header or in the front matter.
If you're uploading entire folders, you might want to add a prefix to each page title in order to avoid collisions. You can do this using the
Adding a preface
--preface-file commands allow you to add some text at the top of each page. This is useful
if you're mirroring documentation to Confluence and want people to know that it's going to be overwritten in an automated
The first option allows you to specify markdown text right on the command line, and defaults to a paragraph saying
Contents are auto-generated, do not edit.
The second option takes a path to a markdown file and will prepend its contents to every page. Note that this is parsed separately and added to the body after the main page has been parsed, so it won't influence behaviour tied to the page contents such as title or front matter detection.
If you want to upload the page under a specific parent, you can supply the parent's page ID as the
--parent-id parameter, or its title through the
--parent-title parameter. Note
You can also optionally specify an update message to describe the
change you just made by using the
Updating an existing page
Uploading a page with the same title twice will update the existing one.
If you want to update a page by page ID, use the
--page-id option. This allows you to change the page's title, or to update a page with a title that is annoying to use as a parameter.
md2cf can upload entire folders for you. This can be useful if you want to mirror some in-repo documentation to Confluence.
When uploading entire folders,
md2cf will recursively traverse all subdirectories and upload any
.md file it encounters. Folders will be represented by empty pages in the final upload, since Confluence can only nest pages under other pages. You can modify this behaviour through three command line parameters.
Customizing folder names
Folder names like
dir1 are not particularly nice. If you pass the
all spaces and hyphens in folder names will be replaced with spaces and the first letter will be capitalized, producing
Interesting subsection and
Alternatively, you can create a YAML file called
.pages with the following format in every folder you wish to rename.
If you pass the
--use-pages-file, the folder will be given that title.
title: "This is a fantastic title!"
Collapse single pages
You can collapse directories that only contain one document by passing the
--collapse-single-pages parameter. This means that a folder layout like this:
document.md folder1/ documentA.md documentB.md folder2/ other-document.md
will be uploaded to Confluence like this:
document folder1/ documentA documentB other-document
Dealing with empty folders
You can also modify the behaviour for empty folders. If you specify
--skip-empty, this tree layout:
document.md folder1/ folder2/ folder3/ other-document.md folderA/ interesting-document.md folderB/ folderC/ lonely-document.md
will be uploaded as:
document folder3/ other-document folderA/ interesting-document folderC/ lonely-document
Alternatively, you can specify
--collapse-empty to merge empty folders together with the following result:
document folder1/folder2/folder3/ other-document folderA/ interesting-document folderB/folderC/ lonely-document
md2cf can of course be used as a Python library. It exposes two useful modules: the renderer and the API wrapper.
ConfluenceRenderer class to generate Confluence Storage Format
output from a markdown document.
import mistune from md2cf.confluence_renderer import ConfluenceRenderer renderer = ConfluenceRenderer(use_xhtml=True) confluence_mistune = mistune.Markdown(renderer=renderer) confluence_body = confluence_mistune(markdown_text)
md2cf embeds a teeny-tiny implementation of the Confluence Server REST API that allows you to create, read, and update pages.
from md2cf.api import MinimalConfluence confluence = MinimalConfluence(host='http://example.com/rest/api', username='foo', password='bar') confluence.create_page(space='TEST', title='Test page', body='<p>Nothing</p>', update_message='Created page') page = confluence.get_page(title='Test page', space_key='TEST') confluence.update_page(page=page, body='New content', update_message='Changed page contents')
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size md2cf-1.0.2-py3-none-any.whl (12.9 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size md2cf-1.0.2.tar.gz (11.1 kB)||File type Source||Python version None||Upload date||Hashes View|