MkDocs to Confluence

MkDocs plugin for converting and uploading Markdown pages to Confluence

Automatically publish your MkDocs documentation to Atlassian Confluence during builds. Convert Markdown to Confluence format and maintain synchronized documentation across platforms.

Features

Core Capabilities

• Automated Publishing - Seamlessly publish MkDocs documentation to Confluence during builds
• Unlimited Hierarchy Depth - Support for arbitrary nesting levels
• Smart Updates - Creates new pages or updates existing ones based on title matching
• Intelligent Update Detection - Compares content before updating to skip unnecessary changes, reducing version bumps
• Orphaned Page Management - Automatically detects and optionally cleans up pages that no longer exist in your documentation, keeping your Confluence space in perfect sync
• Image Management - Automatically uploads and updates images as attachments with SHA1 hash-based change detection

Authentication & Security

• Multiple Authentication Methods - Supports Basic Auth, API tokens, and OAuth Bearer tokens
• Environment Variable Support - Secure credential management for CI/CD pipelines

Developer Experience

• Dry Run Mode - Validate against Confluence without making changes (read-only validation)
• Export-Only Mode - Export to filesystem without connecting to Confluence
• Conditional Publishing - Enable/disable based on environment variables
• Enhanced Markdown - Extended syntax support including strikethrough, admonitions, task lists, and more
• Comprehensive Logging - Verbose and debug modes with detailed content comparison

Documentation Structure

This documentation follows the Diátaxis framework, organizing content by purpose:

📚 Tutorials (Learning-Oriented)

For newcomers who want to learn by doing

Start here if you're new to mkdocs-to-confluence. Tutorials guide you step-by-step through your first setup and configuration.

• Installation - Install the plugin
• Quick Start - Your first Confluence sync
• Configuration - Configure the plugin

🛠️ How-To Guides (Task-Oriented)

For users who need to accomplish specific tasks

Practical guides for solving real-world problems and implementing specific features.

• Basic Usage - Publishing workflow
• Advanced Features - H1 stripping, custom settings
• Managing Orphaned Pages - Sync your Confluence space
• Dry Run Mode - Test before publishing
• GitHub Pages Deployment - Deploy to GitHub Pages
• Troubleshooting - Common issues and solutions
• Contributing - How to contribute

📖 Reference (Information-Oriented)

For users who need precise technical information

Complete technical specifications and API documentation.

• Configuration Options - Complete config reference
• API Reference - Python API documentation
• Markdown Showcase - Supported Markdown features

💡 Explanation (Understanding-Oriented)

For users who want to understand how things work

Conceptual guides explaining the architecture, design decisions, and key concepts.

• How It Works - Plugin architecture and sync process
• Key Concepts - Pages, hierarchy, and content management

Quick Start

# Install
pip install mkdocs-to-confluence

# Configure mkdocs.yml
plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: YOUR_SPACE
      parent_page_name: Documentation

# Publish
mkdocs build

Your documentation is now synced to Confluence! 🎉

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Changelog: Release Notes

License

MIT License - see LICENSE for details.