Configuration Reference

Complete reference for all mkdocs-to-confluence configuration options.

Basic Configuration

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: YOUR_SPACE
      parent_page_name: Documentation
      username: your-email@example.com
      api_token: your-api-token

Configuration Options

Required Settings

host_url

The Confluence REST API endpoint URL.

Format: https://your-domain.atlassian.net/wiki/rest/api/content

host_url: https://company.atlassian.net/wiki/rest/api/content

space

The Confluence space key where pages will be created.

space: DEV

Authentication

username

Your Confluence username (email address).

Default: Environment variable JIRA_USERNAME

username: user@example.com

api_token

Your Confluence API token. Never commit this to version control!

Default: Environment variable CONFLUENCE_API_TOKEN

api_token: your-secret-token

Security

Use environment variables instead of hardcoding credentials:

export JIRA_USERNAME=user@example.com
export CONFLUENCE_API_TOKEN=your-token

password

Legacy password authentication (not recommended). Use api_token instead.

Default: Environment variable JIRA_PASSWORD

auth_type

Authentication method: basic (default) or bearer for OAuth tokens.

auth_type: basic  # or 'bearer'

Page Hierarchy

parent_page_name

The parent page under which all documentation pages will be created.

Default: Uses space value if not specified

parent_page_name: API Documentation

Features

strip_h1

Automatically remove H1 headings from page content (since Confluence displays the page title).

Default: false

strip_h1: true

Only strips if: - H1 is the first content element - There's exactly one H1 in the document

page_label

Label to add to all auto-generated Confluence pages for easy identification.

Default: auto-generated-docs

page_label: mkdocs-generated

This label helps identify which pages were created by the plugin, making it easier to: - Filter pages in Confluence - Bulk-manage auto-generated documentation - Identify orphaned pages

cleanup_orphaned_pages

Automatically delete Confluence pages that exist under the parent page but are no longer in your documentation.

Default: false (safe default)

cleanup_orphaned_pages: true

Use with Caution

Orphaned pages are permanently deleted. Always test with dryrun: true first or review the warning messages before enabling cleanup.

When false (default):

• Warnings are logged about orphaned pages
• No pages are deleted
• You can manually review and delete orphaned pages

When true:

• Orphaned pages are automatically deleted
• Logs show which pages were removed
• Pages in keep_pages are preserved

keep_pages

List of page titles to preserve even if they're not in your documentation (only applies when cleanup_orphaned_pages: true).

Default: [] (empty list)

cleanup_orphaned_pages: true
keep_pages:
  - "Old Documentation"
  - "Archive"
  - "Manual Pages"

Use cases:

• Preserve manually-created pages
• Keep archived documentation
• Protect special pages from auto-deletion

dryrun

Enable dry-run mode for read-only validation against Confluence.

Default: false

dryrun: true

When enabled:

• Connects to Confluence in read-only mode (requires credentials)
• Validates all pages against existing Confluence content
• Performs content comparisons to detect changes
• Detects orphaned pages
• Shows what would be modified with "WOULD UPDATE", "WOULD CREATE" messages
• Does NOT create, update, or delete anything

Changed in 0.7.0

Previously, dryrun exported to filesystem only. Now it connects to Confluence for validation. Use export_only: true for the old behavior (filesystem export without Confluence connection).

Use cases:

• Validate documentation before publishing
• Preview what changes would be made
• Check for orphaned pages without modifying anything
• CI/CD validation workflows

export_only

Enable export-only mode to save pages to filesystem without connecting to Confluence.

Default: false

export_only: true
export_dir: confluence-export

When enabled:

• No Confluence connection required
• Exports all pages to filesystem in Confluence storage format
• No validation, comparisons, or orphaned page detection
• Faster than dryrun mode (no API calls)

Use cases:

• Generate Confluence-compatible HTML for manual upload
• Archive documentation in Confluence format
• Offline development without Confluence credentials
• Preview Confluence rendering locally

Dryrun vs Export-Only

• Use dryrun: true when you want to validate against Confluence without making changes
• Use export_only: true when you want to export to filesystem without connecting to Confluence

export_dir

Directory for filesystem exports (used by export_only mode).

Default: confluence-export

export_dir: my-export-folder

Conditional Execution

enabled_if_env

Only enable the plugin if a specific environment variable is set to 1.

enabled_if_env: PUBLISH_TO_CONFLUENCE

# Enable publishing
export PUBLISH_TO_CONFLUENCE=1
mkdocs build

# Skip publishing
unset PUBLISH_TO_CONFLUENCE
mkdocs build

Logging

verbose

Enable verbose logging output.

Default: false

verbose: true

debug

Enable debug mode with detailed logging and temporary file creation.

Default: false

debug: true

When enabled:

• Logs detailed API responses and operations
• Saves intermediate HTML files to /tmp/mkdocs-to-confluence-debug/
• Shows parent hierarchy resolution details

debug_diff

Enable verbose content diff debugging for page updates.

Default: false

debug_diff: true

When enabled:

• Writes current and new content to /tmp/confluence-debug/ for comparison
• Logs character counts and diff commands
• Shows whether content has changed or not
• Helpful for debugging why pages are/aren't being updated

Performance Impact

Keep debug_diff disabled in production as it writes many temporary files to disk. Enable it only when troubleshooting content update issues.

Complete Example

site_name: My Documentation
plugins:
  - mkdocs-to-confluence:
      # Connection
      host_url: https://company.atlassian.net/wiki/rest/api/content
      space: DOCS

      # Authentication (use environment variables in production!)
      username: user@example.com
      api_token: ${CONFLUENCE_API_TOKEN}
      auth_type: basic

      # Hierarchy
      parent_page_name: Product Documentation

      # Features
      strip_h1: true
      page_label: auto-generated-docs
      cleanup_orphaned_pages: false  # Set to true to auto-delete orphaned pages
      keep_pages:  # Pages to preserve when cleanup is enabled
        - "Archive"
        - "Manual Documentation"

      # Testing
      dryrun: false
      export_dir: confluence-export

      # Logging
      verbose: false
      debug: false
      debug_diff: false  # Enable for verbose content comparison debugging

      # Conditional
      enabled_if_env: PUBLISH_DOCS

Environment-Based Configuration

Recommended production setup:

mkdocs.yml

plugins:
  - mkdocs-to-confluence:
      host_url: https://company.atlassian.net/wiki/rest/api/content
      space: DOCS
      parent_page_name: Documentation
      strip_h1: true
      enabled_if_env: PUBLISH_TO_CONFLUENCE

Environment Variables

# .env file (never commit!)
export JIRA_USERNAME=user@example.com
export CONFLUENCE_API_TOKEN=your-secret-token
export PUBLISH_TO_CONFLUENCE=1

CI/CD Configuration

# .github/workflows/docs.yml
- name: Build and Deploy Docs
  env:
    JIRA_USERNAME: ${{ secrets.JIRA_USERNAME }}
    CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}
    PUBLISH_TO_CONFLUENCE: "1"
  run: mkdocs build

Next Steps

• Basic Usage - Learn how to use the plugin
• Advanced Features - Explore advanced capabilities
• Dry Run Mode - Test before publishing