mkdocs-to-confluence

A MkDocs plugin that automatically publishes your documentation to Atlassian Confluence. Convert Markdown pages to Confluence format and maintain synchronized documentation across platforms.

---

Full Documentation following Diataxis framework with :

• Tutorials (Learning-Oriented)
• How-To Guides (Task-Oriented)
• Reference (Information-Oriented)
• Explanation (Understanding-Oriented)

---

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Usage Examples
• Markdown Support
• Troubleshooting
• Contributing
• License

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 - Export to filesystem for review before publishing 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

Installation

Install from PyPI

The recommended way to install mkdocs-to-confluence is via pip:

pip install mkdocs-to-confluence

Or add to your requirements.txt:

mkdocs>=1.1
mkdocs-to-confluence

Quick Start

API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a name and copy the token

Space Key

Find your Confluence space key:

1. Go to your Confluence space
2. Click "Space Settings"
3. The space key is shown in the URL: https://your-domain.atlassian.net/wiki/spaces/SPACEKEY/

Configuration

Open your mkdocs.yml and add the plugin:

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

Set up your Confluence credentials using environment variables (recommended):

export JIRA_USERNAME=your-email@example.com
export CONFLUENCE_API_TOKEN=your-api-token

!!! tip "Getting Your API Token" Generate an API token at Atlassian Account Settings

Alternatively, you can specify credentials directly in mkdocs.yml (not recommended for production):

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: DOCS
      username: your-email@example.com
      api_token: your-token  # Better to use environment variable!

Orphaned Page Management

Keep your Confluence space in sync by automatically detecting and optionally cleaning up pages that no longer exist in your documentation:

plugins:
  - mkdocs-to-confluence:
      # ... other config ...
      cleanup_orphaned_pages: false  # Set to true to auto-delete orphaned pages
      keep_pages:  # Pages to preserve even if not in docs
        - "Archive"
        - "Manual Documentation"
      page_label: auto-generated-docs  # Label all synced pages for easy filtering

How it works:

• Always warns about orphaned pages (pages in Confluence but not in your docs)
• Optionally deletes them automatically when cleanup_orphaned_pages: true
• Preserves pages listed in keep_pages to protect manual content
• See Managing Orphaned Pages for detailed strategies

For complete configuration options, see the Configuration Reference.

Markdown Support

See the Markdown Showcase and full documentation.

Troubleshooting

Common Issues

For detailed troubleshooting, see the full documentation.

Quick fixes:

• Authentication failed: Verify username and API token
• Space not found: Check space key (case-sensitive)
• Parent page not found: Create parent page in Confluence first
• Images not uploading: Check image paths in Markdown

Debug mode:

plugins:
  - mkdocs-to-confluence:
      debug: true        # General debugging (API calls, operations)
      debug_diff: true   # Content comparison details (creates temp files)
      verbose: true

Dry run testing:

plugins:
  - mkdocs-to-confluence:
      dryrun: true
      export_dir: confluence-export

Requirements

• Python: >=3.8
• MkDocs: >=1.1
• Dependencies: jinja2, requests, mistune>=3.1.2, mime>=0.1.0

Contributing

Contributions are welcome! See the Contributing Guide for details.

Quick start:

git clone https://github.com/jmanteau/mkdocs-to-confluence.git
cd mkdocs-to-confluence
make py-setup
make py-test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

This project includes a vendored copy of md2cf (MIT License), which has been modified to support mistune 3.x and additional Confluence features.

Acknowledgments

• Original mkdocs-with-confluence by Paweł Sikora
• Original md2cf by Giacomo Gaino
• Enhanced md2cf fork by andrust with mistune 3.x support
• MkDocs documentation framework

Support

• Documentation: https://jmanteau.github.io/mkdocs-to-confluence/
• Issues: GitHub Issues

---

This README is auto-generated from documentation sources. Do not edit directly. To update, modify the docs and run make readme