confluence-md-exporter

English | Русский

Local read-only export of Confluence Server/Data Center pages to Markdown: page body, attachments, version diffs, and a batch report.

It does not write to Confluence, walk descendants, or talk to Cloud. Python >=3.11,<3.15.

Install

pip install confluence-md-exporter

or

uv tool install confluence-md-exporter

Check: confluence-md-exporter --version. Help: confluence-md-exporter -h.

Use cases

In every example the URL list is a UTF-8 text file, one page per line. #… lines and blank lines are ignored.

Public instance

Pages are readable without login. The Confluence base URL is taken from absolute links, so --base-url is not needed.

urls.txt:

https://confluence.example.com/pages/viewpage.action?pageId=123456
https://confluence.example.com/display/SPACE/Page+Title

confluence-md-exporter -i urls.txt -o output

Private instance: Personal Access Token

Token without a username → Bearer.

confluence-md-exporter -i urls.txt -o output -t PAT

Private instance: username and password (or username and PAT)

Username + token → HTTP Basic.

confluence-md-exporter -i urls.txt -o output -u USER -t TOKEN

Page ids only

If the list is ids such as 123456 rather than full URLs, the base URL must be set explicitly.

ids.txt:

123456
789012

confluence-md-exporter -i ids.txt -o output --base-url https://confluence.example.com

Compare two versions of a page

Put a Confluence diff URL in the list. Markdown with YAML metadata and a ```diff block is written under output/05_diffs/.

https://confluence.example.com/pages/diffpagesbyversion.action?pageId=607636678&selectedPageVersions=41&selectedPageVersions=42

confluence-md-exporter -i urls.txt -o output -t PAT

Re-run, refresh, clean start

A second run into the same -o skips a page when the local version matches the server and attachment files are still on disk (disk-skip).

Credentials can live in .env (CONFLUENCE_TOKEN, CONFLUENCE_USERNAME, …). CLI flags override the environment. Do not commit .env.

Input line formats

Unsupported lines (tiny-link /x/… and the like) are recorded in run_report.json as invalid_urls and do not fail the batch.

Output layout

output/
├── 01_raw/             # raw REST JSON
├── 02_interim/         # Storage XML
├── 03_assets/          # attachments and images (per page_id)
├── 04_markdown/        # Markdown pages and manifest.json
├── 05_diffs/           # unified diff of two versions (*_v41_to_v42.md)
└── run_report.json     # batch summary

Exit codes

Development

uv sync
uv run python -m pytest