Skip to main content

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

Project description

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")

Project details


Download files

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

Source Distribution

confluence_md-0.4.3.tar.gz (9.6 kB view hashes)

Uploaded Source

Built Distribution

confluence.md-0.4.3-py3-none-any.whl (11.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page