MkDocs Confluence Publisher Plugin

This MkDocs plugin automatically publishes your documentation to Confluence. It creates a hierarchical structure in Confluence that mirrors your MkDocs site structure, updates page content, and handles attachments.

Features

• Automatically creates and updates pages in Confluence
• Maintains the hierarchy of your MkDocs site in Confluence
• Handles attachments referenced in your markdown files
• Configurable page prefix for easy identification in Confluence

Installation

Install the plugin using pip:

pip install mkdocs-confluence-publisher

Configuration

Add the following to your mkdocs.yml:

plugins:
  - confluence-publisher:
      confluence_prefix: "MkDocs - "  # Optional: Prefix for page titles in Confluence
      confluence_suffix: " - MkDocs"  # Optional: Suffix for page titles in Confluence
      space_key: "YOUR_SPACE_KEY"     # Required: Confluence space key
      parent_page_id: 123456          # Required: ID of the parent page in Confluence

Environment Variables

The plugin resolves credentials in this order:

1. If CONFLUENCE_API_TOKEN is set:
   • For Cloud Confluence (atlassian.net / jira.com URLs), set CONFLUENCE_USERNAME (typically your email) and the token is used as the password.
   • For non-cloud Confluence, CONFLUENCE_API_TOKEN is used as a bearer token.
2. If no API token is set, use CONFLUENCE_USERNAME + CONFLUENCE_PASSWORD.

API token mode:

• CONFLUENCE_URL: The base URL of your Confluence instance
• CONFLUENCE_API_TOKEN: Your Confluence API token
• CONFLUENCE_USERNAME (required only for Cloud URLs): Your Confluence username/email

Username/password mode:

• CONFLUENCE_URL: The base URL of your Confluence instance
• CONFLUENCE_USERNAME: Your Confluence username
• CONFLUENCE_PASSWORD: Your Confluence password

You can set these in your environment or use a .env file.

Usage

Once configured, the plugin will automatically publish your documentation to Confluence when you build your MkDocs site:

mkdocs build

How It Works

1. Initialization: The plugin connects to Confluence using the provided credentials.
2. Page Creation: It creates a structure in Confluence mirroring your MkDocs navigation.
3. Content Update: As it processes each page, it updates the content in Confluence.
4. Attachment Handling: Any attachments referenced in your markdown are uploaded to the corresponding Confluence page.

Logging

The plugin uses Python's logging module. You can configure logging in your mkdocs.yml:

logging:
  level: INFO

Set to DEBUG for more detailed logging information.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache-2.0 license.