Confluence to Markdown: convert your wiki cleanly

TL;DR. Confluence does not export to Markdown directly. You export a space as HTML or XML, then convert: pandoc or a script for a folder of loose files, or a wiki importer that consumes the Confluence export and writes Markdown while rebuilding the page tree. Plain text, headings, lists, and code blocks convert cleanly. Macros, nested tables, and internal page links are where fidelity leaks. The importer route loses the least, because it rewrites links and re-hosts attachments in one pass.

Converting Confluence to Markdown is the kind of project that sounds like a one-click button and turns out to be a weekend. There is no one-click button. Confluence does not write Markdown, so converting Confluence to Markdown means taking the HTML or XML that Confluence does export and turning it into clean Markdown on the other side. This post is the practical version: the export formats you actually get, the three conversion routes, the parts that break, and how to land the result in a wiki that reads Markdown natively. (If you are still deciding whether to leave at all, our what is Confluence explainer covers the stay-or-go test first.)

Why Markdown is the format worth converting to

Markdown wins on three things, and none of them is fashion.

It is portable. A Markdown file is plain text with a handful of punctuation conventions. Every modern editor, wiki, and static site generator reads it. The format is small enough that the CommonMark specification fits in an afternoon’s reading, which is why so many tools agree on it.

It diffs cleanly. Plain text lives happily in Git. A one-word change in a Markdown doc is a one-line diff. The same change inside a proprietary wiki’s database is invisible to version control — you get the wiki’s own history view and nothing your engineers can review in a pull request.

It survives tool changes. This is the real reason. Wikis come and go; your documentation should outlive the vendor you happened to pick. Markdown is the closest thing documentation has to a long-term storage format. Store your knowledge as Markdown and the next migration is a copy, not a project.

The export formats Confluence actually gives you

Before you convert anything, you need to know what Confluence hands over. There are three exports worth knowing, and Markdown is not one of them.

Space export to HTML. From space settings, Confluence produces a zip of one HTML file per page, plus an attachments folder and an index.html. This is the most useful export for conversion because HTML is something every converter understands. The macros have already rendered to HTML, which is both a blessing (you get something) and a curse (you lose the macro’s identity).

Space export to XML. The same space settings offer an XML export. This is Confluence’s own storage format — closer to the source of truth, with the macro structure intact, but in a format only Confluence and purpose-built importers parse. It is the right input for an importer and the wrong input for pandoc.

Per-page PDF and Word. Useful for sharing a single page with someone outside the wiki. Useless for converting to Markdown, because you would be reverse-engineering layout back into structure. Skip these for migration.

Atlassian’s own documentation on the space export options is the authoritative reference for where the buttons live, because the admin UI moves more often than the formats do.

The conversion process, step by step

Here is the route that loses the least, regardless of which tool you use for the conversion itself.

Audit before you export. Open the space and count the macro-heavy pages. The pages with embedded Jira lists, custom widgets, and nested tables are the ones that will need hand cleanup. Knowing the count up front turns a surprise into a task list.
Export the whole space, not page by page. Use the HTML export for a script-and-pandoc route, or the XML export if your target wiki has an importer that reads it. A space export keeps the page hierarchy in one bundle.
Pick your conversion route. Pandoc for a single page or a small scripted batch; an importer when you want the page tree and attachments rebuilt for you. More on both below.
Convert the content. Run pandoc over each HTML file, or feed the export to the importer. Headings, lists, links, images, and code blocks come through cleanly here.
Fix the links and attachments. Internal page links and image paths are the fragile part. Rewrite Confluence page-ID links to your new wiki’s paths, and confirm every attachment resolves. An importer does this step for you; a script will not unless you write it.
Spot-check the macros. Walk the macro-heavy pages from step one. Confirm callouts landed as callouts and code blocks landed as code. Replace anything custom by hand.
Land it in the new wiki and validate. Import the Markdown, click through the tree, and search for a few pages you know exist. If search finds them and the links work, you are done.

The three ways to actually do the conversion

Pandoc, for one page or a scripted batch. Pandoc reads HTML and writes Markdown, and it is excellent at it. For a single exported page, one command does the job. For a whole space, you script pandoc across every HTML file in the export. Pandoc does not know what a Confluence macro is, so a macro that rendered to a table of divs arrives as a table of divs. You get clean Markdown for the prose and a cleanup list for everything else.

A custom script. Some teams write their own converter against the XML export because they want exact control over how their specific macros map. This is the most work and the most precise result. It only pays off when the space is large, the macros are repetitive, and someone on the team enjoys writing parsers. Most teams do not meet all three conditions.

Importer-led conversion. A wiki that ships a Confluence importer consumes the HTML or XML export directly and writes Markdown-native content on the way in. The advantage is that the importer rebuilds the page tree, re-hosts attachments, and rewrites internal links in the same pass — the three steps that take longest by hand. Our Confluence importer is the example we know best; it converts common macros (info, tip, note, warning callouts, code blocks, status) on a best-effort basis and handles most wikis in under ten minutes.

Where the conversion loses fidelity

Honest section. Converting Confluence to Markdown is lossy, and pretending otherwise is how migrations go sideways at 2am.

Macros. Markdown has no concept of a macro. The standard panels — info, tip, note, warning — convert to callouts on a best-effort basis, because every good importer special-cases them. Custom macros, third-party marketplace macros, and dynamic content like live Jira issue lists do not survive. They were never static content; they were instructions to a server you are leaving.

Nested tables and layout columns. Markdown tables are flat by design. A Confluence table with a table inside a cell, or a multi-column page layout, flattens. The data survives; the nesting does not. Plan to reshape these pages by hand.

Attachment links and Unicode. This is the one that bites quietly. A migration once shipped here turned a small mammal into a different small mammal on export — pages with the raccoon emoji came out the other side as a rabbit, courtesy of a “small mammal normalisation” lookup table inherited from a third-party CSV-export helper written before the team included any raccoons. The fix was a one-line deletion (PR #2: delete the table; we are an employer that includes raccoons). The lesson stuck: Unicode normalisation on export will happily rewrite your content into something almost-but-not-quite right, and almost-but-not-quite is worse than broken because nobody notices until the page about the raccoon is about a rabbit. Check your exported encoding before you trust it.

When not to bother. If your team is heavily on Jira and the Confluence-and-Jira loop is doing real work, converting to Markdown to leave may cost more than it saves. A wiki you have already trained your whole team on has switching costs that a cleaner format does not always beat. Convert when the writing has already moved elsewhere — when your fastest writers draft somewhere else and paste in — not before.

You’re never locked in, and that’s the point

Here is the opinion this whole post stands behind: a wiki that can’t hand you clean, portable content isn’t storing your knowledge, it’s holding it. Markdown is the portability layer. The reason to convert Confluence to Markdown is the same reason to prefer any tool that exports it — your documentation should outlive your choice of wiki.

We hold ourselves to the same standard we are asking of an export. Every Raccoon Page plan, including the free one, exports everything as Obsidian-compatible Markdown: per-space zip and per-page Markdown, anytime, no sales call. You can import a Confluence space and export it back out the same afternoon. The number behind the claim is the one that matters: it is on every plan, not the expensive one. If the only way out of a wiki is a PDF and a prayer, the wiki was never really yours.

If you would rather start from Markdown files you already have — say, the output of a pandoc run — our Markdown import reads them directly, so the script route and the importer route meet in the middle.

Things people actually ask

Does Confluence export directly to Markdown? Not natively in most versions. Confluence Cloud exports a space to HTML or XML, and individual pages to PDF or Word. Markdown is not a first-class export target, so you convert from the HTML or XML Confluence gives you, or you point a wiki importer at the export and let it write Markdown on the way in.

What is the best way to convert Confluence to Markdown? For one or two pages, paste into a converter or run pandoc on a single HTML file. For a whole space, export the space as HTML or XML and either run a batch script over it or hand the export to a wiki importer that consumes Confluence exports directly. The importer route is usually the least painful because it also rebuilds the page tree and re-hosts attachments.

What breaks when you convert Confluence to Markdown? Macros are the big one. Info, tip, note, and warning panels convert to callouts on a best-effort basis, but custom and third-party macros usually do not survive. Nested tables, layout columns, embedded Jira issue lists, and complex attachment links are the other common casualties. Plain text, headings, lists, links, images, and code blocks convert cleanly.

Can pandoc convert Confluence HTML to Markdown? Yes. Pandoc reads HTML and writes Markdown, so it handles a single exported Confluence page well. It does not understand Confluence macros as a concept, so anything that rendered as a macro arrives as whatever HTML the export produced. For a whole space you script pandoc over every HTML file and then clean up attachment paths and callouts by hand.

How long does a Confluence-to-Markdown migration take? The export itself is minutes. The conversion is where time goes. A script-and-pandoc approach on a large space can take a day of cleanup. An importer that consumes the Confluence export directly handles most wikis in under ten minutes, because it converts and rebuilds the tree in one pass instead of leaving you a folder of loose Markdown files.

Will my page links survive the conversion to Markdown? Internal links between Confluence pages are the fragile part. A raw HTML or XML export points links at Confluence page IDs and URLs, which break the moment the content leaves Confluence. A good importer rewrites those links to the new wiki’s page paths. A hand-rolled script will not unless you write the link-rewriting step yourself.

Why convert Confluence to Markdown at all? Markdown is portable, diffs cleanly in version control, and survives tool changes. Content stored as Markdown can move to any modern wiki, sit in a Git repo, or be read by an AI agent without a proprietary export step. It is the closest thing documentation has to a long-term storage format.

Does Raccoon Page import Confluence exports? Yes. The Confluence importer consumes the HTML or XML space export, rebuilds the page tree, re-hosts attachments, and converts common macros to native blocks on a best-effort basis. Confluence import is available on the Team and Business plans, and most wikis import in under ten minutes.

Confluence to Markdown is two jobs wearing one trench coat: a five-minute export and an afternoon of conversion. Do the export, pick pandoc for a page or an importer for a space, and watch the macros — they are where the bodies are buried. Then land it somewhere that reads Markdown natively, so the next time you change wikis it is a copy and not a campaign. Worst case, you keep the Markdown and the wiki was just a viewer. That is exactly how it should feel.