Export Confluence to Markdown and keep it in Git

Confluence has no export to Markdown. Its built-in exports are Word, PDF, HTML, XML and CSV, so a move to Markdown in Git always takes two steps: get the content out, then convert it. This post compares four ways to do both, says what each loses on the way, and ends with a checklist you can run on a trial space before you commit to the move.

We moved our own wiki out of Confluence, so the pitfalls below come from that move and from the converter we built, not from theory. What Atlassian offers was checked against its documentation on 19 October 2026. It changes, so look again before you plan.

What "Markdown in Git" has to mean

Be exact about the goal before you pick a tool. Markdown in Git means four things: each page is a .md file, the page tree is a folder tree, images and attachments sit in the repository next to the pages, and links between pages are relative paths that still resolve. A way that gives you the text but breaks the other three leaves you a pile of files, not a wiki.

Way 1: the built-in export, then a converter

In Confluence Cloud one page exports to Word or PDF, and only its published version. A space exports to PDF, CSV, HTML or XML; CSV and XML come as a zip, and only space admins can export a space. Atlassian's page on exports adds that an organization's admins can block exports, that HTML exports leave out comments and blog posts, and that a space export holds only what the person exporting can view.

The HTML export is the useful one. Run it through a general converter such as Pandoc, which reads HTML and writes GitHub-Flavored Markdown, and you get one file per page with headings, lists and tables in place. Macros are the weak point: the HTML holds whatever each macro drew, in Confluence's own markup, and a general converter knows nothing about it. Expect to review panels, code blocks and task lists by hand.

Pick this way for an archive of a space, when the text matters more than the structure and you do not mind some cleaning.

Way 2: read the pages through the REST API

If you want control, read the pages yourself. The Confluence Cloud REST API v2 returns a page by id, and its body-format parameter takes values such as storage, atlas_doc_format and view. Listing the pages of a space is paged: a request returns up to 250 pages and the Link header points at the next set. Data Center and Server have the older API, where a content request with expand set to body.storage returns the same storage format. According to Atlassian's REST introduction, the API supports basic auth, and apps sign in with OAuth 2.0 or JWT.

The storage format is the richest source. It is XML in which every macro is a tag with its name and parameters, so a converter can tell an info panel from a code block and a task from a list item. It is also the most work: you write the conversion, fetch attachments with a second call per page and rebuild the tree from the parent links. Plan on a script that you keep fixing against your own pages.

Way 3: a free converter for single pages

Our Confluence to Markdown converter takes a pasted page and returns GitHub-Flavored Markdown. It reads the storage format, an exported HTML file or content copied from a rendered page, and it runs in your browser, so what you paste is not uploaded. Code macros become fenced code, info, note, warning and tip macros become callouts, task lists become checkboxes and expand macros become collapsible blocks. A macro it does not know is left as an HTML comment with its name, so you can see where it stood.

It does one page at a time and does not download images: the Markdown names each attachment and you bring the files. It cannot reproduce macros that need Confluence to run, such as a table of contents, a page tree, include page, Jira issue lists, or draw.io and Gliffy diagrams. Use it to see how your content converts, or to move five or ten pages.

Way 4: import a page or a whole tree into Folio

Folio is a wiki whose pages are Markdown files in a Git repository, and it has an importer for the whole job. In the import dialog you give the address of a Confluence page, choose the page alone or the tree below it, and sign in: an email and an API token for Confluence Cloud, or a personal access token for an on-premises installation. Folio reads the pages through the Confluence API and writes them into a space.

On the way, panels become callouts, code stays code, task lists stay checkboxes, status macros become status tags, and images and other attachments are stored with the space. The page tree becomes folders: a page with children turns into a folder with its own index page. Whiteboards from Confluence Cloud become editable Excalidraw boards. The imported root never replaces the space's home page, and importing the same tree again updates it in place instead of making a copy.

Because a Folio space is a Git repository, the result is the one you set out to get: Markdown files in Git, edited in the browser by the team and in an IDE by developers. Two limits. The importer does not support every macro, and the limitations list tells you to run a test import before you move a whole space. And the public demo has Confluence import switched off, because the importer would connect to a host chosen by the visitor, so you need your own installation to try it.

What breaks, whichever way you choose

• Macros. Anything Confluence computes, such as a table of contents, a page tree, include page or a Jira list, has no Markdown form. Decide per macro: drop it, replace it with a plain list of links, or use what the new wiki has. Folio shows a page outline by itself and has a live page-tree directive, which covers the first two.
• Images and attachments. Exports and the free converter refer to files by name. Check that every image link opens and that the files end up next to the pages. In Folio images go to the space's own store by default; a space admin can switch on storing images in the repository, which is what you want when the repository must be complete on its own.
• Links. Links between pages point at Confluence addresses or page ids. After the move they must become relative paths. Run a link checker over the result. Over MCP an agent can also list the links in a Folio space that point at nothing.
• Permissions. Page restrictions and space permissions are not part of the page body, and none of these ways carries them over. Rebuild access in the new place before you let people in. Folio sets roles per space and can narrow a single page.
• Comments, history and labels. The converter does not touch them, the HTML export leaves out comments, and Folio's import does not bring the Confluence version history: the history in Git starts at the import. Keep the old space read-only for a while as the archive.
• Tables. Merged cells are split into empty cells, because Markdown tables cannot merge.

A checklist for the trial run

• Pick 10 to 20 pages that hold your worst cases: macros, many images, a deep tree, a table with merged cells, a restricted page.
• List the macros in them and decide what each one becomes.
• Convert them with one of the ways above into a throwaway repository or space.
• Open each result in a Markdown preview and compare it with the original: tables, code, callouts, images.
• Run a link check and fix the links that still point at Confluence.
• Rebuild permissions in the target and test them with a person who should not see everything.
• Convert the whole space in one go, commit it as one commit and read the diff.
• Make the Confluence space read-only, keep it for a few months and tell people where the pages went.

Try it

If you only need Markdown, the converter and Pandoc are enough. If the team will keep editing afterwards, look at where you are going: our list of Confluence alternatives compares the options with sources and dates, and Folio vs. Confluence says where Folio does not fit, for example if you need SSO, SCIM, Marketplace apps or Jira-connected workflows. To see what a wiki in Git looks like, open the public demo; to run the importer, follow the install guide. If the pages should live next to your code, read docs-as-code in the browser.

All posts