confluence.md

Markdown to Confluence - upload any .md files to your Confluence cloud page


Keywords
markdown, confluence, md, atlassian, atlassian-confluence
License
MIT
Install
pip install confluence.md==0.2.2

Documentation

confluence.md

Push markdown files straight to a Confluence page.

What it does?

confluence.md allows you to push any markdown file to Confluence. You can create a new page (under given parent) or update an existing one.

How to install?

It's as easy as:

$ pip install confluence.md

# If the above doesn't work, your `pip` command points to different
# python than installation than `python` command. If so, run:
$ python -m pip install confluence.md

How to use it in command-line?

Markdown to Confluence

Example workflow:

1. Create page

Create a new page under --parent_id:

$ confluence.md --user user@name.net \             # Atlassian username
        --token 9a8dsadsh \                        # API token or --password
        --url https://your-domain.atlassian.net \  # Confluence instance URL
        create \                                   # create or update
        --file README.md \                         # markdown file
        --parent_id 182371 \                       # parent page
        --title "new title"                        # title for a new page
        --add_meta                                 # adds meta to source.md file

2. Verify markdown

The page is created and the file is decorated with metadata:

$ head -n 3 markdown.md
---
confluence-url: https://your-domain.atlassian.net/wiki/spaces/SP/pages/18237182/new+title
---

3. Update page

Performing an update does not require providing --page_id and --url:

$ confluence.md --user user@name.net --token 9a8dsadsh update --file README.md

Doing an update with --page_id and --url is still possible.

Consider adding useful --add_info option.

To create Atlassian API Token go to api-tokens.

Command line arguments

Actions:

  • update Updates page content based on given page_id or metadata in Markdown file
  • create Creates new page under given parent_id

positional arguments:

  • {update,create} Action to run

optional arguments:

  • -h, --help show this help message and exit
  • --file FILE input markdown file to process
  • --add_meta adds metadata to .md file for easy editing
  • --add_info adds info panel automatic content do not edit on top of the page
  • --add_label ADD_LABEL adds label to page
  • --convert_jira convert all Jira links to issue snippets (either short [KEY-ID] format or full URL) note: this options works only in Cloud instances with Secure Markdown installed
  • -v, --verbose verbose mode
  • -q, --quiet quiet mode

required auth parameters:

  • -u USER, --user USER Atlassian username/email
  • -t TOKEN, --token TOKEN Atlassian API token
  • -p PWD, --password PWD Atlassian password (used in on-prem instances)
  • -l URL, --url URL Atlassian instance URL
  • -n, --no_verify_ssl don't verify SSL cert (useful in on-prem instances)

create page parameters:

  • --parent_id PARENT_ID define parent page id while creating a new page
  • --title TITLE define page title while creating a new page
  • --overwrite force overwrite if page with this title already exists

update page arguments:

  • --page_id PAGE_ID define (or override) page id while updating a page

How to use it in a Python script?

ConfluenceMD wasn't designed to be used this way, but it's fairly simple to embed it in a Python script. See this example:

from md2cf.utils.confluencemd import ConfluenceMD

conf_md = ConfluenceMD(username=user,
                       md_file=md_file,
                       token=token,
                       url=url,
                       convert_jira=convert_jira)

# create new page under parent_id
new_page_id = conf_md.create_new("parent_id", "title")

# update existing page with given page_id
page_id = conf_md.update_existing("page_id")