[{"data":1,"prerenderedAt":64},["Reactive",2],{"blog-post-mermaid-diagrams-in-slack-jira-confluence-word-email":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":34,"related":37},"mermaid-diagrams-in-slack-jira-confluence-word-email","Mermaid Diagrams in Slack, Jira, Confluence, Word, and Email: The Static Export Workaround","Mermaid renders live on GitHub, GitLab, and Obsidian — and nowhere else most teams actually work. Here's how to get a Mermaid diagram into Slack, Jira, Confluence, Word, and email as a static image instead.","Our complete guide to diagrams and flowcharts in Markdown covers Mermaid syntax in depth — flowcharts, sequence diagrams, ER diagrams, the works. What it doesn't dwell on is a problem that shows…","2026-09-18","Tutorial","Matthew Rathbone","mermaid diagrams slack, mermaid confluence, mermaid jira, mermaid word document, mermaid email, export mermaid to png, export mermaid to svg",6,"\u003Cp>Our \u003Ca href=\"/blog/markdown-diagrams-flowcharts-complete-guide\">complete guide to diagrams and flowcharts in Markdown\u003C/a> covers Mermaid syntax in depth — flowcharts, sequence diagrams, ER diagrams, the works. What it doesn't dwell on is a problem that shows up the moment you try to actually \u003Cem>use\u003C/em> one of those diagrams somewhere other than a GitHub README: most of the places you'd want to paste a diagram don't render Mermaid at all.\u003C/p>\n\u003Cp>That's not a syntax problem, and no amount of getting the Mermaid code "right" fixes it. It's a rendering-engine problem — Slack, Jira, Confluence, Word, and email clients simply have no Mermaid interpreter anywhere in their pipeline. The fix isn't better Markdown. It's exporting the diagram as a plain image before it leaves your Mermaid source.\u003C/p>\n\u003Ch2 id=\"why-this-keeps-catching-people-off-guard\">Why this keeps catching people off guard\u003C/h2>\n\u003Cp>Mermaid fences (\u003Ccode>```mermaid\u003C/code>) look exactly like any other fenced code block, and on the platforms that *do* support it — GitHub, GitLab, Obsidian — that fence quietly becomes a rendered diagram with zero extra steps. It's easy to assume the same thing will happen everywhere else, because nothing about the syntax signals "this only works in three places." It doesn't error. It doesn't warn you. It just shows up as a gray code block of \u003Ccode>flowchart TD\u003C/code> and arrow syntax, exactly as literally typed, and the reader has to reconstruct the diagram in their head from the text.\u003C/p>\n\u003Cp>We ran into this from the other direction first, while documenting our own conversion tools: our \u003Ca href=\"/blog/markdown-for-notion-what-actually-works\">Notion conversion guide\u003C/a>, \u003Ca href=\"/blog/markdown-to-word-docx-what-converts-cleanly\">Word/DOCX guide\u003C/a>, and \u003Ca href=\"/blog/markdown-to-email-html-newsletters-and-esps\">Email HTML guide\u003C/a> all independently document the same fallback: a Mermaid fence gets carried through as an inert code block, with a warning, because there's no other honest thing a converter can do with syntax the destination format can't execute. Slack and Jira have the identical gap for a different reason — there's no conversion step at all, since you're typically composing directly in Slack's message box or Jira's editor, and neither one has ever implemented a Mermaid renderer.\u003C/p>\n\u003Ch2 id=\"the-fix-render-it-once-export-a-static-image\">The fix: render it once, export a static image\u003C/h2>\n\u003Cp>The workaround is the same regardless of destination: render the Mermaid source into an actual image — SVG or PNG — outside the target platform, then paste or attach \u003Cem>that\u003C/em> instead of the Mermaid code. Once it's a PNG or SVG, every platform on this list handles it exactly the same way it handles any other image, because at that point it \u003Cem>is\u003C/em> just an image.\u003C/p>\n\u003Cp>You can do this with the Mermaid CLI (\u003Ccode>mmdc\u003C/code>) if you're comfortable with a Node toolchain and want it scripted into a build step — our diagrams guide covers that command-line path. For a one-off diagram, or if you don't want to install anything, our \u003Ca href=\"/tools/markdown-mermaid\">Markdown Mermaid Diagram Preview\u003C/a> tool does the same rendering step in the browser: paste your Mermaid source, see it render live (so you catch syntax errors before you export, not after you've already pasted a broken image somewhere), then use \u003Cstrong>Download SVG\u003C/strong> or \u003Cstrong>Download PNG\u003C/strong> to get a static file with nothing installed.\u003C/p>\n\u003Ch2 id=\"platform-by-platform\">Platform by platform\u003C/h2>\n\u003Ch3 id=\"slack\">Slack\u003C/h3>\n\u003Cp>Slack has no diagram rendering of any kind — not in the message composer, not via the API, not through Block Kit. A Mermaid fence pasted into a Slack message just shows up as plain text with backticks, per our \u003Ca href=\"/blog/markdown-to-slack-formatting-guide\">Markdown to Slack guide\u003C/a>, which documents the same "no native rendering, period" behavior for tables and several other Markdown constructs. Export a PNG and drag it into the message instead — Slack handles inline image previews natively, and unlike a wall of Mermaid syntax, a teammate can actually read it without decoding the diagram in their head.\u003C/p>\n\u003Ch3 id=\"jira\">Jira\u003C/h3>\n\u003Cp>Neither Jira's classic wiki markup nor its modern Cloud rich-text editor has a Mermaid renderer, as our \u003Ca href=\"/blog/markdown-to-jira-wiki-markup-guide\">Markdown to Jira guide\u003C/a> notes for wiki-markup conversion generally. Some teams install a marketplace add-on (several exist specifically for embedding live Mermaid/PlantUML diagrams in Jira issues), which is worth it if diagrams are a constant part of your workflow — but for an occasional diagram in a ticket, attaching an exported PNG is faster than getting a marketplace app approved and installed.\u003C/p>\n\u003Ch3 id=\"confluence\">Confluence\u003C/h3>\n\u003Cp>Confluence's \u003Ccode>/markdown\u003C/code> paste panel strips or escapes raw HTML and doesn't execute embedded scripts, so a Mermaid fence pasted in comes through as a plain code-formatted block, consistent with what our \u003Ca href=\"/blog/markdown-in-confluence-what-works\">Confluence compatibility guide\u003C/a> documents for other unsupported constructs. As with Jira, marketplace add-ons exist for live Mermaid rendering in Confluence pages if you need diagrams to stay editable in place; for a document going out once, attach the exported image and move on.\u003C/p>\n\u003Ch3 id=\"word-docx\">Word (.docx)\u003C/h3>\n\u003Cp>A \u003Ccode>.docx\u003C/code> file has no code-execution layer at all — there's no such thing as a "live" Mermaid diagram inside a Word document, full stop. Our \u003Ca href=\"/blog/markdown-to-word-docx-what-converts-cleanly\">Markdown to Word guide\u003C/a> documents that our own \u003Ccode>markdown-to-docx\u003C/code> converter drops Mermaid fences to a plain monospace code block with a warning, for exactly this reason — there's nothing else a converter \u003Cem>could\u003C/em> do with it. Export the diagram as a PNG first, then either paste it directly into the document or use our \u003Ca href=\"/tools/markdown-image-formatter\">Markdown Image Formatter\u003C/a> if you want a sized/captioned version before it goes in.\u003C/p>\n\u003Ch3 id=\"email-newsletters-transactional-templates\">Email (newsletters, transactional templates)\u003C/h3>\n\u003Cp>Same root problem as Word, for the same reason: email clients render HTML, not JavaScript, and Mermaid needs JavaScript to do its layout work. Our \u003Ca href=\"/blog/markdown-to-email-html-newsletters-and-esps\">Markdown to Email HTML guide\u003C/a> documents the identical fallback — a Mermaid fence becomes a plain code block with a warning banner. For email specifically, export \u003Cstrong>PNG\u003C/strong>, not SVG: SVG support in email clients is inconsistent (particularly in Outlook's desktop Word-based rendering engine, already a recurring theme in that guide), while a PNG is universally safe.\u003C/p>\n\u003Ch2 id=\"svg-vs-png-which-to-export\">SVG vs. PNG: which to export\u003C/h2>\n\u003Cp>Reach for \u003Cstrong>SVG\u003C/strong> when the destination platform accepts vector images and you might need to resize or embed the diagram at multiple sizes — a wiki page, a MkDocs/Docusaurus site that doesn't render Mermaid live, a print-quality document. SVG stays crisp at any zoom level and is a much smaller file for simple diagrams.\u003C/p>\n\u003Cp>Reach for \u003Cstrong>PNG\u003C/strong> for everything else in the list above — Slack, Jira, Confluence attachments, Word, and especially email — where universal support matters more than infinite scalability, and where you can't be sure the destination will render an \u003Ccode><img>\u003C/code> pointing at an SVG correctly. Our tool exports PNG at 2x scale specifically so it still looks sharp on a high-DPI display without needing SVG's true vector scaling.\u003C/p>\n\u003Ch2 id=\"quick-reference\">Quick reference\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Destination\u003C/th>\n\u003Cth>Native Mermaid rendering?\u003C/th>\n\u003Cth>What to do instead\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>GitHub, GitLab, Obsidian\u003C/td>\n\u003Ctd>Yes, built in\u003C/td>\n\u003Ctd>Nothing — paste the fence directly\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Slack\u003C/td>\n\u003Ctd>No, none\u003C/td>\n\u003Ctd>Export PNG, attach/drag into message\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Jira\u003C/td>\n\u003Ctd>No (marketplace add-ons exist)\u003C/td>\n\u003Ctd>Export PNG, attach to issue\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Confluence\u003C/td>\n\u003Ctd>No (marketplace add-ons exist)\u003C/td>\n\u003Ctd>Export PNG, attach to page\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Word (.docx)\u003C/td>\n\u003Ctd>No, no execution layer at all\u003C/td>\n\u003Ctd>Export PNG, insert as image\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Email (ESP / HTML template)\u003C/td>\n\u003Ctd>No, no execution layer at all\u003C/td>\n\u003Ctd>Export PNG (not SVG), inline in template\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>MkDocs / Docusaurus\u003C/td>\n\u003Ctd>Needs a plugin, off by default\u003C/td>\n\u003Ctd>Export SVG for a self-hosted static asset, or enable the plugin\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-diagrams-flowcharts-complete-guide\">Markdown Diagrams and Flowcharts: Complete Guide\u003C/a> — full Mermaid/PlantUML syntax reference\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-to-slack-formatting-guide\">Markdown to Slack Formatting Guide\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-to-jira-wiki-markup-guide\">Markdown to Jira Wiki Markup Guide\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-in-confluence-what-works\">Markdown in Confluence: What Actually Works\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-to-word-docx-what-converts-cleanly\">Markdown to Word (DOCX): What Converts Cleanly\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-to-email-html-newsletters-and-esps\">Markdown to Email HTML: Newsletters and ESPs\u003C/a>\u003C/li>\n\u003Cli>Try it yourself: \u003Ca href=\"/tools/markdown-mermaid\">Markdown Mermaid Diagram Preview\u003C/a>\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31],{"id":16,"text":17,"level":18},"why-this-keeps-catching-people-off-guard","Why this keeps catching people off guard",2,{"id":20,"text":21,"level":18},"the-fix-render-it-once-export-a-static-image","The fix: render it once, export a static image",{"id":23,"text":24,"level":18},"platform-by-platform","Platform by platform",{"id":26,"text":27,"level":18},"svg-vs-png-which-to-export","SVG vs. PNG: which to export",{"id":29,"text":30,"level":18},"quick-reference","Quick reference",{"id":32,"text":33,"level":18},"related-reading","Related reading",[35,36],"markdown-mermaid","markdown-image-formatter",[38,46,56],{"slug":39,"title":40,"description":41,"excerpt":42,"date":43,"category":9,"author":10,"keywords":44,"readingMinutes":45},"how-to-convert-word-documents-to-markdown","How to Convert Word Documents to Markdown: Complete Guide","Learn multiple methods to convert Microsoft Word documents to Markdown format. Includes Pandoc, online tools, and manual conversion techniques with examples.","Converting Microsoft Word documents to Markdown format is a common need for developers, technical writers, and content creators moving to Markdown-based workflows. Whether you're migrating…","2025-08-05","word to markdown, convert word document to markdown, docx to markdown converter, pandoc word markdown",5,{"slug":47,"title":48,"description":49,"excerpt":50,"date":51,"category":52,"author":53,"keywords":54,"readingMinutes":55},"markdown-to-jira-wiki-markup-guide","Markdown to Jira Wiki Markup: The Complete Conversion Guide","Converting Markdown to Jira wiki markup? This guide covers every syntax difference, explains how Jira Cloud vs Server handle formatting, and shows you how to automate the conversion.","If you write documentation in Markdown but need to post it to Jira, you've hit the wall: Jira has its own wiki markup language, and pasting Markdown directly doesn't work — or doesn't work…","2026-06-19","workflows","Matt Rathbone","markdown to jira, jira wiki markup, jira markdown conversion, atlassian wiki markup, jira formatting, jira text formatting, markdown jira syntax, jira cloud markdown",7,{"slug":57,"title":58,"description":59,"excerpt":60,"date":61,"category":62,"author":53,"keywords":63,"readingMinutes":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","confluence markdown, confluence markdown support, confluence markdown editor, atlassian markdown, confluence paste markdown, confluence import markdown",1792184947067]