Confluence and Markdown: how to import, convert, and sync

Atlassian Confluence is a wiki built around its own editor, not Markdown. The phrase "Markdown for Confluence" usually means one of three different things: paste-convert (a one-time conversion), the Markdown macro (renders Markdown inside a Confluence page), or bulk import (a project full of .md files into a Confluence space). This guide covers all three.

The honest answer first

Confluence and Markdown have an uncomfortable relationship. Confluence's editor is rich-text with its own internal format (ADF - Atlassian Document Format). Markdown isn't a first-class citizen - you can't type # Heading in the Confluence editor and have it render as a heading. You can paste Markdown that gets auto-converted, you can render Markdown inside a code-block macro, or you can use third-party apps and the REST API to round-trip.

Pick the path that matches what you're actually trying to do.

Method 1: Paste auto-conversion (Confluence Cloud)

The smoothest workflow as of 2026: paste Markdown directly into the Confluence editor and Confluence auto-converts the syntax to its rich-text equivalents.

What works in paste-conversion:

• Headings (#, ##, ### → H1, H2, H3)
• Bold, italic, strikethrough
• Bullet and numbered lists (including nested)
• Inline code and fenced code blocks (language hint becomes a code-block macro syntax setting)
• Links ([text](url))
• Tables (GFM tables, mostly)
• Block quotes

What doesn't paste-convert cleanly:

• Images via Markdown ![alt](url) - you'll need to upload images separately
• Footnotes
• Definition lists
• Math (LaTeX)
• Anything HTML-flavored

Note: this paste-conversion is a Confluence Cloud feature; behavior in Confluence Data Center / Server depends on version.

Method 2: The Markdown macro (Server / DC / Cloud)

Inside the Confluence editor, type /markdown (or /code) and pick the Markdown macro. You get a code-block where you type Markdown source; Confluence renders the formatted output.

Use when:

• You're editing a Confluence page but want one section sourced from Markdown
• Your Markdown contains things paste-conversion doesn't handle (math, footnotes)
• You're embedding Markdown that's auto-generated from another system

Drawback: the rendered output lives inside a single block. You can't intersperse rendered Markdown with other Confluence content the way you can with native rich-text.

Method 3: Bulk import (.md → Confluence pages)

For migrating a folder of .md files (a project's docs, a team's runbooks, an old GitBook export) into Confluence:

1. Use a converter that emits Confluence's storage format - md2cf (a CLI), mark (newer, supports macros), or the Mermaid/PlantUML-enabled forks.
2. Or convert to HTML first with Markdown to HTML, then use Confluence's "Import HTML" feature in Space Settings.

Option two is usually more reliable for documents that mostly need to render right; option one preserves Markdown structure better when you'll edit further in Confluence.

For a single page, the fastest workflow:

1. Paste your Markdown into Markdown Tidy's editor
2. Click Tidy (strips AI artifacts, repairs broken tables)
3. Export → HTML
4. In Confluence, create a new page → … menu → Import → paste the HTML

The Markdown Tidy step matters because Confluence's import is strict. A broken table or stray Unicode character that GitHub silently absorbs will fail Confluence's import.

Confluence → Markdown (the reverse)

Going Confluence → Markdown is rarer but happens when teams migrate out of Confluence to GitHub-based docs or static-site generators.

Three options:

• confluence-to-markdown (npm package) - exports pages via the Confluence REST API and converts
• Pandoc - pandoc input.html -t gfm if you've already exported the page as HTML
• Manual copy-paste - surprisingly viable for small projects; modern browsers handle the formatted-text → Markdown conversion via tools like the Markdown Web Clipper extensions

Confluence-specific gotchas

A few things that bite people:

• Table cells with line breaks. Confluence accepts <br> inside cells; Markdown tables don't natively. Use Confluence-aware export tools or accept some cells will collapse to one line.
• Code blocks with language hints. Confluence's code-block macro has its own language list; some Markdown language names (e.g., tsx) don't map directly.
• Page hierarchy. Bulk imports flatten the page tree. You usually have to drag pages into the right parent after import.
• Attachments. Image references in Markdown (![](path)) become broken links unless you upload the images to the page first.

What to use Confluence's Markdown story for

The honest framing: Confluence's Markdown support is good enough for occasional pastes and one-off imports. It's not a replacement for "write your team docs in Markdown, sync to Confluence." Teams that want both usually:

• Keep authoritative source in Markdown in a Git repo
• Use a static-site generator (MkDocs, Docusaurus) for the engineering audience
• Mirror the high-traffic pages to Confluence via a sync tool, accepting some staleness

If you're at the start of this decision, see MkDocs: getting started for the Git-based docs route.

Related

• Markdown to HTML - for the "import HTML" path into Confluence
• The AI Markdown cleanup checklist - Confluence is unforgiving with broken syntax
• How to repair broken Markdown tables - Confluence's table importer is strict