md2confluence 1.0.0

Sync Markdown documentation to Confluence Cloud

md2confluence

A Python tool to sync Markdown documentation to Confluence Cloud.

Features

• Markdown to Confluence conversion - Headers, lists, tables, code blocks, info panels, task lists, and more
• Image handling - Automatically uploads local images as attachments
• Config-driven - Define document mappings in a simple config file
• Dry-run mode - Preview changes before syncing
• Retry logic - Exponential backoff for transient failures
• Rate limiting - Avoid API throttling
• Edge case handling - Configurable behavior for missing files, failed uploads, etc.

Installation

# From git (recommended)
pip install git+ssh://[e-mail]/bibliocommons/itops-md2confluence.git

# Or pin to a version
pip install git+ssh://[e-mail]/bibliocommons/itops-md2confluence.git@v1.0.0

# For development
git clone [e-mail]:bibliocommons/itops-md2confluence.git
cd itops-md2confluence
pip install -e .

Dependencies

• Python 3.9+
• requests library (installed automatically)

Quick Start

1. Install:

   pip install git+ssh://[e-mail]/bibliocommons/itops-md2confluence.git
   

2. Set environment variables:

   export CONFLUENCE_API_TOKEN="your-api-token"
   export CONFLUENCE_USER_EMAIL="[e-mail]"  # For basic auth
   

3. Create a config file (.confluence-sync.conf):

   CONFLUENCE_BASE_URL="https://your-domain.atlassian.net/wiki"
   CONFLUENCE_SPACE_KEY="DOCS"
   CONFLUENCE_TECH_PARENT_ID="123456789"
   
   # Document mappings: "Title|path/to/file.md|parent_page_id"
   CONFLUENCE_DOC_README="README|README.md|${CONFLUENCE_TECH_PARENT_ID}"
   

4. Run the sync:

   md2confluence
   

Usage

# Sync all configured documents
python md2confluence.py

# Dry-run (preview without changes)
python md2confluence.py --dry-run

# List configured documents
python md2confluence.py --list

# Verify config and connectivity
python md2confluence.py --verify

# Sync a single document
python md2confluence.py --single "Page Title" path/to/doc.md parent_page_id

# Convert markdown to Confluence format (stdin)
echo "# Hello" | python md2confluence.py --stdin

Configuration

See confluence-sync.conf.example for all available options.

Authentication

Supports two auth modes:

• Basic auth: CONFLUENCE_USER_EMAIL + CONFLUENCE_API_TOKEN
• Bearer auth: CONFLUENCE_API_TOKEN only (OAuth tokens)

Auto-detected based on whether CONFLUENCE_USER_EMAIL is set.

Document Mappings

Define documents to sync using CONFLUENCE_DOC_* variables:

CONFLUENCE_DOC_MYPAGE="Page Title|path/to/file.md|parent_page_id"

Edge Case Handling

Option	Values	Default
CONFLUENCE_MISSING_FILE_BEHAVIOR	skip, fail	skip
CONFLUENCE_IMAGE_FAILURE_BEHAVIOR	placeholder, skip, fail	placeholder
CONFLUENCE_TITLE_SPECIAL_CHARS	sanitize, encode, fail	sanitize

Markdown Support

• Headers (h1-h6)
• Bold, italic, strikethrough
• Ordered and unordered lists
• Nested lists
• Task lists (checkboxes)
• Tables
• Fenced code blocks with syntax highlighting
• Inline code
• Links (inline and reference-style)
• Images (uploaded as attachments)
• Blockquotes → Confluence panels (Note/Warning/Tip/Info)
• Horizontal rules

License

MIT