How to Export Confluence to Markdown

Converting Confluence to Markdown takes one of three routes. Export a page to Word and convert the .docx, export a space to HTML and convert each file, or pull pages from the API with the confluence-markdown-exporter CLI. Confluence has no Markdown export of its own, so this guide shows which route fits each job.

Does Confluence Have a Native Markdown Export?

No. Atlassian's export documentation for Confluence Cloud lists Word and PDF for a single page, from the page's more actions menu, then Export. A whole space exports as PDF, CSV, HTML, or XML from Space settings, General, Export space. Markdown isn't in either list.

Data Center is the same story with different menus. Per the Data Center export page, a page exports from Tools to PDF or Word. A space exports from Space tools, Content Tools, Export as HTML or PDF, with XML under the Back up tab.

So every Confluence export to Markdown is a two-step job or a third-party tool, and a search for confluence export markdown turns up both. That's not as bad as it sounds, and it's why no menu offers a Confluence export as Markdown. Confluence pages are stored as structured content. Both the HTML export and the API preserve headings, lists, tables, and code blocks well enough that a converter does most of the work.

Which Confluence Export Method Fits Your Job?

Match the size of the job to the cheapest method that handles it.

We prefer the CLI for anything larger than a handful of pages. It skips pages that haven't changed since the last run, so you can re-export a space weekly during a migration instead of redoing the whole thing.

One acknowledged limitation: page comments are easy to lose. Atlassian's Cloud docs say comments aren't included in the HTML export, and blog posts aren't either. If comments carry decisions, copy them by hand or use the CLI, which writes them to sidecar files.

Method 1: Export a Confluence Page to Word and Convert It

This is the zero-install path for a single page.

1. Open the page, click the more actions menu (the three dots), then Export, then Export to Word.
2. Atlassian notes that the exported file only opens in Microsoft Word and not in LibreOffice or Google Docs, so don't try to clean it up elsewhere first.
3. Drop the .docx into the DOCX to Markdown converter and copy the output.

Headings, bold and italic text, lists, simple tables, and links have direct Word equivalents and convert cleanly. Word has no concept of a code fence, so check every code block and re-fence any that arrived as styled paragraphs. Info, tip, and warning panels lose their colour and icon and become plain paragraphs.

Method 2: Export Confluence to HTML and Convert Each Page

For a page tree or a whole space, the HTML export is the route that needs no install. In Cloud, go to Space settings, General, Export space, choose HTML, and pick either the whole space or a custom selection of pages. You get a zip with one HTML file per page and, per Atlassian's docs, page attachments in individual folders named by page ID.

Unzip it, then convert each file. For a few pages, open the HTML and paste the page body into the HTML to Markdown converter. For many pages, Pandoc handles a folder in one loop:

for f in *.html; do
  pandoc "$f" -f html -t gfm-raw_html --wrap=none -o "${f%.html}.md"
done

-t gfm-raw_html writes GitHub Flavored Markdown and drops the HTML wrappers Confluence puts around every macro, and --wrap=none keeps paragraphs on one line. A typical exported runbook page comes back looking roughly like this:

# Deployment Runbook

Run this only after the release branch is tagged.

## Steps

1.  Merge `release/2.4`
2.  Run the pipeline

|         |                         |
|---------|-------------------------|
| Env     | URL                     |
| Staging | https://stg.example.com |

``` syntaxhighlighter-pre
./deploy.sh --env staging
```

![](attachments/123456/789.png)

Rollback

Run `./deploy.sh --rollback`.

Four things to fix are visible right there (an empty table header row, a fence with a class name instead of a language, an unlabelled image, and a flattened expand macro), and they show up on almost every page. The HTML to Markdown guide covers the generic conversion rules; the next section covers the Confluence-specific cleanup.

Cleaning Up Confluence Macros After Conversion

Confluence macros are the part converters can't fully handle, because Markdown has no equivalent for most of them. Here's what each one becomes and how to rebuild it.

Info, note, tip, and warning panels. They export as nested div elements with a class such as confluence-information-macro-information. Converters flatten them to a plain paragraph, so the panel type is lost. Rebuild them as GitHub alerts (> [!NOTE]) or Obsidian callouts; the Markdown callout guide shows the syntax for each platform.

Tables. Confluence marks header cells with th but doesn't always wrap them in a thead, so Pandoc can produce an empty header row with the real header in the body. Move the first row up into the header position. Merged cells have no Markdown equivalent and become repeated or empty cells; the Markdown table guide explains the limits.

Code blocks. The exported pre element carries the class syntaxhighlighter-pre instead of a language, so the fence gets a useless info string. Replace it with bash, python, or whatever the block contains.

Images and attachments. The HTML export references images as relative paths into the attachments folders, so the ![](attachments/123456/789.png) links work as long as you keep the folder next to the Markdown. Rename the files to something readable before you commit them.

Expand macros. The title and body survive as two plain paragraphs with nothing marking them collapsible. Wrap them in a details element if the destination renders HTML.

Jira issue macros, page-tree macros, and user mentions. These are rendered from live data and export as whatever text was on screen, often just an issue key or a name. Replace the Jira key with a link and delete page-tree output, which is just a stale list of child pages.

Try the converted page in the editor

The editor below holds the runbook after cleanup. The header row is fixed, the code block restored, the panel rebuilt as a GitHub alert, and the expand macro turned into a details block. Compare it with the raw Pandoc output above. One note on the preview: the editor renders > [!NOTE] as a plain blockquote, because alert syntax is a GitHub extension; GitHub adds the icon and colour.

./deploy.sh --env staging

The converter tab takes raw HTML, so you can also paste a page body copied from the exported file and see the first-pass Markdown before you start the cleanup.

Method 3: Export Confluence to Markdown With the cme CLI

For a whole space, or anything you'll export more than once, use the open source confluence-markdown-exporter. It talks to the Confluence API and writes Markdown directly. Its README installs it with a single script on macOS and Linux; Windows gets a PowerShell equivalent, and PyPI or Docker are alternatives.

curl -LsSf uvx.sh/confluence-markdown-exporter/install.sh | sh
cme config edit auth.confluence

The second command asks for your Confluence URL, username, and an API token. Then export at whichever scope you need:

cme pages <page-url>
cme pages-with-descendants <page-url>
cme spaces <space-url>

Output lands in the current directory unless you set export.output_path. The project's feature list says it converts headings, lists, tables, links, images, attachments, language-aware code blocks, task lists, and info, note, tip, and warning panels into Markdown alert blocks. Page labels become tags, and page properties can be written as YAML front matter. Comments are exported as sidecar files, which makes this the only route that keeps them. It also ships target presets for Obsidian and Azure DevOps.

You still need a cleanup pass for Jira macros and mentions, but it's far shorter than the HTML route. Version 5.4.0 is the release the README shows in its install examples; check the docs site for the current one.

Confluence to GitHub Markdown: Final Checks

If the destination is a GitHub repository or wiki, three adjustments make the export render properly.

1. Use GFM tables and alerts. GitHub renders pipe tables and > [!NOTE] alerts, so the Pandoc output and the CLI's alert blocks work unchanged.
2. Fix image paths. Put the attachments folder inside the repository and make the image links relative to the Markdown file. GitHub doesn't render absolute paths into your old Confluence site.
3. Strip inline styles. Confluence exports font colours and highlights as span elements with style attributes. GitHub removes inline styles, so delete the dead HTML.

The GitHub Markdown cheat sheet lists every GFM feature you can use in the cleaned-up files. The reverse direction, getting Markdown into Confluence, is covered in the Confluence Markdown guide.

Confluence to Markdown FAQ

Getting Confluence to Markdown cleanly is about picking the right scope. Use the Word export for one page, the HTML export for a tree, and the cme CLI for a space or a repeatable migration. Whichever you choose, budget time to rebuild panels and tables. Paste each converted page into the editor to check that the tables and code fences render before you commit them.