confluence-markdown-exporter

The exporter provides specific handling for common Confluence diagramming and extension tools:

• draw.io: Diagram files are saved as attachments.
• Mermaid: Embedded Mermaid diagrams are extracted as fenced Mermaid blocks.
• PlantUML: Exported as fenced PlantUML code blocks.
• Markdown Extensions: Raw Markdown macro content is passed through directly.

The exporter converts various Confluence rich text elements into Markdown. Supported features include:

• Rich text: Headings, paragraphs, bold, italic, underline, lists, tables, links, images, attachments, and image captions.
• Code blocks: Language-aware fenced code blocks.
• Task lists: Checkboxes with completion state.
• Text highlights & font colours: Preserved using inline HTML colour styling.
• Status badges: Converted to coloured inline highlights.
• Info / note / tip / warning panels: Converted to Markdown alert blocks (e.g., [!NOTE], [!TIP]).
• Comments: Open inline and/or page-level (footer) comments are exported as sidecar files located next to each page.
• Include / excerpt-include macros: Embedded pages are either inlined or exported as Obsidian transclusion links (![[Page Title]]).

The exporter handles Confluence metadata by converting it into formats suitable for Markdown-based knowledge bases like Obsidian:

• Page properties: The Page Properties macro is exported as YAML front matter, Dataview inline fields, or Meta Bind VIEW fields. Duplicate keys are automatically disambiguated. The specific format is controlled by the export.page_properties_format configuration option.
• Page Properties Report: Dynamic cross-page property tables are exported as either a static snapshot or a live Dataview DQL query. The format is controlled by the export.page_properties_report_format configuration option.
• Page labels: Confluence labels are exported as tags in the YAML front matter.

Environment variables can override stored configuration for the current session. These overrides are not persisted to the config file.

Naming Convention:

• Prefix: CME_
• Delimiter: __ (double underscore) replaces the dot . used in config keys.
• Case: Uppercase.

Example: export.log_level becomes CME_EXPORT__LOG_LEVEL.

Warning: Authentication credentials using URL-keyed nested dicts (e.g., auth.confluence["https://..."]) cannot be set via environment variables. Use cme config edit or cme config set for these.

# Example: Overriding log level for the current session
export CME_EXPORT__LOG_LEVEL=DEBUG

The exporter preserves the Confluence hierarchy in your local file system. Files are saved to the directory defined by export.output_path.

Each space or page hierarchy creates a corresponding directory structure where .md files represent pages and subdirectories represent nested pages.

output_path/
└── MYSPACE/
   ├── MYSPACE.md
   └── MYSPACE/
      ├── My Confluence Page.md
      └── My Confluence Page/
            ├── My nested Confluence Page.md
            └── Another one.md

For an isolated, self-updating environment that manages its own virtualenv using uv, use the platform-specific shell scripts. This is recommended for users who want a managed tool without manual environment management.

# Linux / macOS
curl -LsSf uvx.sh/confluence-markdown-exporter/install.sh | sh

# Windows (Run from PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/confluence-markdown-exporter/install.ps1 | iex"

To export content, you must first authenticate with your Atlassian instance.

Local Installation

Run the following command to open an interactive configuration menu to set up your credentials. This writes the configuration to ~/.config/confluence-markdown-exporter/app_data.json.

cme config edit auth.confluence

Docker / CI Installation

Docker containers are non-interactive. To authenticate in a containerized environment:

1. Run cme config edit auth.confluence on a local workstation to generate the app_data.json file.
2. Copy app_data.json to your CI secret store or repository.
3. Mount the file into the container at runtime (see Docker usage below) or use environment variables starting with CME_AUTH__*.

Use the cme CLI to export different levels of Confluence content. By default, the exporter skips unchanged pages, re-exporting only what has changed since the last run. Output is sent to the configured export.output_path (which defaults to the current directory).

# Export a single page
cme pages <page-url>

# Export a page and all its descendants
cme pages-with-descendants <page-url>

# Export an entire space
cme spaces <space-url>

# Export every space in an organisation
cme orgs <base-url>

Use the spaces or space command to export all pages contained within one or more Confluence spaces.

Supported space URL formats:

• Confluence Cloud: https://company.atlassian.net/wiki/spaces/SPACEKEY
• Confluence Cloud (API gateway): https://api.atlassian.com/ex/confluence/CLOUDID/wiki/spaces/SPACEKEY
• Confluence Server (long): https://wiki.company.com/display/SPACEKEY
• Confluence Server (short): https://wiki.company.com/SPACEKEY

cme spaces <space-url>
cme spaces <space-url-1> <space-url-2> ...

# Singular alias
cme space <space-url>

The image reads its configuration from /data/config/app_data.json (controlled by the CME_CONFIG_PATH environment variable).

Workflow:

1. Generate a config file on a local workstation using the cme config command.
2. Mount this file into the container at /data/config/app_data.json using a read-only volume.
3. Ensure the file is readable by UID 1000 (the cme user inside the image). Use chmod 644 app_data.json if necessary.

Example Docker Run:

docker run --rm \
  -v "$PWD/app_data.json:/data/config/app_data.json:ro" \
  -v "$PWD/output:/data/output" \
  spenhouet/confluence-markdown-exporter \
  pages <page-url>