MkDocs Confluence Plugin

A MkDocs plugin that automatically publishes your documentation to Confluence, with advanced navigation matching and semantic page resolution.

Features

• Automatic publishing - Seamlessly export your MkDocs documentation to Confluence
• Navigation matching - Matching between MkDocs navigation and documentation pages, including:
  • Support for complex nested navigation structures
  • Context-aware matching for pages in subdirectories
  • Semantic matching with abbreviation expansion (e.g., "ADRs" → "Architecture Design Records")
  • Fuzzy matching as fallback for edge cases
  • YAML front matter title recognition
• Flexible configuration - Extensive configuration options for Confluence integration
• Dry-run mode - Test your configuration without publishing
• Debug mode - Detailed logging for troubleshooting
• Footer support - Optional GitHub edit links and auto-generation notices
• Folder structure preservation - Maintains your documentation hierarchy in Confluence

Installation

Install from Source

pip install .

Development Installation

For development with optional dependencies:

pip install -e ".[dev]"

Build from Source

Using modern Python build tools:

python -m build
pip install dist/mkdocs_confluence_plugin-*.whl

Additional MkDocs Plugins (Optional)

Install additional MkDocs plugins as needed for your documentation:

# Popular MkDocs plugins for enhanced documentation
pip install mkdocs-material mkdocs-awesome-nav
pip install mkdocs-build-plantuml-plugin mkdocs-git-revision-date-localized-plugin

Python Requirements

• Python: >=3.7
• Build System: setuptools>=61, wheel, build

Dependencies

Core Dependencies (from pyproject.toml)

• mkdocs - The static site generator this plugin extends
• atlassian-python-api - Confluence API client
• md2cf - Markdown to Confluence markup converter
• mistune - Markdown parser
• requests - HTTP library for API calls
• pyyaml==6.0 - YAML parsing library
• mime - MIME type detection

Testing Dependencies

• pytest==8.0.0 - Testing framework
• pytest-mock==3.12.0 - Mocking utilities for tests
• coverage==7.5 - Code coverage analysis
• pre-commit - Git hook management

Development Dependencies (Optional)

Install with: pip install -e ".[dev]"

• black - Code formatting
• mkdocs - For local testing
• pytest - Testing framework
• coverage - Coverage reporting
• md2cf - Markdown conversion
• atlassian-python-api - Confluence integration

Recommended MkDocs Plugins

These plugins work well with the Confluence plugin but are installed separately:

• mkdocs-awesome-nav - Advanced navigation management with .nav.yml files
• mkdocs-material - Modern Material Design theme
• mkdocs-build-plantuml-plugin - PlantUML diagram support
• mkdocs-git-revision-date-localized-plugin - Git-based page timestamps

Configuration

The plugin is automatically registered as a MkDocs plugin via the entry point:

confluence = "mkdocs_confluence_plugin.plugin:ConfluencePlugin"

Add the plugin to your mkdocs.yml configuration:

plugins:
  - awesome-nav:
      filename: ".nav.yml"
  - confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: YOUR_SPACE_KEY
      parent_page_name: 'Documentation Root'
      git_base_url: "https://github.com/your-org/your-repo/blob/main"
      enable_header: true
      enable_footer: true
      header_text: "Auto-updated - {edit_link}"
      footer_text: "Auto-updated - {edit_link}"
      enabled_if_env: MKDOCS_TO_CONFLUENCE
      dryrun: false
      debug: true
      verbose: true

Configuration Options

Option	Description	Default	Required
host_url	Confluence API endpoint URL		✅
space	Confluence space key		✅
parent_page_name	Parent page name in Confluence		✅
git_base_url	Base URL for Git Server edit links
enable_header	Add header with edit links	false
enable_footer	Add footer with edit links	false
header_text	Custom header text ({edit_link} placeholder)	"Auto-updated - {edit_link}"
footer_text	Custom footer text ({edit_link} placeholder)	"Auto-updated - {edit_link}"
enabled_if_env	Environment variable to enable plugin
dryrun	Test mode without publishing	false
debug	Enable debug logging	false
verbose	Enable verbose output	false

Usage

Basic Usage

1. Configure the plugin in your mkdocs.yml
2. Set up environment variables for Confluence authentication:

   export CONFLUENCE_USERNAME=your-email@domain.com
   export CONFLUENCE_PASSWORD=your-api-token
   export MKDOCS_TO_CONFLUENCE=1

3. Build and publish your documentation:

   mkdocs build

Using with mkdocs-awesome-nav

For complex navigation structures, use mkdocs-awesome-nav with a .nav.yml file:

# docs/.nav.yml
nav:
  - Index: index.md

  - Support:
      - support/*.md
      - support/**/*.md

  - Technical-Practices:
      - Architecture Design Records:
          - technical-practices/architecture_design_records/*.md
          - technical-practices/architecture_design_records/**/*.md
      - Code-Maintainability:
          - technical-practices/code-maintainability/*.md
          - technical-practices/code-maintainability/**/*.md
      - Continuous-Delivery:
          - technical-practices/continuous-delivery/*.md
          - technical-practices/continuous-delivery/**/*.md
      - Monitoring-Observability:
          - technical-practices/monitoring-observability/*.md
          - technical-practices/monitoring-observability/**/*.md

  - Template Files:
      - template_files/*.md
      - template_files/**/*.md

Environment Setup

Set up the required environment variables for Confluence authentication and plugin configuration:

# Required for Confluence authentication
export CONFLUENCE_USERNAME="your-email@domain.com"
export CONFLUENCE_PASSWORD="your-confluence-api-token"

# Plugin enablement
export MKDOCS_TO_CONFLUENCE=1

# Optional: Override configuration via environment variables
export host_url="https://your-domain.atlassian.net/rest/api/content"
export space_key="YOUR_SPACE_KEY"
export parent_page_name="Documentation Root"
export enable_footer="true"
export dryrun="false"
export debug="true"
export verbose="true"

Required Environment Variables:

• CONFLUENCE_USERNAME - Your Confluence/Atlassian email
• CONFLUENCE_PASSWORD - Your Confluence API token (not your login password)
• MKDOCS_TO_CONFLUENCE - Set to 1 or true to enable the plugin

Dry Run Mode

Test your configuration without publishing to Confluence:

plugins:
  - confluence:
      # ... other config ...
      dryrun: true
      debug: true
      verbose: true

Testing

Run All Tests

Tests are configured via pyproject.toml with optimized settings:

# Run tests with project settings (maxfail=1, no warnings, quiet)
python -m pytest tests/

# Or run with verbose output
python -m pytest tests/ -v

Test Configuration (from pyproject.toml):

• Test directory: tests/
• Max failures: 1 (stops after first failure)
• Warnings disabled for cleaner output
• Quiet mode by default

Run Specific Test Categories

# Navigation matching tests
python -m pytest tests/test_navigation_matching.py -v

# Similarity and semantic matching tests  
python -m pytest tests/test_similarity.py -v

# Title-based matching tests
python -m pytest tests/test_title_based_matching.py -v

# Folder structure tests
python -m pytest tests/test_folder_titles.py -v

# Nested navigation tests
python -m pytest tests/test_nested_matching.py -v

Coverage Report

The project is configured for comprehensive coverage reporting with a minimum threshold:

# Generate coverage report (configured in pyproject.toml)
coverage run --source=src -m pytest -vv tests/
coverage report  # Shows missing lines, fails if under 30% coverage
coverage html    # Generate HTML report

Coverage Settings (from pyproject.toml):

• Branch coverage enabled
• Source directory: src
• Minimum coverage: 30%
• Shows missing lines in reports

Debug Scripts

The project includes debug scripts for troubleshooting navigation matching:

# Debug navigation matching step-by-step
python debug_step.py

# Debug word extraction and similarity
python debug_words.py

# Debug page collection logic
python debug_collect.py

# Debug navigation flattening
python debug_flatten.py

Code Quality

Code Formatting

We use Black for consistent code formatting:

black .

Linting

We use ruff for fast, comprehensive linting:

ruff check .

Pre-commit Hooks

Install pre-commit hooks for automatic code quality checks:

pre-commit install

Development

Local Development Setup

1. Clone the repository
2. Install the package with development dependencies: pip install -e ".[dev]"
3. Install additional MkDocs plugins if needed: pip install mkdocs-material mkdocs-awesome-nav
4. Set up environment variables:

   export CONFLUENCE_USERNAME=your-email@domain.com
   export CONFLUENCE_PASSWORD=your-api-token
   export MKDOCS_TO_CONFLUENCE=1

5. Run tests: python -m pytest tests/

Build System

The project uses modern Python packaging with pyproject.toml:

# Build distribution packages
python -m build

# Install built package
pip install dist/mkdocs_confluence_plugin-*.whl

Build Configuration:

• Build system: setuptools>=61, wheel, build
• Package discovery: automatic from src/ directory
• Entry point: confluence = "mkdocs_confluence_plugin.plugin:ConfluencePlugin"

Versioning

The project uses semantic versioning with automated releases:

• Version managed in pyproject.toml
• Semantic release configured for automated version bumps
• Current version: 1.26.0

Testing Your Changes

1. Run the full test suite: python -m pytest tests/ -v
2. Test with a real MkDocs build: mkdocs build -f mkdocs-test.yml
3. Use dry-run mode to test Confluence integration without publishing

Contributing

1. Ensure all tests pass
2. Format code with Black: black .
3. Check linting with ruff: ruff check .
4. Add tests for new functionality
5. Update documentation as needed

Architecture

The plugin provides sophisticated navigation matching through:

• Semantic word extraction - Extracts meaningful words from navigation entries and page paths
• Abbreviation expansion - Recognizes and expands common abbreviations (e.g., "ADRs" → "Architecture Design Records")
• Context-aware matching - Uses folder context and parent page information for better matching
• Multi-stage matching - Title-based, semantic, and fuzzy matching with configurable thresholds
• Robust error handling - Graceful degradation and comprehensive logging