md2cf 0.2.1

Convert Markdown documents to Confluence

md2cf

A library to convert documents written in Markdown to Confluence Storage format, and optionally upload them to a Confluence Server instance.

Features

• 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.

Installation

pip install md2cf

Basic Usage

Renderer

Use the 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_data)

API

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>', message='Created page')

page = confluence.get_page(title='Test page', space_key='TEST')
confluence.update_page(page=page, body='New content', message='Changed page contents')

Upload script

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. http://confluence.example.com/rest/api)
• The username to use for logging into the instance
• The corresponding password
• The space on which to upload the page
• The file(s) 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.

In addition, 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: CONFLUENCE_HOST, CONFLUENCE_USERNAME, and CONFLUENCE_PASSWORD.

The title of the page will be the first top-level header found in the document (i.e. the first # header), or the filename if there are no top-level headers.

If you want to upload the page under a specific parent, supply the parent's page ID as the --parent parameter.

You can also optionally specify an update message to describe the change you just made by using the --message parameter.

If you want to update a page by page ID, use the --page-id option. This allows you to update the page's title, or to update a page with a title that is hard to use as a parameter.