confluence-markdown-exporter-advanced 0.5.0

A tool to export Confluence pages to Markdown

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, Foam, Dendron and more.

Features

• 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.

Supported Markdown Elements

• 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.

Usage

To use the confluence-markdown-exporter, follow these steps:

1. Installation

Install python package via pip.

pip install confluence-markdown-exporter-advanced

2. Configure Authentication

You must set environment variables for one of the following authentication options:

1. Username + API Token

   • ATLASSIAN_USERNAME: Your Atlassian account email address
   • ATLASSIAN_API_TOKEN: An API token created at
     https://id.atlassian.com/manage-profile/security/api-tokens

2. Personal Access Token (PAT)

   • ATLASSIAN_PAT: A Personal Access Token (used instead of username+token)

In all cases, you must also set:

• ATLASSIAN_URL: Your Atlassian instance URL (e.g. https://company.atlassian.net)

Here an example setting the environment variables for the Username + API Token authentication for the current terminal session.

export ATLASSIAN_USERNAME="work mail address"
export ATLASSIAN_API_TOKEN="API token Test"
export ATLASSIAN_URL="https://company.atlassian.net"

3. Exporting

Run the exporter with the desired Confluence page ID/URL or space key.

Export a single Confluence page by URL:

confluence-markdown-exporter page-url <page-url e.g. https://company.atlassian.net/Wiki/foo/bar> <output path e.g. ./output_path/>

Export a single Confluence page by id:

confluence-markdown-exporter page-id <page-id e.g. 645208921> <output path e.g. ./output_path/>

Export a Confluence page and all it's descendants:

confluence-markdown-exporter page-with-descendants <page-id e.g. 645208921> <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/>

[!TIP] Instead of confluence-markdown-exporter you can also use the shorthand cf-export.

4. Output

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

Configuration Options

By default the converter uses a GitHub Flavored Markdown (GFM). You can also choose an Obsidian flavored markdown by setting:

export MARKDOWN_STYLE="Obsidian"

Via PAGE_PATH and ATTACHMENT_PATH you can customize how pages and attachments are organized in the output directory.

By default, pages are stored at:

export PAGE_PATH="{space_name}/{homepage_title}/{ancestor_titles}/{page_title}.md"

Available variables:

• {space_key}: The key of the Confluence space.
• {space_name}: The name of the Confluence space.
• {homepage_id}: The ID of the homepage of the Confluence space.
• {homepage_title}: The title of the homepage of the Confluence space.
• {ancestor_ids}: A slash-separated list of ancestor page IDs.
• {ancestor_titles}: A slash-separated list of ancestor page titles.
• {page_id}: The unique ID of the Confluence page.
• {page_title}: The title of the Confluence page.

By default, attachments are stored at:

export ATTACHMENT_PATH="{space_name}/attachments/{attachment_file_id}{attachment_extension}"

Available variables:

• {space_key}: The key of the Confluence space.
• {space_name}: The name of the Confluence space.
• {homepage_id}: The ID of the homepage of the Confluence space.
• {homepage_title}: The title of the homepage of the Confluence space.
• {ancestor_ids}: A slash-separated list of ancestor page IDs.
• {ancestor_titles}: A slash-separated list of ancestor page titles.
• {attachment_id}: The unique ID of the attachment.
• {attachment_title}: The title of the attachment.
• {attachment_file_id}: The file ID of the attachment.
• {attachment_extension}: The file extension of the attachment, including the leading dot.

Contributing

If you would like to contribute, please read our contribution guideline.

License

This tool is an open source project released under the MIT License.