Markdown files/directory publishing to Atlassian Confluence
Project description
Requirements
This Python package has been tested and designed for:
- Ubuntu 18.04 LTS
- Python 3.7.5 and several python libraries:
Please see requirements.txt for specific python packages/modules versions required.
Missing Features (Todo)
- Attachments (e.g. images, pdf, etc.)
Install
Download the package and prepare Python environment:
git clone "https://github.com/olafrv/mdtocf.git"
cd mdtocf
sudo apt install -y python3.7 python3-pip # Option 1: Install Python at system level
make virtualenv # Option 2: Create a Python virtual environment
Install the package for its use:
Note: If you skip virtual environment you should ensure using python >= 3.7
source venv/bin/activate # Use python virtual environment (Optional)
make install # Option 1: Use local package in ./mdtocf
make install-pypi # Option 2: Install package from PyPI
mkdir -p ~/dbs # Create temporal database directory
deactivate # Deactivate virtual environment (Optional)
See an example code in mdtocf.py and the target test-publish inside Makefile show some parameters examples.
Publish using local script
Note: If you skip virtual environment you should ensure using python >= 3.7
source venv/bin/activate # Use python virtual environment (Optional)
export PYTHON=python # Virtual Environment (Default, after 'source')
#export PYTHON=venv/bin/python # Virtual Environment (Default, without 'source')
#export PYTHON=venv/bin/python3.7 # Virtual Environment (Default = 3.7, without 'source')
#export PYTHON=/usr/bin/python3.7 # Use system level Python (without virtual environment)
${PYTHON} -m mdtocf.mdtocf --help
${PYTHON} -m mdtocf.mdtocf \
--confluenceUsername "olafrv@gmail.com" \
--confluenceApiToken "****************" \
--confluenceUrl "https://olafrv.atlassian.net" \
--confluenceSpace "TEST" \
--confluenceParentPageId "33114" \
--confluencePageTitlePrefix "[Test] " \
--markdownDir ./examples \
--db ~/dbs/examples.db
deactivate # Deactivate virtual environment (Optional)
Publish using Docker (Image locally built)
make docker
docker run --rm -it mdtocf --help
docker run --rm -it \
--mount type=bind,source="$(pwd)"/examples,target=/mdtocf/examples \
--mount type=bind,source=~/dbs,target=/mdtocf/dbs \
mdtocf \
--confluenceUsername "olafrv@gmail.com" \
--confluenceApiToken "****************" \
--confluenceUrl "https://olafrv.atlassian.net" \
--confluenceSpace "TEST" \
--confluenceParentPageId "33114" \
--confluencePageTitlePrefix "[Test] " \
--markdownDir "./examples" \
--db ~/dbs/examples.db
Publish using Docker (Image downloaded from Github's Packages)
# Check <VERSION> in https://github.com/olafrv/mdtocf/packages
export IMAGE=docker.pkg.github.com/olafrv/mdtocf/mdtocf:<VERSION>
docker run --rm -it $IMAGE --help
docker run --rm -it \
--mount type=bind,source="$(pwd)"/examples,target=/mdtocf/examples \
--mount type=bind,source=~/dbs,target=/mdtocf/dbs \
$IMAGE
--confluenceUsername "olafrv@gmail.com" \
--confluenceApiToken "****************" \
--confluenceUrl "https://olafrv.atlassian.net" \
--confluenceSpace "TEST" \
--confluenceParentPageId "33114" \
--confluencePageTitlePrefix "[Test] " \
--markdownDir ./examples \
--db ~/dbs/examples.db
Output and Results
Output:
UPD => Title: [Test] Folder A
Can't find '[Test] Folder A' page on the https://olafrv.atlassian.net/wiki!
IDX => Title: [Test] Folder B
Can't find '[Test] Folder B' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] 1
Can't find '[Test] 1' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] Page AA
Can't find '[Test] Page AA' page on the https://olafrv.atlassian.net/wiki!
UPD => Title: [Test] Example Page
Can't find '[Test] Example Page' page on the https://olafrv.atlassian.net/wiki!
The "Can't find..." means "not found but creating..." (Python Atlassian API).
Results in Confluence
Rendering and publishing ./examples produce the following final result in Confluence:
About Markdown Compatibility
This scripts depends on Mistune v2 Markdown Parser, compatible with CommonMark
The (optional) metadata heading in markdown (.md) files likes the one which follows below used by Hugo, it is not part of CommonMarkdown standard, but just a popular way of specify in YAML markdown metadata usable for external tools.
title: My Page Title
date: 2019-03-26T08:47:11+01:00
draft: true
chapter: true
kind: index
It is parsed and partially used by this script to organize the content in Attlasian Confluence. A test for this can be run:
make test-re
References
Markdown
Mistune v2
Python v3
- https://docs.python.org/3/
- https://docs.python.org/3/howto/regex.html
- https://pypi.org/project/atlassian-python-api/
- https://atlassian-python-api.readthedocs.io/confluence.html
Confluence and Storage Format (Cloud API)
- https://developer.atlassian.com/cloud/confluence/rest/
- https://confluence.atlassian.com/doc/confluence-server-documentation-135922.html
- https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html
- https://confluence.atlassian.com/doc/macros-139387.html
- https://confluence.atlassian.com/conf59/code-block-macro-792499083.html
- https://confluence.atlassian.com/confkb/how-to-get-confluence-page-id-648380445.html
- https://confluence.atlassian.com/doc/delete-or-restore-a-page-139429.html
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.