If you’re a developer or technical writer who lives in Markdown, Confluence can feel like a wall. You write clean Markdown, paste it into Confluence, and something unexpected happens. Sometimes it works beautifully. Sometimes your tables collapse. Sometimes your code blocks lose their language tag.

This guide covers Confluence’s Markdown story honestly — what converts cleanly, what doesn’t survive the jump, and practical workarounds for the gaps.

The Core Thing to Understand

Confluence is not a Markdown-native tool. Its internal storage format is XHTML-based (called “Confluence Storage Format”). When you paste Markdown, Confluence converts it into its own internal format — there is no persistent Markdown mode where your content stays as .md.

This matters because:

  • After pasting, you edit content using Confluence’s rich text editor
  • The original Markdown source is gone; Confluence converted it
  • Round-tripping back to Markdown (for example, to put content back in Git) loses fidelity

If you need Markdown as a persistent, two-way format, you’ll need a marketplace app or a different workflow (more on that below).

Confluence Cloud vs. Server / Data Center

Markdown support varies significantly between deployment types:

Feature Confluence Cloud Server / Data Center
Paste Markdown in editor ✅ auto-converts ⚠️ limited
/markdown slash command ✅ ❌
Markdown file import ✅ ✅
Markdown macro (native) ❌ ❌
Markdown macro (marketplace) ✅ ✅

This guide focuses primarily on Confluence Cloud, which has the most Markdown support.

What You Can Paste in Confluence Cloud

In the Confluence Cloud editor, when you paste Markdown text, Confluence attempts to auto-convert it. Here’s what converts reliably:

What converts cleanly

  • Headings (# H1, ## H2, ### H3) → Confluence headings ✅
  • Bold and italic (**bold**, *italic*) → Confluence formatting ✅
  • Unordered lists (- item) → Confluence bullet lists ✅
  • Ordered lists (1. item) → Confluence numbered lists ✅
  • Inline code (`code`) → Confluence inline code ✅
  • Fenced code blocks (‘‘‘) → Confluence code macro ✅ (language tag usually preserved)
  • Basic links ([text](url)) → Confluence hyperlinks ✅
  • Images from URLs (![alt](url)) → embedded image ✅
  • Simple tables (pipe syntax) → Confluence table ✅
  • Horizontal rules (---) → Confluence divider ✅

What does NOT convert well

  • Footnotes ([^1]: reference) → rendered as plain text ❌
  • Definition lists → rendered as plain text ❌
  • Task lists (- [x] done) → inconsistent; sometimes works, sometimes breaks ⚠️
  • Table cell alignment (:---:, ---:) → usually ignored ❌
  • HTML mixed with Markdown → HTML is stripped or escaped ❌
  • YAML frontmatter (--- header blocks) → treated as horizontal rules or breaks the conversion ❌
  • Complex nested lists (3+ levels deep) → structure may collapse ⚠️
  • Strikethrough (~~text~~) → usually works but inconsistent across editor versions ⚠️

The /markdown Slash Command

In Confluence Cloud, type /markdown anywhere in a page body to open a Markdown entry panel. Paste your Markdown into the panel, then click Insert — Confluence converts and inserts it.

This is the most reliable way to paste Markdown in Confluence Cloud. It gives you a dedicated conversion step with a clear preview before inserting.

How to use it:

  1. Click in the page body where you want to insert content
  2. Type /markdown
  3. Select Markdown from the macro picker dropdown
  4. Paste your Markdown into the panel
  5. Click Insert

The same conversion limitations apply — footnotes, complex tables, and inline HTML will still lose fidelity — but the /markdown command is more predictable than a raw paste.

Importing Markdown Files

Confluence Cloud can import Markdown files directly, which is useful for migrating an existing Markdown documentation set. Check your Space settings for import options (the exact path varies by Confluence version, but look under Space Settings → Manage Space or the Create menu for an import option).

Imported pages become regular Confluence pages after import — there’s no ongoing Markdown sync. For bulk migration (importing a full MkDocs or Docusaurus docs tree), you’ll need a scripted approach using the Confluence REST API or a third-party migration tool.

Code Blocks: The Special Case

Code blocks generally convert well, but with a few gotchas:

Language identifiers — Confluence supports a specific set of language names in its code macro. If you paste a code block with an unrecognised language tag, it falls back to plain text formatting. Reliably supported: java, javascript, python, bash, sql, xml, json, html, css, yaml, ruby, go.

Long code blocks — very long blocks (hundreds of lines) can cause the editor to struggle. Break them up if you hit rendering issues.

Inline code — converts cleanly in virtually all cases.

Tables in Confluence

Basic pipe-syntax Markdown tables convert to Confluence tables, but with limitations:

  • ✅ Basic multi-column tables with a header row
  • ❌ Merged cells (colspan / rowspan) — not supported in Markdown anyway, but no workaround in the paste
  • ❌ Column alignment markers (:---:) — usually ignored
  • ❌ Complex cell content (code blocks inside table cells)

For merged cells or complex alignment, you’ll need to use Confluence’s native table editor after pasting.

Workarounds for Common Pain Points

Problem: You write docs in Markdown but need to publish to Confluence

Option 1: Convert to HTML first, then paste HTML

Confluence’s rich text editor handles pasted HTML much better than pasted Markdown for complex content. Use our Markdown to HTML converter to convert your Markdown, then paste the resulting HTML into Confluence.

Most HTML structure (headings, lists, tables, code blocks, links) survives the paste well.

Option 2: Use a Markdown sync marketplace app

Apps like Markdown for Confluence allow you to maintain pages as Markdown files in a Git repository and sync them to Confluence automatically. The page source stays as Markdown; the app handles conversion on publish. This is the closest thing to a true persistent Markdown mode in Confluence.

Option 3: Embrace Confluence’s native editor

For teams fully committed to Confluence, forcing Markdown into the workflow often creates more friction than it saves. Confluence’s editor is capable — it just isn’t Markdown. Writing natively can be more efficient than maintaining a conversion workflow.

Problem: YAML frontmatter breaks the page

Strip frontmatter before pasting. Confluence has no concept of frontmatter and renders the --- delimiters as horizontal rules, with the YAML content appearing as plain text.

Problem: Code blocks lose syntax highlighting

Use the /markdown slash command instead of a direct paste — it’s more reliable for preserving code block language tags. If a specific language doesn’t highlight, check Confluence’s supported language list and substitute the closest match.

Problem: You need to get Confluence content back into Markdown

Confluence doesn’t export to Markdown natively. Options:

  1. Export as HTML — use the page’s export function to get HTML, then run it through our HTML to Markdown converter
  2. Confluence REST API — fetch the Storage Format (XHTML) via API, then convert from XHTML to Markdown with a script
  3. Marketplace app — some two-way sync apps handle export back to Markdown

Confluence Data Center and Server

On Confluence Data Center or Server (self-hosted), Markdown support is more limited. There is no native /markdown slash command, and auto-paste conversion is inconsistent depending on the version and which editor your instance uses.

Your best options on Server/DC:

  • Markdown Macro app (Atlassian Marketplace) — renders Markdown in a macro block on the page; the source stays as Markdown and the app renders it on page load
  • HTML paste method — convert Markdown to HTML first (using our Markdown to HTML tool), then paste the HTML
  • REST API import — script a migration using the Confluence Server REST API

When Confluence Markdown Just Isn’t Worth It

For some teams, the better answer is to stop fighting the impedance mismatch and choose one format per context:

  • Living documentation the whole team edits: Use Confluence natively. Don’t fight the tool.
  • Technical reference docs maintained by developers: Consider a docs-as-code approach (MkDocs, Docusaurus) and link to those sites from Confluence, rather than trying to sync.
  • One-time migration of existing Markdown content: Do the import once, accept the conversion loss, and maintain in Confluence from that point.

Quick Reference

Task Best approach
Paste Markdown into Cloud Use /markdown slash command
Import a Markdown file Use Space settings import option
Keep Markdown as the source of truth Use a marketplace sync app
Convert Markdown to paste-ready HTML Markdown to HTML tool
Extract Confluence content to Markdown Export HTML → HTML to Markdown tool
Complex tables after paste Edit with Confluence’s native table editor