The confluence-markdown-exporter exports Confluence pages in Markdown format. This exporter helps in migrating content from Confluence to platforms that support Markdown e.g. Obsidian, Gollum, Azure DevOps (ADO), Foam, Dendron and more.
- Converts Confluence pages to Markdown format.
- Uses the Atlassian API to export individual pages, pages including children, and whole spaces.
- Supports various Confluence elements such as headings, paragraphs, lists, tables, and more.
- Retains formatting such as bold, italic, and underline.
- Converts Confluence macros to equivalent Markdown syntax where possible.
- Handles images and attachments by linking them appropriately in the Markdown output.
- Supports extended Markdown features like tasks, alerts, and front matter.
- Headings: Converts Confluence headings to Markdown headings.
- Paragraphs: Converts Confluence paragraphs to Markdown paragraphs.
- Lists: Supports both ordered and unordered lists.
- Tables: Converts Confluence tables to Markdown tables.
- Formatting: Supports bold, italic, and underline text.
- Links: Converts Confluence links to Markdown links.
- Images: Converts Confluence images to Markdown images with appropriate links.
- Code Blocks: Converts Confluence code blocks to Markdown code blocks.
- Tasks: Converts Confluence tasks to Markdown task lists.
- Alerts: Converts Confluence info panels to Markdown alert blocks.
- Front Matter: Adds front matter to the Markdown files for metadata like page properties and page labels.
To use the confluence-markdown-exporter, follow these steps:
Install python package via pip.
pip install confluence-markdown-exporter
Run the exporter with the desired Confluence page ID or space key. Execute the console application by typing confluence-markdown-exporter
and one of the commands page
, page-with-descendants
, space
, all-spaces
or config
. If a command is unclear, you can always add --help
to get additional information.
Tip
Instead of confluence-markdown-exporter
you can also use the shorthand cf-export
.
Export a single Confluence page by ID:
confluence-markdown-exporter page <page-id e.g. 645208921> <output path e.g. ./output_path/>
or by URL:
confluence-markdown-exporter page <page-url e.g. https://company.atlassian.net/MySpace/My+Page+Title> <output path e.g. ./output_path/>
Export a Confluence page and all its descendant pages by page ID:
confluence-markdown-exporter page-with-descendants <page-id e.g. 645208921> <output path e.g. ./output_path/>
or by URL:
confluence-markdown-exporter page-with-descendants <page-url e.g. https://company.atlassian.net/MySpace/My+Page+Title> <output path e.g. ./output_path/>
Export all Confluence pages of a single Space:
confluence-markdown-exporter space <space-key e.g. MYSPACE> <output path e.g. ./output_path/>
Export all Confluence pages across all spaces:
confluence-markdown-exporter all-spaces <output path e.g. ./output_path/>
The exported Markdown file(s) will be saved in the specified output
directory e.g.:
output_path/
└── MYSPACE/
├── MYSPACE.md
└── MYSPACE/
├── My Confluence Page.md
└── My Confluence Page/
├── My nested Confluence Page.md
└── Another one.md
All configuration and authentication is stored in a single JSON file managed by the application. You do not need to manually edit this file.
To interactively view and change configuration, run:
confluence-markdown-exporter config
This will open a menu where you can:
- See all config options and their current values
- Select a config to change (including authentication)
- Reset all config to defaults
- Navigate directly to any config section (e.g.
auth.confluence
)
Key | Description | Default |
---|---|---|
export.output_path | The directory where all exported files and folders will be written. Used as the base for relative and absolute links. | ./ (current working directory) |
export.page_href | How to generate links to pages in Markdown. Options: "relative" (default) or "absolute". | relative |
export.page_path | Path template for exported pages | {space_name}/{homepage_title}/{ancestor_titles}/{page_title}.md |
export.attachment_href | How to generate links to attachments in Markdown. Options: "relative" (default) or "absolute". | relative |
export.attachment_path | Path template for attachments | {space_name}/attachments/{attachment_file_id}{attachment_extension} |
export.page_breadcrumbs | Whether to include breadcrumb links at the top of the page. | True |
export.filename_encoding | Character mapping for filename encoding. | Default mappings for forbidden characters. |
export.filename_length | Maximum length of filenames. | 255 |
export.include_document_title | Whether to include the document title in the exported markdown file. | True |
connection_config.backoff_and_retry | Enable automatic retry with exponential backoff | True |
connection_config.backoff_factor | Multiplier for exponential backoff | 2 |
connection_config.max_backoff_seconds | Maximum seconds to wait between retries | 60 |
connection_config.max_backoff_retries | Maximum number of retry attempts | 5 |
connection_config.retry_status_codes | HTTP status codes that trigger a retry | [413, 429, 502, 503, 504] |
connection_config.verify_ssl | Whether to verify SSL certificates for HTTPS requests. | True |
auth.confluence.url | Confluence instance URL | "" |
auth.confluence.username | Confluence username/email | "" |
auth.confluence.api_token | Confluence API token | "" |
auth.confluence.pat | Confluence Personal Access Token | "" |
auth.jira.url | Jira instance URL | "" |
auth.jira.username | Jira username/email | "" |
auth.jira.api_token | Jira API token | "" |
auth.jira.pat | Jira Personal Access Token | "" |
You can always view and change the current config with the interactive menu above.
Some platforms have specific requirements for Markdown formatting, file structure, or metadata. You can adjust the export configuration to optimize output for your target system. Below are some common examples:
- Document Title: Obsidian already displays the document title. Ensure
export.include_document_title
isFalse
so the documented title is not redundant. - Breadcrumbs: Obsidian already displays page breadcrumbs. Ensure
export.breadcrumbs
isFalse
so the breadcrumbs are not redundant.
- Absolute Attachment Links: Ensure
export.attachment_href
is set toabsolute
. - Attachment Path Template: Set
export.attachment_path
to.attachments/{attachment_file_id}{attachment_extension}
so ADO Wiki can find attachments. - Filename sanitizing:
- Set
export.filename_encoding
to" ":"-","\"":"%22","*":"%2A","-":"%2D",":":"%3A","<":"%3C",">":"%3E","?":"%3F","|":"%7C","\\":"_","#":"_","/":"_","\u0000":"_"
for ADO compatibility (spaces become-
, dashes become%2D
, and forbidden characters become_
) - Set
export.filename_length
to200
- Set
By default, configuration is stored in a platform-specific application directory. You can override the config file location by setting the CME_CONFIG_PATH
environment variable to the desired file path. If set, the application will read and write config from this file instead. Example:
export CME_CONFIG_PATH=/path/to/your/custom_config.json
This is useful for using different configs for different environments or for scripting.
Update python package via pip.
pip install confluence-markdown-exporter --upgrade
This package is not tested extensively. Please check all output and report any issue here. It generally was tested on:
- Confluence Cloud 1000.0.0-b5426ab8524f (2025-05-28)
- Confluence Server 8.5.20
- Missing Attachment File ID on Server: For some Confluence Server version/configuration the attachment file ID might not be provided (#39). In the default configuration, this is used for the export path. Solution: Adjust the attachment path in the export config and use the
{attachment_id}
or{attachment_title}
instead. - Connection Issues when behind Proxy or VPN: There might be connection issues if your Confluence Server is behind a proxy or VPN (#38). If you experience issues, help to fix this is appreciated.
If you would like to contribute, please read our contribution guideline.
This tool is an open source project released under the MIT License.