Skip to content

Configuring Your Plugin

Learn how to configure mkdocs-to-confluence to publish your documentation to Confluence.

Step 1: Add Plugin to mkdocs.yml

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

Step 2: Configure Authentication

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

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

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!

Alternatively, you can specify credentials directly in .env (recommended):

JIRA_USERNAME="your-email@example.com"
CONFLUENCE_API_TOKEN="your-api-token-here"
CONFLUENCE_HOST_URL="https://domain_name/rest/api/content"
SPACE_KEY="your-confluence-space-key"
PARENT_PAGE_NAME="Technical Documentation"

Step 3: Find Your Space Key

Your Confluence space key appears in the URL:

https://your-domain.atlassian.net/wiki/spaces/SPACEKEY/overview
                                                  ^^^^^^^^

Or find it in Confluence: 1. Navigate to your space 2. Click "Space Settings" (gear icon) 3. Look for "Space Key" in the overview

Step 4: Test with Dry Run

Before publishing to Confluence, test locally:

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: DOCS
      dryrun: true
      export_dir: confluence-export

Build your docs:

mkdocs build

Check the confluence-export/ directory to preview the converted pages.

Step 5: Publish to Confluence

Remove or set dryrun: false to publish:

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: DOCS
      parent_page_name: Documentation
      dryrun: false  # Or remove this line

Build again:

mkdocs build

Your pages are now published to Confluence! 🎉

Common Configuration Options

Strip H1 Headings

Remove redundant H1 headings (Confluence shows page title):

plugins:
  - mkdocs-to-confluence:
      strip_h1: true

Conditional Publishing

Only publish when an environment variable is set:

plugins:
  - mkdocs-to-confluence:
      enabled_if_env: PUBLISH_TO_CONFLUENCE

export PUBLISH_TO_CONFLUENCE=1
mkdocs build  # Will publish

unset PUBLISH_TO_CONFLUENCE
mkdocs build  # Will skip publishing

Enable Verbose Logging

See detailed output during publishing:

plugins:
  - mkdocs-to-confluence:
      verbose: true

Complete Example

Here's a production-ready configuration:

site_name: My Documentation

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

      # Features
      strip_h1: true

      # Control
      enabled_if_env: PUBLISH_TO_CONFLUENCE

      # Credentials (set via environment variables)
      # JIRA_USERNAME and CONFLUENCE_API_TOKEN

Set environment variables:

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

Next Steps