Confluence to Markdown: 5 Proven Export Methods (2026)

Over 50,000 companies use Atlassian Confluence for internal documentation (ElectroIQ, 2025). But when teams adopt Git-based workflows, static site generators, or tools like Obsidian, they need a way to convert confluence to markdown without losing formatting, tables, or code blocks.

This guide covers five methods to export Confluence pages to Markdown — from one-click marketplace apps to command-line tools that handle entire spaces at once. Each method includes step-by-step instructions, limitations, and tips for cleaning up the output.

TL;DR: Use a marketplace app (Methods 1-2) for quick single-page exports without technical skills. Use the Python CLI exporter (Method 3) for API-based bulk extraction. Use Pandoc (Method 4) for maximum control over output format. Use the Node.js converter (Method 5) if you want Turndown's cleaner output from HTML exports.

Why Convert Confluence to Markdown?

Teams convert Confluence to Markdown for portability, version control, and cost savings. Markdown files are plain text. They version-control cleanly in Git, render on GitHub and GitLab without plugins, and work in hundreds of editors. Confluence pages, by contrast, live inside a proprietary storage format that locks content behind a browser interface.

Common reasons teams migrate:

• Documentation-as-code — storing docs alongside source code in the same repository, reviewed via pull requests.
• Platform independence — Markdown renders everywhere, from VS Code to terminal viewers to dedicated Markdown apps.
• Cost reduction — Atlassian Cloud pricing increased by up to 35% in October 2025 (Valiantys, 2025), pushing some teams toward self-hosted Markdown wikis.
• Offline access — Markdown files work without a network connection, unlike Confluence Cloud.
• Speed — opening a local .md file takes milliseconds. Loading a Confluence page averages 2-4 seconds on Cloud instances.
• Growing adoption — Markdown usage on GitHub alone surpasses 3 billion files (GitHub Innovation Graph, 2025), making it the dominant format for technical documentation.

Over 50,000 companies use Confluence, but Atlassian Cloud pricing rose up to 35% in late 2025. Teams migrating to Markdown gain Git-native version control, offline access, and rendering speeds measured in milliseconds rather than the 2-4 seconds typical of Confluence Cloud page loads.

How Do You Export a Confluence Space to HTML First?

Export your space as HTML from Confluence's built-in export tool, then convert the HTML files to Markdown. Confluence does not export Markdown natively — but it does export HTML, which is the starting point for every conversion method below.

For Confluence Cloud:

1. Open the space you want to export.
2. Click Space settings in the sidebar.
3. Under Manage space, select Export space.
4. Choose HTML and click Next.
5. Select Normal Export (includes all pages) or Custom Export (specific pages).
6. Click Export and download the ZIP file when ready.

For Confluence Server / Data Center:

1. Go to Space tools > Content Tools.
2. Select Export.
3. Choose HTML and follow the prompts.

The exported ZIP contains HTML files, stylesheets, and an attachments/ folder with images. You will feed these HTML files into one of the conversion tools below.

Confluence does not offer a native Markdown export option. The built-in export supports HTML, PDF, and Word formats only. To get Markdown output, export to HTML first, then run the HTML files through a dedicated converter such as Pandoc, a Python CLI tool, or an Atlassian Marketplace app.

What Are the 5 Best Methods to Convert Confluence to Markdown?

The five best methods are: two Atlassian Marketplace apps (no-code), a Python CLI that uses the Confluence API, Pandoc for manual HTML conversion, and a Node.js converter using the Turndown engine. Here is each method with full setup instructions.

Method 1: Markdown Exporter for Confluence (Marketplace App)

The Markdown Exporter for Confluence runs entirely in your browser — no server-side processing, so your data stays within the Atlassian environment.

Steps:

1. Install the app from the Atlassian Marketplace.
2. Navigate to any Confluence page.
3. Click the ... menu and select Export to Markdown.
4. Choose single page or entire space.
5. Download the resulting .md files.

Pros: No command-line skills needed. Runs client-side. Handles tables and code blocks.

Limitations: Paid app (free trial available). Complex macros like Jira issue lists or draw.io diagrams may not convert cleanly.

Method 2: Export to Markdown for Confluence Cloud (Marketplace App)

Export to Markdown for Confluence Cloud by Atly Apps (version 5.3.0, released November 2025) offers similar functionality with additional options for attachment handling.

Steps:

1. Install from the Atlassian Marketplace.
2. Open a page or space.
3. Use the export action to generate Markdown files.
4. Download the ZIP containing .md files and images.

Pros: Actively maintained. Supports image export alongside Markdown files. Space-level batch export.

Limitations: Cloud-only. Pricing varies by team size.

Method 3: confluence-markdown-exporter (Python CLI)

The open-source confluence-markdown-exporter uses the Confluence REST API to pull pages directly and convert them to Markdown — no manual HTML export needed.

Steps:

1. Install via pip:

   pip install confluence-markdown-exporter

2. Generate an API token at id.atlassian.com/manage-profile/security/api-tokens.
3. Export a single page:

   confluence-markdown-exporter \
     --url https://yoursite.atlassian.net \
     --username your@email.com \
     --token YOUR_API_TOKEN \
     --page-id 123456 \
     --output ./exported-docs

4. Export an entire space:

   confluence-markdown-exporter \
     --url https://yoursite.atlassian.net \
     --username your@email.com \
     --token YOUR_API_TOKEN \
     --space-key TEAM \
     --output ./exported-docs

Pros: Free and open source. API-based — no manual export step. Handles child pages recursively. Tested on Confluence Cloud as of May 2025.

Limitations: Requires Python 3. API rate limits apply on large spaces. Image download depends on API permissions.

Important: Atlassian decommissioned several Confluence REST API v1 endpoints on March 31, 2025. Verify the tool version supports the current API before running.

Method 4: Pandoc + HTML Export (Manual Pipeline)

Pandoc has over 35,000 stars on GitHub and supports conversion between 40+ document formats (Pandoc GitHub, 2025). Combined with the HTML export described earlier, it handles the heavy lifting of HTML-to-Markdown transformation.

Steps:

1. Export your Confluence space to HTML (see the HTML export section above).
2. Unzip the export.
3. Install Pandoc:

   brew install pandoc    # macOS
   apt install pandoc     # Ubuntu/Debian
   choco install pandoc   # Windows

4. Convert a single HTML file:

   pandoc input.html -f html -t markdown -o output.md

5. Batch-convert all HTML files:

   for f in *.html; do
     pandoc "$f" -f html -t markdown -o "${f%.html}.md"
   done

Pros: Free. Handles complex HTML structures. Supports multiple Markdown flavors (GFM, CommonMark, MultiMarkdown). Runs locally — no data leaves your machine.

Limitations: Confluence-specific macros (status badges, Jira links, expand sections) export as raw HTML and require manual cleanup. Image paths need updating after conversion.

Tip: Use pandoc -t gfm (GitHub-Flavored Markdown) for the best compatibility with GitHub, GitLab, and most Markdown viewers.

If you have Confluence HTML exports ready, you can also use our free HTML to Markdown converter for quick one-off conversions without installing anything.

Method 5: confluence-to-markdown (Node.js)

The confluence-to-markdown npm package by meridius processes Confluence HTML exports and produces clean Markdown. It offers two conversion engines: Turndown (default) and Pandoc (optional).

Steps:

1. Export your space to HTML from Confluence.
2. Clone and install:

   git clone https://github.com/meridius/confluence-to-markdown.git
   cd confluence-to-markdown
   npm install

3. Place your HTML export in the input/ directory.
4. Run the conversion:

   npm run start

5. Find converted Markdown files in the output/ directory.

Pros: Free. Turndown engine produces cleaner Markdown than raw Pandoc for Confluence-specific markup. Handles internal links and attachments.

Limitations: Requires Node.js. Not published as a global CLI — you clone the repo. Last major update may not cover recent Confluence Cloud export format changes.

How Do You Clean Up Converted Markdown Files?

Every converter leaves artifacts — broken links, wrong image paths, residual HTML, and malformed tables — that require manual cleanup. No tool produces perfect Markdown from Confluence. Here is what typically needs attention after conversion:

Broken internal links. Confluence uses page IDs and space keys in URLs. After conversion, internal links point to nonexistent paths. Search for href= or ]( patterns and update them to your new file structure.

Image paths. Exported images land in an attachments/ or images/ folder. You may need to move them to a static/ or public/ directory and update paths in the Markdown files.

Residual HTML. Confluence macros that have no Markdown equivalent (expand sections, status badges, Jira issue panels) export as raw <div> or <ac:structured-macro> blocks. Delete or replace them with Markdown alternatives.

Table formatting. Complex tables with merged cells or nested content may break during conversion. Verify each table renders correctly in your target viewer. A Markdown table generator can help rebuild broken tables from scratch.

Front matter. If you are moving to a static site generator (Hugo, Astro, Jekyll), you need YAML front matter at the top of each file. No converter adds this automatically — build a script or add it manually.

---
title: "Your Page Title"
date: 2026-03-25
tags: ["documentation", "migration"]
---

Which Method Should You Choose?

Use a marketplace app if you want zero setup, the Python CLI for automated bulk exports, or Pandoc for full control over Markdown flavor.

For a single page: Use a marketplace app or copy-paste the page content into our HTML to Markdown tool.

For an entire space (10-100+ pages): Use the Python CLI exporter if you want API-based extraction, or Pandoc if you prefer working from an HTML export.

For ongoing sync: None of these tools provide real-time sync. If you need bidirectional Confluence-Markdown integration, look at markdown-confluence which publishes Markdown files to Confluence.

For non-technical teams exporting fewer than 10 pages, a marketplace app is the fastest option. For developers migrating an entire Confluence space of 100+ pages into a Git repository, the Python CLI exporter or Pandoc batch conversion provides the most control and automation.

How Do You View the Converted Markdown Files?

Use a native Markdown viewer for instant rendering with live reload — far faster than re-importing into a wiki or opening files in a browser. After converting your Confluence documentation to Markdown, you need a way to review hundreds of .md files quickly. Opening each file in a browser or text editor is slow.

On macOS, MacMD Viewer renders Markdown files instantly with live reload — edit in VS Code or any editor, and see changes in real time. It handles tables, code blocks with syntax highlighting, and even Mermaid diagrams that Confluence cannot render natively. At 2 MB, it launches faster than loading a single Confluence page.

For cross-platform needs, check our guide to viewing Markdown files covering tools for Mac, Windows, Linux, and the terminal.

FAQ

Does Confluence have a built-in Markdown export?

No. Confluence exports to HTML, PDF, and Word, but not Markdown. You need a third-party tool or marketplace app to convert Confluence content to Markdown format.

Will my Confluence tables survive the conversion?

Simple tables convert cleanly with all five methods. Tables with merged cells, colored rows, or nested content often break and need manual cleanup. Use a Markdown table generator to rebuild complex tables.

Can I convert Confluence to Markdown without admin access?

Yes. The Python CLI exporter and marketplace apps work with regular user permissions. You only need an API token (for the CLI) or the app installed by an admin (for marketplace apps). The Pandoc method works with any HTML export you can download.

What about Confluence macros — do they convert?

Standard formatting (headings, lists, code blocks, images) converts well. Confluence-specific macros like Jira issue lists, draw.io diagrams, roadmaps, and status badges do not have Markdown equivalents and export as raw HTML or get dropped entirely.

Is there a way to automate ongoing Confluence-to-Markdown sync?

Not with the tools in this guide — they are one-time export tools. For continuous sync, look at CI/CD scripts that use the Confluence API to pull content on a schedule, or use the markdown-confluence project to push Markdown files into Confluence (reverse direction).