Confluence Cloud doesn't come with a diagram macro. For many teams that's a real gap. They want to show their architecture, a workflow, or how the components of a system connect to each other, right on the page next to the text that explains it.
So they go to the Atlassian Marketplace and install a diagram app, often one for Mermaid, where you write the diagram as text and the app draws it for you. On screen it works well, and for a while everyone is happy.
Then, sooner or later, someone asks for the page as a PDF or a Word file: for an auditor, a customer or an offline review. That’s where the problem starts. Not every Mermaid app supports PDF or Word export, and the file comes back with a blank box, an error message or a diagram cut in half.
This article collects what Confluence Cloud users report in this situation, explains why it happens, and lists what you can check before you send the file.
What people run into
The same complaints come up again and again in Community questions about PDF export.
The diagram is too big and gets cut off. It looks fine on screen, but in the PDF it is enlarged past the page edge and cropped.
The diagram is there but nobody can read it. The resolution drops so low that labels turn into blur. People have been asking about this for years.
Word export drops the diagram. PDF at least shows something, while the Word file comes out with a gap or a broken image icon where the diagram used to be. Users of other diagram apps report the same.
The diagram turns into an error message or an empty box. Instead of the picture, the PDF shows a placeholder or an error from the app.
Why it happens
Mermaid diagrams are text. A JavaScript library turns that text into a picture in your browser when you open the page.
Export doesn't happen in your browser. Confluence builds the PDF or Word file on its own servers, where that script never runs. So the app has to hand Confluence a ready-made picture of each diagram. Not every Mermaid app does this. Some show a blank box or an error in every export, and some handle PDF but not Word. Even when the app does its part, Confluence's PDF engine decides how big the picture ends up on the page, which is where the oversizing and cropping come from.
Before you start: check your app
Look for PDF and Word export on your Mermaid app's Marketplace listing or in its documentation. If neither mentions export, assume it doesn't work until you test it.
Example: exporting a page with our app
Here is the whole flow with Apportunity: Mermaid Diagrams Macro for Confluence. It works in Confluence Cloud with the new editor and supports both PDF and Word export.
1. Add the diagram. In the editor, type /, pick the Mermaid Diagram macro and write your diagram. For a page that will be printed, start the code with a light theme. Here is the export process itself, as most of us know it:
---
config:
theme: neutral
layout: elk
---
flowchart TD
A[Auditor asks for a PDF] --> B[Export to PDF]
B --> C{Is the diagram in the file?}
C -->|Yes| D[Send it before anyone edits the page]
C -->|No, just an empty box| E[Blame Mermaid]
E --> F[Read this article]
F --> B
Without a theme line, the diagram follows each reader's light or dark mode. With one, everyone gets the same colors, and our theming guide describes neutral as a grayscale palette that is good for print. layout: elk arranges the diagram with fewer crossing lines.
2. Publish the page. The app stores the diagram as a page attachment, so it stays with the page when you copy or move it.
3. Export. Open the ••• menu at the top of the page and choose Export, then Export to PDF or Export to Word.
Export is in the ••• menu at the top of the page.
The diagram appears in the file in place of the macro.
The exported PDF: the diagram sits where the macro was, and the labels stay readable.
4. Need the diagram on its own? Save it as PNG or SVG, or copy it to the clipboard, and paste it into slides or an email.
The macro's own menu: copy to clipboard, or save as PNG or SVG.
Tips for a clean export
- Test one page first. Export a single page with your largest diagram before you export a whole space or a page tree. Problems show up there first.
- Match the diagram to the paper. A portrait page is taller than it is wide. A wide
flowchart LR with twenty steps will shrink or overflow. Switch to flowchart TD, or split the flow into two diagrams. - Split very large diagrams. A system map with hundreds of nodes is hard to read on paper at any resolution. One diagram per subsystem prints better and is easier to review.
- Keep a fallback. If a diagram still breaks, save it as PNG or SVG and insert the image next to the macro. The image won't update when the code changes, so date it or add a note.
Over to you
If you export Mermaid diagrams regularly, what breaks for you: size, resolution, Word, or something else? Share it in the comments.
Disclosure: I work for Apportunity, the team that builds Apportunity: Mermaid Diagrams Macro for Confluence. I use our app as the example above, and the tips apply whichever app you use.
