confluence2md 0.3.0

Export Confluence pages to Markdown files

confluence2md

Export Confluence pages to Markdown files because using Confluence (or any other Atlassian product for that matter, like Jira) sucks. Works as a CLI tool and as a Python library.

Installation

uv sync

Configuration

Copy config.yaml.example to config.yaml and adjust it to your Confluence instance:

confluence:
  url: https://your-instance.atlassian.net/wiki
  token: your-personal-access-token
  username: [e-mail]

output:
  directory: ./export
  filename_pattern: "{title}"
  include_children: false
  include_labels: true
  include_metadata: true

The token can also be set via the CONFLUENCE2MD_TOKEN environment variable. The username can be set via CONFLUENCE2MD_USERNAME.

For Confluence Cloud, both username (your email) and token (API token) are required. For Confluence Server/Data Center with personal access tokens, only token is needed.

CLI Usage

Export pages matching a CQL query:

confluence2md export --cql "space = DEV AND label = api"

Export a single page by ID:

confluence2md export --page-id 12345

Export a page and its children:

confluence2md export --page-id 12345 --include-children

Export all pages from a space:

confluence2md export --space DEV

Override the output directory:

confluence2md export --cql "space = DEV" --output-dir ./docs

Use a specific config file:

confluence2md -c path/to/config.yaml export --space DEV

List available spaces:

confluence2md list-spaces
confluence2md list-spaces --search "dev"

Library Usage

from confluence2md import load_config, connect, fetch_pages_by_cql, export_pages

config = load_config("config.yaml")
confluence = connect(config.confluence)
pages = fetch_pages_by_cql(confluence, "space = DEV", max_results=100)
paths = export_pages(pages, config.output)

You can also render Markdown without writing files:

from confluence2md import render_page

markdown = render_page(page, config.output)
print(markdown)

Releasing

./scripts/release.sh patch  # 0.1.0 → 0.1.1
./scripts/release.sh minor  # 0.1.0 → 0.2.0
./scripts/release.sh major  # 0.1.0 → 1.0.0

This bumps the version in pyproject.toml, commits, tags, and pushes. The push triggers a GitHub Actions workflow that publishes the package to PyPI.

License

MIT