[{"data":1,"prerenderedAt":82},["Reactive",2],{"blog-post-markdown-in-confluence-what-works":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":52,"related":55},"markdown-in-confluence-what-works","Markdown in Confluence: What Actually Works, What Doesn't, and Workarounds","A practical guide to using Markdown in Confluence Cloud and Data Center — what converts cleanly, what breaks, and how to work around the limitations.","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…","2026-05-15","platform-guides","Matt Rathbone","confluence markdown, confluence markdown support, confluence markdown editor, atlassian markdown, confluence paste markdown, confluence import markdown",7,"\u003Cp>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.\u003C/p>\n\u003Cp>This guide covers Confluence's Markdown story honestly — what converts cleanly, what doesn't survive the jump, and practical workarounds for the gaps.\u003C/p>\n\u003Ch2 id=\"the-core-thing-to-understand\">The Core Thing to Understand\u003C/h2>\n\u003Cp>\u003Cstrong>Confluence is not a Markdown-native tool.\u003C/strong> 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 \u003Ccode>.md\u003C/code>.\u003C/p>\n\u003Cp>This matters because:\u003C/p>\n\u003Cul>\n\u003Cli>After pasting, you edit content using Confluence's rich text editor\u003C/li>\n\u003Cli>The original Markdown source is gone; Confluence converted it\u003C/li>\n\u003Cli>Round-tripping back to Markdown (for example, to put content back in Git) loses fidelity\u003C/li>\n\u003C/ul>\n\u003Cp>If you need Markdown as a persistent, two-way format, you'll need a marketplace app or a different workflow (more on that below).\u003C/p>\n\u003Ch2 id=\"confluence-cloud-vs-server--data-center\">Confluence Cloud vs. Server / Data Center\u003C/h2>\n\u003Cp>Markdown support varies significantly between deployment types:\u003C/p>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Feature\u003C/th>\n\u003Cth align=\"center\">Confluence Cloud\u003C/th>\n\u003Cth align=\"center\">Server / Data Center\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Paste Markdown in editor\u003C/td>\n\u003Ctd align=\"center\">✅ auto-converts\u003C/td>\n\u003Ctd align=\"center\">⚠️ limited\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>/markdown\u003C/code> slash command\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Markdown file import\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Markdown macro (native)\u003C/td>\n\u003Ctd align=\"center\">❌\u003C/td>\n\u003Ctd align=\"center\">❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Markdown macro (marketplace)\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Cp>This guide focuses primarily on \u003Cstrong>Confluence Cloud\u003C/strong>, which has the most Markdown support.\u003C/p>\n\u003Ch2 id=\"what-you-can-paste-in-confluence-cloud\">What You Can Paste in Confluence Cloud\u003C/h2>\n\u003Cp>In the Confluence Cloud editor, when you paste Markdown text, Confluence attempts to auto-convert it. Here's what converts reliably:\u003C/p>\n\u003Ch3 id=\"what-converts-cleanly\">What converts cleanly\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Headings\u003C/strong> (\u003Ccode># H1\u003C/code>, \u003Ccode>## H2\u003C/code>, \u003Ccode>### H3\u003C/code>) → Confluence headings ✅\u003C/li>\n\u003Cli>\u003Cstrong>Bold and italic\u003C/strong> (\u003Ccode>**bold**\u003C/code>, \u003Ccode>*italic*\u003C/code>) → Confluence formatting ✅\u003C/li>\n\u003Cli>\u003Cstrong>Unordered lists\u003C/strong> (\u003Ccode>- item\u003C/code>) → Confluence bullet lists ✅\u003C/li>\n\u003Cli>\u003Cstrong>Ordered lists\u003C/strong> (\u003Ccode>1. item\u003C/code>) → Confluence numbered lists ✅\u003C/li>\n\u003Cli>\u003Cstrong>Inline code\u003C/strong> (\u003Ccode>`code`\u003C/code>) → Confluence inline code ✅\u003C/li>\n\u003Cli>\u003Cstrong>Fenced code blocks\u003C/strong> (‘‘‘) → Confluence code macro ✅ (language tag usually preserved)\u003C/li>\n\u003Cli>\u003Cstrong>Basic links\u003C/strong> (\u003Ccode>[text](url)\u003C/code>) → Confluence hyperlinks ✅\u003C/li>\n\u003Cli>\u003Cstrong>Images from URLs\u003C/strong> (\u003Ccode>![alt](url)\u003C/code>) → embedded image ✅\u003C/li>\n\u003Cli>\u003Cstrong>Simple tables\u003C/strong> (pipe syntax) → Confluence table ✅\u003C/li>\n\u003Cli>\u003Cstrong>Horizontal rules\u003C/strong> (\u003Ccode>---\u003C/code>) → Confluence divider ✅\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"what-does-not-convert-well\">What does NOT convert well\u003C/h3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Footnotes\u003C/strong> (\u003Ccode>[^1]: reference\u003C/code>) → rendered as plain text ❌\u003C/li>\n\u003Cli>\u003Cstrong>Definition lists\u003C/strong> → rendered as plain text ❌\u003C/li>\n\u003Cli>\u003Cstrong>Task lists\u003C/strong> (\u003Ccode>- [x] done\u003C/code>) → inconsistent; sometimes works, sometimes breaks ⚠️\u003C/li>\n\u003Cli>\u003Cstrong>Table cell alignment\u003C/strong> (\u003Ccode>:---:\u003C/code>, \u003Ccode>---:\u003C/code>) → usually ignored ❌\u003C/li>\n\u003Cli>\u003Cstrong>HTML mixed with Markdown\u003C/strong> → HTML is stripped or escaped ❌\u003C/li>\n\u003Cli>\u003Cstrong>YAML frontmatter\u003C/strong> (\u003Ccode>---\u003C/code> header blocks) → treated as horizontal rules or breaks the conversion ❌\u003C/li>\n\u003Cli>\u003Cstrong>Complex nested lists\u003C/strong> (3+ levels deep) → structure may collapse ⚠️\u003C/li>\n\u003Cli>\u003Cstrong>Strikethrough\u003C/strong> (\u003Ccode>~~text~~\u003C/code>) → usually works but inconsistent across editor versions ⚠️\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"the-markdown-slash-command\">The \u003Ccode>/markdown\u003C/code> Slash Command\u003C/h2>\n\u003Cp>In Confluence Cloud, type \u003Ccode>/markdown\u003C/code> anywhere in a page body to open a Markdown entry panel. Paste your Markdown into the panel, then click \u003Cstrong>Insert\u003C/strong> — Confluence converts and inserts it.\u003C/p>\n\u003Cp>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.\u003C/p>\n\u003Cp>\u003Cstrong>How to use it:\u003C/strong>\u003C/p>\n\u003Col>\n\u003Cli>Click in the page body where you want to insert content\u003C/li>\n\u003Cli>Type \u003Ccode>/markdown\u003C/code>\u003C/li>\n\u003Cli>Select \u003Cstrong>Markdown\u003C/strong> from the macro picker dropdown\u003C/li>\n\u003Cli>Paste your Markdown into the panel\u003C/li>\n\u003Cli>Click \u003Cstrong>Insert\u003C/strong>\u003C/li>\n\u003C/ol>\n\u003Cp>The same conversion limitations apply — footnotes, complex tables, and inline HTML will still lose fidelity — but the \u003Ccode>/markdown\u003C/code> command is more predictable than a raw paste.\u003C/p>\n\u003Ch2 id=\"importing-markdown-files\">Importing Markdown Files\u003C/h2>\n\u003Cp>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 \u003Cstrong>Space Settings → Manage Space\u003C/strong> or the \u003Cstrong>Create\u003C/strong> menu for an import option).\u003C/p>\n\u003Cp>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.\u003C/p>\n\u003Ch2 id=\"code-blocks-the-special-case\">Code Blocks: The Special Case\u003C/h2>\n\u003Cp>Code blocks generally convert well, but with a few gotchas:\u003C/p>\n\u003Cp>\u003Cstrong>Language identifiers\u003C/strong> — 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: \u003Ccode>java\u003C/code>, \u003Ccode>javascript\u003C/code>, \u003Ccode>python\u003C/code>, \u003Ccode>bash\u003C/code>, \u003Ccode>sql\u003C/code>, \u003Ccode>xml\u003C/code>, \u003Ccode>json\u003C/code>, \u003Ccode>html\u003C/code>, \u003Ccode>css\u003C/code>, \u003Ccode>yaml\u003C/code>, \u003Ccode>ruby\u003C/code>, \u003Ccode>go\u003C/code>.\u003C/p>\n\u003Cp>\u003Cstrong>Long code blocks\u003C/strong> — very long blocks (hundreds of lines) can cause the editor to struggle. Break them up if you hit rendering issues.\u003C/p>\n\u003Cp>\u003Cstrong>Inline code\u003C/strong> — converts cleanly in virtually all cases.\u003C/p>\n\u003Ch2 id=\"tables-in-confluence\">Tables in Confluence\u003C/h2>\n\u003Cp>Basic pipe-syntax Markdown tables convert to Confluence tables, but with limitations:\u003C/p>\n\u003Cul>\n\u003Cli>✅ Basic multi-column tables with a header row\u003C/li>\n\u003Cli>❌ Merged cells (colspan / rowspan) — not supported in Markdown anyway, but no workaround in the paste\u003C/li>\n\u003Cli>❌ Column alignment markers (\u003Ccode>:---:\u003C/code>) — usually ignored\u003C/li>\n\u003Cli>❌ Complex cell content (code blocks inside table cells)\u003C/li>\n\u003C/ul>\n\u003Cp>For merged cells or complex alignment, you'll need to use Confluence's native table editor after pasting.\u003C/p>\n\u003Ch2 id=\"workarounds-for-common-pain-points\">Workarounds for Common Pain Points\u003C/h2>\n\u003Ch3 id=\"problem-you-write-docs-in-markdown-but-need-to-publish-to-confluence\">Problem: You write docs in Markdown but need to publish to Confluence\u003C/h3>\n\u003Cp>\u003Cstrong>Option 1: Convert to HTML first, then paste HTML\u003C/strong>\u003C/p>\n\u003Cp>Confluence's rich text editor handles pasted HTML much better than pasted Markdown for complex content. Use our \u003Ca href=\"/tools/markdown-to-html\">Markdown to HTML converter\u003C/a> to convert your Markdown, then paste the resulting HTML into Confluence.\u003C/p>\n\u003Cp>Most HTML structure (headings, lists, tables, code blocks, links) survives the paste well.\u003C/p>\n\u003Cp>\u003Cstrong>Option 2: Use a Markdown sync marketplace app\u003C/strong>\u003C/p>\n\u003Cp>Apps like \u003Cstrong>Markdown for Confluence\u003C/strong> 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.\u003C/p>\n\u003Cp>\u003Cstrong>Option 3: Embrace Confluence's native editor\u003C/strong>\u003C/p>\n\u003Cp>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.\u003C/p>\n\u003Ch3 id=\"problem-yaml-frontmatter-breaks-the-page\">Problem: YAML frontmatter breaks the page\u003C/h3>\n\u003Cp>Strip frontmatter before pasting. Confluence has no concept of frontmatter and renders the \u003Ccode>---\u003C/code> delimiters as horizontal rules, with the YAML content appearing as plain text.\u003C/p>\n\u003Ch3 id=\"problem-code-blocks-lose-syntax-highlighting\">Problem: Code blocks lose syntax highlighting\u003C/h3>\n\u003Cp>Use the \u003Ccode>/markdown\u003C/code> 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.\u003C/p>\n\u003Ch3 id=\"problem-you-need-to-get-confluence-content-back-into-markdown\">Problem: You need to get Confluence content back into Markdown\u003C/h3>\n\u003Cp>Confluence doesn't export to Markdown natively. Options:\u003C/p>\n\u003Col>\n\u003Cli>\u003Cstrong>Export as HTML\u003C/strong> — use the page's export function to get HTML, then run it through our \u003Ca href=\"/tools/html-to-markdown\">HTML to Markdown converter\u003C/a>\u003C/li>\n\u003Cli>\u003Cstrong>Confluence REST API\u003C/strong> — fetch the Storage Format (XHTML) via API, then convert from XHTML to Markdown with a script\u003C/li>\n\u003Cli>\u003Cstrong>Marketplace app\u003C/strong> — some two-way sync apps handle export back to Markdown\u003C/li>\n\u003C/ol>\n\u003Ch2 id=\"confluence-data-center-and-server\">Confluence Data Center and Server\u003C/h2>\n\u003Cp>On Confluence Data Center or Server (self-hosted), Markdown support is more limited. There is no native \u003Ccode>/markdown\u003C/code> slash command, and auto-paste conversion is inconsistent depending on the version and which editor your instance uses.\u003C/p>\n\u003Cp>Your best options on Server/DC:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Markdown Macro app\u003C/strong> (Atlassian Marketplace) — renders Markdown in a macro block on the page; the source stays as Markdown and the app renders it on page load\u003C/li>\n\u003Cli>\u003Cstrong>HTML paste method\u003C/strong> — convert Markdown to HTML first (using our \u003Ca href=\"/tools/markdown-to-html\">Markdown to HTML tool\u003C/a>), then paste the HTML\u003C/li>\n\u003Cli>\u003Cstrong>REST API import\u003C/strong> — script a migration using the Confluence Server REST API\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"when-confluence-markdown-just-isnt-worth-it\">When Confluence Markdown Just Isn't Worth It\u003C/h2>\n\u003Cp>For some teams, the better answer is to stop fighting the impedance mismatch and choose one format per context:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Living documentation the whole team edits\u003C/strong>: Use Confluence natively. Don't fight the tool.\u003C/li>\n\u003Cli>\u003Cstrong>Technical reference docs maintained by developers\u003C/strong>: Consider a docs-as-code approach (MkDocs, Docusaurus) and link to those sites from Confluence, rather than trying to sync.\u003C/li>\n\u003Cli>\u003Cstrong>One-time migration of existing Markdown content\u003C/strong>: Do the import once, accept the conversion loss, and maintain in Confluence from that point.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"quick-reference\">Quick Reference\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Task\u003C/th>\n\u003Cth>Best approach\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Paste Markdown into Cloud\u003C/td>\n\u003Ctd>Use \u003Ccode>/markdown\u003C/code> slash command\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Import a Markdown file\u003C/td>\n\u003Ctd>Use Space settings import option\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Keep Markdown as the source of truth\u003C/td>\n\u003Ctd>Use a marketplace sync app\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Convert Markdown to paste-ready HTML\u003C/td>\n\u003Ctd>\u003Ca href=\"/tools/markdown-to-html\">Markdown to HTML tool\u003C/a>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Extract Confluence content to Markdown\u003C/td>\n\u003Ctd>Export HTML → \u003Ca href=\"/tools/html-to-markdown\">HTML to Markdown tool\u003C/a>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Complex tables after paste\u003C/td>\n\u003Ctd>Edit with Confluence's native table editor\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"related-reading\">Related Reading\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown Across Platforms: What Works in GitHub, Notion, Obsidian, and Confluence\u003C/a> — feature matrix across tools\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/mkdocs-vs-docusaurus-vs-gitbook\">MkDocs vs Docusaurus vs GitBook: Which Documentation Tool Should You Use?\u003C/a> — if you're evaluating docs-as-code alternatives to Confluence\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-tables-advanced-features-and-styling-guide\">Markdown tables: advanced features and styling\u003C/a> — make tables as clean as possible before pasting\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-for-github-complete-workflow-guide\">Markdown for GitHub: the complete workflow guide\u003C/a> — how Markdown behaves on a platform that does it right\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31,34,37,40,43,46,49],{"id":16,"text":17,"level":18},"the-core-thing-to-understand","The Core Thing to Understand",2,{"id":20,"text":21,"level":18},"confluence-cloud-vs-server--data-center","Confluence Cloud vs. Server / Data Center",{"id":23,"text":24,"level":18},"what-you-can-paste-in-confluence-cloud","What You Can Paste in Confluence Cloud",{"id":26,"text":27,"level":18},"the-markdown-slash-command","The /markdown Slash Command",{"id":29,"text":30,"level":18},"importing-markdown-files","Importing Markdown Files",{"id":32,"text":33,"level":18},"code-blocks-the-special-case","Code Blocks: The Special Case",{"id":35,"text":36,"level":18},"tables-in-confluence","Tables in Confluence",{"id":38,"text":39,"level":18},"workarounds-for-common-pain-points","Workarounds for Common Pain Points",{"id":41,"text":42,"level":18},"confluence-data-center-and-server","Confluence Data Center and Server",{"id":44,"text":45,"level":18},"when-confluence-markdown-just-isnt-worth-it","When Confluence Markdown Just Isn't Worth It",{"id":47,"text":48,"level":18},"quick-reference","Quick Reference",{"id":50,"text":51,"level":18},"related-reading","Related Reading",[53,54],"markdown-to-html","html-to-markdown",[56,65,75],{"slug":57,"title":58,"description":59,"excerpt":60,"date":61,"category":62,"author":10,"keywords":63,"readingMinutes":64},"markdown-for-notion-what-actually-works","Markdown for Notion: What Actually Works and What Doesn't","A practical guide to importing, writing, and exporting Markdown in Notion — what converts cleanly, what breaks, and reliable workarounds for each case.","Notion markets itself as Markdown-friendly, and for basic formatting it mostly is. But spend enough time moving documents between Notion and the rest of your toolchain and you'll hit the edge…","2026-06-26","workflows","markdown notion, notion markdown import, notion markdown export, notion markdown support, paste markdown notion, notion markdown rendering",6,{"slug":66,"title":67,"description":68,"excerpt":69,"date":70,"category":71,"author":72,"keywords":73,"readingMinutes":74},"markdown-platform-compatibility-guide","Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence","A practical Markdown compatibility guide for GitHub, Notion, Obsidian, Confluence, VS Code, and more. Includes a feature comparison table and platform-specific tips.","Markdown is everywhere — but Markdown is not the same everywhere. If you've ever carefully written a document with footnotes, custom HTML, or a nice callout block, only to paste it into a…","2026-04-30","Guide","Matthew Rathbone","markdown compatibility, markdown platforms, github markdown, notion markdown, obsidian markdown, confluence markdown, markdown comparison, markdown features by platform",8,{"slug":76,"title":77,"description":78,"excerpt":79,"date":80,"category":62,"author":10,"keywords":81,"readingMinutes":64},"markdown-to-slack-formatting-guide","Markdown to Slack Formatting: What Actually Works (mrkdwn Explained)","Slack doesn't render standard Markdown — it uses its own mrkdwn format. Here's the full syntax mapping, what breaks (tables, headings, images), and how to convert reliably.","If you've ever pasted a chunk of Markdown into Slack expecting headings and tables to show up nicely, you've already learned the hard way: Slack doesn't speak Markdown. It has its own lookalike…","2026-07-10","markdown to slack, slack mrkdwn, slack markdown formatting, slack message formatting, slack markdown syntax, convert markdown to slack, slack markdown tables",1792184946835]