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.
1 maintainer
Release files for md2cf 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| md2cf-0.2.1.tar.gz | 5.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| md2cf-0.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 13.4 kB
Release files / md2cf-0.2.1.tar.gz
| Download URL | md2cf-0.2.1.tar.gz |
|---|---|
| Size | 5.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f496085225b5c32db5a9f9de27593bc609e1802086f188ad70e9b30f325a005f
|
|
BLAKE2b-256 checksum How to use checksums |
a24e3b81d52eb195cac837d55cb724de88db289e936ec67d93795ecba127a043
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.6.8
|
Release files / md2cf-0.2.1-py3-none-any.whl
| Download URL | md2cf-0.2.1-py3-none-any.whl |
|---|---|
| Size | 7.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aa12ba5c01b21a86523342af37aa46113a339be5c988e16f0849f81efdfa490e
|
|
BLAKE2b-256 checksum How to use checksums |
2a8b73c7bb322f48c4244fec076459922a8e6dbc8356effa50aaa3a9b5192761
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.6.8
|
