Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Convert Markdown documents to Confluence

Project description

md2cf

image

image

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for md2cf, version 0.2.2
Filename, size File type Python version Upload date Hashes
Filename, size md2cf-0.2.2-py3-none-any.whl (7.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size md2cf-0.2.2.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page