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!

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 Locally (Export-Only)

Before publishing to Confluence, test locally with export-only mode:

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: DOCS
      export_only: true  # Export to filesystem without connecting to Confluence
      export_dir: confluence-export

Build your docs:

mkdocs build

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

Validate Against Confluence

Once you have credentials set up, use dryrun: true instead to validate against Confluence without making changes. See Dry Run Mode for details.

Step 5: Publish to Confluence

Remove export_only or set it to false to publish:

plugins:
  - mkdocs-to-confluence:
      host_url: https://your-domain.atlassian.net/wiki/rest/api/content
      space: DOCS
      parent_page_name: Documentation
      export_only: 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