Atlassian Tools
Markdown Exporter or DIY Pipeline? Choosing How to Export Confluence to Markdown
•
min read
Use a dedicated app such as Markdown Exporter for Confluence by Narva Software when you need a page, page tree or entire space turned into Markdown without writing code; build your own pipeline on the Confluence REST API, an HTML export and Pandoc when you need a custom transform and you have engineering capacity for building DIY pipeline.
Both routes end in valid Markdown. They differ in who does the work of rebuilding page hierarchy, image paths, attachments and macro output. Atlassian's own documentation states that Confluence stores page content in an XHTML-based storage format, so nothing in Confluence is Markdown until something converts it. This article explains what each route handles, what breaks, what it costs in engineering hours, and how to decide.
The short answer
Choose Markdown Exporter for Confluence by Narva Software if you need hierarchy, images and attachments preserved in one ZIP today, with no code and no credentials.
Choose Pandoc if you already have HTML or XML exports, want a free conversion you can script, and will rebuild the page tree and asset links yourself.
Choose the Confluence REST API if the export must run repeatedly inside a pipeline, with custom front matter or transforms you maintain.
Pandoc, written by John MacFarlane and released under the GPL, converts between more than 40 markup formats and is the reference tool for this kind of work. It is not a Confluence client, and that distinction drives most of the decision below.
What a DIY Confluence → Markdown pipeline actually involves
Route 1: REST API plus Turndown or a custom converter
The Confluence Cloud REST API returns storage format: HTML with Confluence-specific macro elements such as ac:structured-macro. Converting it means handling six things yourself.
Authentication. Atlassian Cloud uses an email address plus an API token, or OAuth 2.0.
Pagination. Content endpoints return a default page of 25 results, so a 4,000-page space means at least 160 requests before you fetch a single attachment.
Rate limits. Atlassian's REST API documentation describes cost-based rate limiting that answers with HTTP 429 and a Retry-After header. Your script needs backoff logic or it will stall midway through a large space.
Attachments. Each file is a separate download, and the returned URLs are absolute and access-controlled.
Link rewriting. Internal page links use page IDs. Every one has to be mapped to the relative path of the Markdown file you eventually write.
Macros. Tables of contents, code blocks, expand panels, Mermaid and draw.io diagrams each resolve differently, and many carry no body text in storage format at all.
Turndown, Dom Christie's MIT-licensed HTML-to-Markdown library, handles the markup conversion well and supports custom rules for unknown elements. It converts what you give it. It has no opinion about your page tree.
Route 2: Space export to HTML or XML, then Pandoc
Confluence can export a space to HTML or XML. Pandoc then converts those files to GitHub Flavored Markdown with -f html -t gfm. This is the cheapest technical route and it works.
What Pandoc does well: accurate markup conversion, a GFM target that matches what GitHub and GitLab render, and full scriptability. What it does not do: reach into Confluence, understand your page tree, rename files to readable slugs, or rewrite image and attachment references. Confluence's HTML export names files by page ID, so a raw Pandoc run produces a flat folder of files such as 1234567.md.
"Because Pandoc's intermediate representation of a document is less expressive than many of the formats it converts between, one should not expect perfect conversions between every format and every other."
— Pandoc User's Guide, John MacFarlane
Conversion fidelity is a spectrum: work skipped at conversion time reappears as cleanup time.
Route 3: Open-source CLI exporters
Community projects such as confluence-markdown-exporter, installable with pip, wrap the REST API and emit Markdown directly. They are free, scriptable, and often good enough for a technical team exporting its own space. Attachment, macro, and diagram coverage varies by project; releases depend on volunteer time, and Atlassian API changes can break them between versions. Read the open issues before you commit to a migration deadline.
What a dedicated exporter does instead
Markdown Exporter for Confluence by Narva Software is an app installed from the Atlassian Marketplace. The workflow is mechanical: install the app, open a page, select a single page, a page tree, or an entire space, run the export, and download a ZIP.
The ZIP contains GitHub Flavored Markdown files. The page hierarchy becomes the folder structure. Images and attachments are exported next to the Markdown and referenced by relative path, so the files render correctly the moment you drop them into a Git repository or a static site generator. Tables, code blocks, and diagrams are converted by the app rather than left as raw storage-format markup. Processing runs client-side, so page content is not sent to a third-party server for conversion — which matters when the space holds customer data.
Anyone with permission to view the pages can run it. No API token, scripting environment, or Pandoc needed.
Export a Confluence space without writing code
Markdown Exporter for Confluence by Narva Software exports a page, page tree or entire space as Markdown, with the hierarchy, images and attachments preserved in one ZIP. Install it from the Atlassian Marketplace and run your first export in minutes.
Markdown Exporter or DIY Pipeline? A Side by Side comparison
Criterion | Markdown Exporter for Confluence (Narva Software) | DIY: REST API / HTML export / Pandoc |
Setup | Install from the Atlassian Marketplace, no code | Scripting environment, API credentials, Pandoc install |
Skills needed | Any Confluence user with export permission | Developer comfortable with APIs and scripting |
Page hierarchy | Preserved in the exported folder structure | Must be reconstructed from API metadata yourself |
Attachments | Exported and linked | Fetched separately and re-mapped by hand |
Images | Exported with working relative paths | Paths and references must be rewritten |
Scope | Page, page tree or entire space | Whatever you build support for |
Output | Markdown (GFM) plus assets, as a ZIP | Whatever the pipeline emits |
Macros and diagrams | Handled by the app | Solved case by case, often left as raw markup |
Time to first export | Minutes | Hours to weeks, depending on fidelity |
Repeatability | Same workflow every time | Repeatable once built; breaks when formats change |
Customisation | Limited to the app's options | Complete — any transform you can write |
Automation | Run on demand from Confluence | Schedulable, pipeline-friendly |
Maintenance | Vendor-maintained | Yours to own |
Cost | Marketplace licence | Free software, paid engineering time |
Best for | Teams who need the export done | Engineers who need a custom, automated pipeline |
When a DIY pipeline is the better choice
The export runs on a schedule. Nightly or per-commit syncs belong in cron or CI, not in a manual click.
You need custom front matter. Static site generators such as Hugo, Jekyll and Docusaurus expect specific YAML keys, and only your script knows which.
The target is not standard Markdown. MDX, reStructuredText, AsciiDoc, and bespoke formats all need transform rules of your own.
You are extending existing tooling. If a documentation pipeline already reads from the Atlassian API, adding an export step is cheaper than adding a vendor.
Developer time is already budgeted. When the build is funded, control is worth more than speed.
Marketplace apps are not permitted. Some regulated environments block third-party app installation outright.
When Markdown Exporter for Confluence by Narva Software is the better choice
Migrating an entire Confluence space
Bulk export at space level is the job the app is built for. To export an Entire Confluence Space to Markdown - select the space, run one export, and receive every page as Markdown with the hierarchy intact. Migrations off Confluence Server rose sharply after Atlassian ended Server support in February 2024, and most of them are one-way moves where building a pipeline you will run once makes little sense.
Confluence to Git
Docs-as-code workflows need Markdown files, a folder structure, and relative asset links — exactly what the ZIP contains. Unpack it into the repository, commit, and the diff is readable. Markdown Exporter for Confluence by Narva Software keeps the tree shape, which is what makes the first commit reviewable rather than a flat dump of page IDs.
Confluence to Markdown for an LLM or RAG pipeline
Retrieval pipelines chunk on structure, and Markdown headings are the cleanest boundary available. LangChain's MarkdownHeaderTextSplitter, for example, splits on # levels directly. Clean Markdown with intact headings and no leftover macro markup produces better chunks than scraped HTML, and Markdown Exporter for Confluence by Narva Software produces it in one pass.
Archive and backup
Markdown is plain text, which makes it durable, diffable, and readable without Confluence. An annual export gives you an archive that will still open in twenty years.
How to export an entire Confluence space to Markdown
1. Install the app. Add Markdown Exporter for Confluence by Narva Software from the Atlassian Marketplace to your Confluence Cloud site.
2. Open the space. Confirm you can view every page you want included; the export respects Confluence permissions.
3. Choose the scope. Single page, page tree, or the whole space.
4. Run the export and download the ZIP. Markdown files, folders matching the hierarchy, and assets linked by relative path.
A short decision checklist
Does someone on the team write and maintain scripts? No → dedicated exporter.
Do you need images and attachments to work after the export? Yes → dedicated exporter, or budget the link-rewriting work.
Is the target standard Markdown or GFM? No → DIY pipeline.
Does the page hierarchy have to survive? Yes → dedicated exporter, or write the tree-walking code.
Is there a fixed migration deadline? Yes → dedicated exporter.
Frequently asked questions
Use Pandoc if you already have Confluence content exported as HTML or XML, want a free, scriptable conversion, and are willing to rebuild page hierarchy, image paths, and attachment links yourself. Use a dedicated app such as Markdown Exporter for Confluence by Narva Software if you need a page, page tree, or entire space in Markdown without writing code, bulk export with hierarchy, images, and attachments preserved in a single ZIP. Visit the product documentation for Markdown Exporter for Confluence by Narva Software to learn more about export scopes, output structure and supported macros.
No. Pandoc has no Confluence connector. You first export content from Confluence as HTML or XML, then run Pandoc over the exported files. Pandoc converts markup accurately, but it does not rebuild the page tree, rewrite image and attachment references, or resolve Confluence macros and diagrams — those remain your problem.
It works and gives you the most control, but the API returns Confluence storage format (XHTML), not Markdown. A usable pipeline has to handle authentication, pagination, rate limits, attachment downloads, link rewriting and macro content, then convert with something like Turndown or Pandoc. Expect days to weeks of engineering plus ongoing maintenance when formats change.
The fastest no-code route is Markdown Exporter for Confluence by Narva Software: select the space, run a bulk export, and receive a ZIP of Markdown files with the page hierarchy, images and attachments intact. The DIY routes are a space-level HTML or XML export converted with Pandoc, or a script that walks the REST API page by page.
Markdown Exporter for Confluence by Narva Software preserves the page hierarchy as a folder structure and exports images and attachments alongside the Markdown files with working relative paths. In a DIY pipeline none of this is automatic: hierarchy, asset downloads and link rewriting each have to be implemented.
Pandoc and open-source CLI exporters cost nothing to license, which makes them cheapest for a one-off export by someone who already has the skills. Once you account for engineering hours to handle hierarchy, attachments and link rewriting, and for maintaining that code, a Marketplace licence is usually cheaper for a single migration.
Build your own when the export has to run repeatedly and automatically, when you need custom front matter or transform rules, when the target is not standard Markdown, when you are extending existing tooling, or when installing a Marketplace app is not possible in your environment. For a one-off migration with a fixed deadline, a dedicated exporter is usually faster.
Nar is the founder of Narva Software and a former software developer with real-world experience using Atlassian tools. After facing the limitations of Jira and Confluence himself, he set out to build simple, effective apps that make teamwork easier. Today, his focus is on creating practical solutions that help teams work faster and smarter — and are trusted by companies around the world.
