DEV Community

Adrian Darian
Adrian Darian

Posted on

Export Your Confluence Documentation Like a Pro: Introducing Confluence Export CLI

#automation #opensource #documentation #cli

Have you ever needed to backup your Confluence pages? Or migrate documentation to another system? Or simply want your Confluence content in Markdown format for version control?

I've built Confluence Export CLI - a powerful command-line tool that exports Confluence pages to multiple formats (Markdown, HTML, Text, PDF) with support for bulk exports, parallel fetching, and recursive child page export.

Why I Built This

Working with Confluence documentation, I often needed to:

  • Export entire documentation spaces for backup
  • Convert Confluence pages to Markdown for Git-based workflows
  • Migrate documentation between systems
  • Create offline backups of critical documentation

The existing solutions were either too complex, required manual work, or didn't support bulk exports. So I built a tool that does exactly what I needed - and made it open source for others to use.

Key Features

🚀 Multiple Export Formats

Export to the format that works best for your workflow:

  • Markdown - Perfect for Git-based documentation
  • HTML - Standalone HTML files with embedded CSS
  • Plain Text - Great for search and archival
  • PDF - Native Confluence PDF export 
# Export to multiple formats at once
confluence-export --pages 123456 --format markdown html pdf
Enter fullscreen mode Exit fullscreen mode

📦 Bulk Export with Parallel Processing

Export hundreds of pages efficiently with configurable parallel workers:

# Export entire space with 8 parallel workers
confluence-export --space DOCS --format markdown --workers 8
Enter fullscreen mode Exit fullscreen mode

🌳 Recursive Child Page Export

Automatically export parent pages and all their children:

# Export a page and all its sub-pages
confluence-export --pages 123456 --include-children --format markdown
Enter fullscreen mode Exit fullscreen mode

🎯 Flexible Input Options

Support for multiple input methods:

  • Full URLs: https://yoursite.atlassian.net/wiki/spaces/DOCS/pages/123/Page+Title
  • Page IDs: 123456
  • From file: --pages-file pages.txt
  • Entire spaces: --space DOCS

📊 Progress Display & Export Manifest

Beautiful progress bars using Rich library, plus optional manifest generation:

confluence-export --pages 123456 --include-children --manifest
Enter fullscreen mode Exit fullscreen mode

Creates INDEX.md and manifest.json listing all exported pages.

Quick Start

Installation 

pip install confluence-export
Enter fullscreen mode Exit fullscreen mode

Setup Authentication

Get your API token from Atlassian API Tokens:

export CONFLUENCE_BASE_URL=https://yoursite.atlassian.net
export CONFLUENCE_EMAIL=your.email@example.com
export CONFLUENCE_API_TOKEN=your-api-token
Enter fullscreen mode Exit fullscreen mode

Export Your First Page 

# Using a full URL
confluence-export --pages "https://yoursite.atlassian.net/wiki/spaces/DOCS/pages/123456/My+Page" --format markdown

# Or using a page ID
confluence-export --pages 123456 --format markdown
Enter fullscreen mode Exit fullscreen mode

Real-World Examples

Backup an Entire Documentation Space 

confluence-export \
  --space DOCS \
  --format markdown html pdf \
  --include-children \
  --manifest \
  --output "./backup-$(date +%Y%m%d)" \
  --workers 8
Enter fullscreen mode Exit fullscreen mode

Export Documentation Section with Sub-pages 

confluence-export \
  --pages "https://mysite.atlassian.net/wiki/spaces/DOCS/pages/123/Getting+Started" \
  --include-children \
  --format markdown \
  --manifest \
  --output ./docs
Enter fullscreen mode Exit fullscreen mode

Export from a File of URLs

Create pages.txt:

https://mysite.atlassian.net/wiki/spaces/DOCS/pages/123/Page+One
https://mysite.atlassian.net/wiki/spaces/DOCS/pages/456/Page+Two
789012
Enter fullscreen mode Exit fullscreen mode

Then:

confluence-export --pages-file pages.txt --format markdown
Enter fullscreen mode Exit fullscreen mode

Technical Highlights

Architecture

The tool is built with Python 3.8+ and follows clean architecture principles:

  • Modular Design: Separate exporters for each format, easy to extend
  • Parallel Processing: Uses ThreadPoolExecutor for concurrent API calls
  • Error Handling: Graceful error handling with --skip-errors option
  • Configuration Layers: CLI args > Config file > Environment variables > Defaults

Distribution Options

I've made it easy to distribute and use:

  1. Wheel Package: Install via pip install confluence-export
  2. Standalone Executables: No Python required - download and run
    • Linux, Windows, and macOS executables
    • Built with PyInstaller
    • Available in GitHub releases

GitHub Actions Workflow

Automated builds and releases:

  • Builds wheel packages and executables for all platforms
  • Creates GitHub releases automatically
  • Publishes to PyPI on tag push

Configuration File Support

Save your settings to avoid repeating them:

confluence-export --base-url https://mysite.atlassian.net \
  --email user@example.com \
  --output ./exports \
  --format markdown html \
  --save-config
Enter fullscreen mode Exit fullscreen mode

Creates .confluence-export.toml:

[auth]
base_url = "https://mysite.atlassian.net"
email = "user@example.com"

[export]
output = "./exports"
formats = ["markdown", "html"]
include_children = true
Enter fullscreen mode Exit fullscreen mode

Now you can just run:

confluence-export --pages 123456
Enter fullscreen mode Exit fullscreen mode

Output Structure

Hierarchical (Default)

Preserves page hierarchy in folder structure:

exports/
├── Parent-Page-123.md
└── Parent-Page/
    ├── Child-Page-456.md
    └── Child-Page/
        └── Grandchild-789.md
Enter fullscreen mode Exit fullscreen mode

Flat Structure

Use --flat for a single directory:

exports/
├── Parent-Page-123.md
├── Child-Page-456.md
└── Grandchild-789.md
Enter fullscreen mode Exit fullscreen mode

Use Cases

  1. Documentation Migration: Export Confluence docs before migrating to another platform
  2. Version Control: Convert Confluence pages to Markdown for Git-based documentation
  3. Backup: Create regular backups of critical documentation
  4. Offline Access: Export documentation for offline viewing
  5. Content Analysis: Export to text format for analysis or search indexing

Contributing

The project is open source and welcomes contributions! Areas where help is appreciated:

  • Additional export formats (DOCX, LaTeX, etc.)
  • Performance improvements
  • Documentation improvements
  • Bug fixes and feature requests

Check out the GitHub repository to get started.

Conclusion

Confluence Export CLI solves a real problem for teams working with Confluence documentation. Whether you need to backup your docs, migrate to another system, or simply want your content in a different format, this tool makes it easy.

Try it out:

pip install confluence-export
confluence-export --help
Enter fullscreen mode Exit fullscreen mode

Star the repo: github.com/adriandarian/confluence-export

Have questions or feedback? Open an issue on GitHub or reach out!

Top comments (0)