The compliance reviewer replied on Friday afternoon.
"Can you send the architecture diagram as a PDF attachment? The Confluence link is fine for the team, but our vendor packet needs a file."
The author opened the Mermaid macro, found export options, and clicked PDF. On a smaller test diagram, it worked. On the production architecture map — the one with four subgraphs and thirty-two services — the download failed in one browser and produced a cropped image in another.
That is the gap behind export Mermaid diagrams from Confluence workflows. The diagram renders on the page. The handoff format you promise stakeholders may not survive browser limits, Forge iframe permissions, canvas constraints, or diagram size.
"Which export button is the real source of truth?"
Quick Answer
- Most reliable handoff: Mermaid source text and sanitized SVG.
- Best-effort handoff: PNG, raster PDF, and clipboard image — validate on your largest real diagrams before you commit to them.
- Separate path: Confluence whole-page PDF export is not the same as a macro's client-side PDF export.
BacklogBridge Diagram Lens for Confluence public docs describe this split explicitly. Other Mermaid macros may differ — verify export behavior in a sandbox trial.
Quick Decision Table
| Stakeholder asks for… | Export first | Validate on largest diagram? | If it fails… |
|---|---|---|---|
| Editable diagram for engineering | Mermaid source | No — text handoff | Provide SVG as visual supplement |
| Slide or design review file | Sanitized SVG | Light check in target viewer | Split diagram scope; avoid untested PNG |
| Email/Slack image | Clipboard or PNG | Yes | Use SVG download; avoid browser screenshot |
| Vendor/compliance PDF | Macro raster PDF | Yes — required | Hand off SVG + written note; do not substitute page PDF without comparison |
| Full Confluence page archive | Confluence page PDF | Yes — separate test | Do not assume macro PDF matches page PDF |
What You Are Trying To Accomplish
You want to share a Confluence Mermaid diagram with people who do not live in the page:
- engineers who need editable source
- reviewers who need a vector file for slides
- procurement or compliance contacts who ask for PDF
- chat threads where a pasted image is faster than a link
The outcome is a defined primary export format per audience, validated on real diagrams — not a last-minute click on whatever button works on a three-box test flowchart.
Requirements
| Requirement | Why it matters |
|---|---|
| Approved Mermaid macro in Confluence Cloud | Export menus live in the macro; behavior varies by app |
| A real "large" diagram for testing | Raster limits appear on production maps, not toy sketches |
| Known stakeholder format | PDF vs SVG vs source-in-repo changes the workflow |
| Browser matrix if raster exports matter | Forge Custom UI and clipboard APIs vary by browser |
| Admin approval for Marketplace macros | Site admins install through Connected Apps |
Native Confluence vs Mermaid Macro Exports
Confluence pages can host Mermaid-like content through native features or third-party macros. Export options depend on the macro you installed.
A Forge macro with an export menu — such as Diagram Lens — generates files client-side from rendered output. Native page content may not offer the same Mermaid source download, SVG copy, or raster export paths. Confirm export behavior on the exact macro your space uses before documenting team handoff rules.
Step 1: Choose The Handoff Format By Audience
The Mermaid documentation describes diagrams as text and code. When the recipient can use text, Mermaid source is the most durable export because it survives re-rendering, diffs, and tooling changes.
| Audience need | Start with | Fall back | Avoid assuming |
|---|---|---|---|
| Engineering / platform team | Mermaid source | SVG | PNG as the canonical artifact |
| Design or slide review | Sanitized SVG | Tested PNG | Untested clipboard paste |
| Vendor / compliance packet | Validated PDF on largest diagram | SVG + cover note | Page PDF without checking macro output |
| Slack / email quick share | Clipboard image after test | PNG download | Screenshot of browser zoom |
Step 2: Export Mermaid Source
Source export is the handoff path documentation teams should default to for maintained architecture and process diagrams.
Why source wins:
- Diff-friendly — reviewers see what changed between releases.
- Re-renderable — recipients can render in IDE plugins, docs pipelines, or another approved macro.
- Independent of canvas limits — no browser rasterization step.
Workflow:
- Open the macro editor or export menu from page view or wide view.
- Copy or download Mermaid source.
- Store in the ticket, repo, or attachment system your team uses for doc review.
- Include the Confluence page link as provenance, not as the only artifact.
Diagram Lens support docs treat source copy/download as a primary reliable path alongside SVG. Public product copy also surfaces line and character counts so authors can see when source is approaching size limits before render or export fails.
Step 3: Export Sanitized SVG
When stakeholders need a visual file but not editable source, Mermaid SVG export is the most reliable visual handoff from a Confluence macro — provided the macro sanitizes exported SVG the same way it renders on the page.
Why SVG over PNG:
- Vector output scales in slides and print layouts.
- Text remains selectable in many viewers.
- Avoids the canvas dimension constraints that affect raster export.
Workflow:
- Confirm the diagram renders correctly in page view or wide view.
- Export or copy SVG from the macro export menu.
- Open the file in your target tool (slide deck, diagram viewer, ticket attachment).
- Compare labels and layout against on-page rendering.
Interactivity note: Macros with strict Mermaid security models — including Diagram Lens per public security page — sanitize SVG and strip click actions or JavaScript links. Exported SVG is meant for safe viewing, not interactive diagrams. If authors expected clickable nodes in the handoff file, set that expectation before export.
For a fuller macro security review, see Mermaid Macro Security in Confluence.
Step 4: Test PNG And Clipboard Image
Mermaid PNG export Confluence workflows are common — and commonly over-trusted.
PNG and clipboard image export typically rasterize the rendered diagram in the browser. That introduces variables:
- Browser support for download and clipboard APIs
- Forge iframe permissions — clipboard and file generation inside embedded Custom UI may be blocked by browser policy or enterprise controls
- Canvas limits when very large diagrams exceed practical raster dimensions
- Diagram size — node count, label length, and subgraph depth affect output size and memory use
Treat PNG and clipboard as best effort:
- Test on your largest production diagram, not a minimal example.
- Try more than one browser if your organization allows it.
- If PNG fails, export SVG first — Diagram Lens support troubleshooting recommends this order.
- Record which browser succeeded if your team standardizes on one.
Do not promise stakeholders a PNG workflow until that test passes.
Before You Rasterize: Viewport And Framing
Raster exports often capture the macro's current viewport — not an abstract "whole diagram" unless the macro fits to view first.
| Situation | Risk | Mitigation |
|---|---|---|
| Zoomed into one cluster in wide view | Cropped PNG/PDF | Use Fit or reset zoom before export |
| Long left-to-right architecture map | Tiny labels in raster output | Open wide view; fit to view; prefer SVG |
| Page column scaling | Blurry raster text | Export from macro menu, not a page screenshot |
When diagrams routinely outgrow the page column, reader tools matter for inspection — but they do not replace export validation. See Mermaid Diagrams in Confluence: Why Big Diagrams Need a Reader.
Step 5: Test Raster PDF And Distinguish From Confluence Page PDF
Confluence diagram PDF export confuses two different pipelines:
| Export path | What it captures | Typical use |
|---|---|---|
| Macro client-side PDF | Rasterized diagram from the macro's rendered output | Attachment for a single diagram |
| Confluence whole-page PDF | Confluence page export layout | Full page or space documentation packet |
Diagram Lens support known limitations state Confluence whole-page PDF export is separate from Diagram Lens client-side PDF export. They may not produce equivalent framing, resolution, or macro fidelity.
For raster PDF from the macro:
- Run the same large-diagram test you used for PNG.
- Confirm headers, labels, and subgraph boundaries are legible at 100% zoom in the PDF viewer.
- If PDF fails, hand off SVG with a short note rather than a cropped raster.
Worked example: Vendor packet asks for PDF
| Step | Action |
|---|---|
| 1 | Identify the largest diagram in the packet scope |
| 2 | Attempt macro PDF export in the browser your team standardizes on |
| 3 | Open PDF at 100%; verify subgraph labels and edge text |
| 4 | If pass → attach macro PDF; keep Confluence link as live source |
| 5 | If fail → attach sanitized SVG; note that PDF raster export exceeded browser/macro limits |
| 6 | Optionally compare Confluence page PDF — only if the packet requires full page context |
Do not silently substitute a page screenshot when PDF export fails. That drops selectable text and may clip wide diagrams.
Export Format Comparison
| Format | Reliability | Strengths | Limitations |
|---|---|---|---|
| Mermaid source | Primary | Editable, diffable, re-renderable | Recipient must accept text |
| Sanitized SVG | Primary | Scalable vector; aligns with strict macro rendering | Interactivity stripped; not ideal for PDF-only non-technical reviewers |
| PNG | Best effort | Universal image support | Canvas/browser limits; viewport framing |
| Clipboard image | Best effort | Fast paste into chat | iframe + clipboard permission variance |
| Macro raster PDF | Best effort | Single-file handoff | Same raster limits as PNG; not page PDF |
| Confluence page PDF | Separate workflow | Full page context | May not match macro export fidelity |
Common Pitfalls
| Pitfall | Better approach |
|---|---|
| Promising PDF before testing the largest diagram | Validate raster paths on production-sized source |
| Using PNG as the engineering system of record | Default to Mermaid source or SVG |
| Assuming page PDF equals macro PDF | Test both if compliance requires PDF |
| Exporting while zoomed into one cluster | Fit to view or reset zoom before raster export |
| Skipping SVG when PNG fails | Follow vendor troubleshooting: SVG first |
| Screenshot instead of export | Screenshots drop selectable text and may clip wide LR diagrams |
| Expecting clickable exported diagrams from strict macros | Use Confluence links for navigation; export static SVG |
Admin And Security Notes
Atlassian's Manage your apps documentation says Confluence apps install from Marketplace through Connected Apps and require site admin access.
For export-heavy Mermaid workflows, admins and appsec reviewers should verify:
| Check | Why it matters for export |
|---|---|
| Export generated locally vs remote | Remote renderers add data-flow review |
| SVG sanitization on export | Export must match safe on-page rendering |
| Source-size limits | Oversized source may block before export is available |
| Browser/iframe clipboard permissions | Clipboard export may fail under strict policies |
At the time of research on July 15, 2026, I did not find an official Atlassian Marketplace listing for BacklogBridge Diagram Lens for Confluence through available public sources in sibling editorial research. Search Marketplace again before install.
Do not infer SOC 2, ISO, Cloud Fortified, GDPR/DPA, or procurement approval without explicit published evidence.
Validation Checklist
Test with one diagram your team already uses for stakeholder handoff.
- Export Mermaid source; confirm it re-renders in your approved toolchain.
- Export SVG; compare labels against page view at normal zoom.
- Open wide view; fit to view; export PNG on the largest diagram; note browser and outcome.
- Repeat PNG or PDF in a second browser if policy allows.
- Copy clipboard image into the target channel; confirm clarity.
- Export macro PDF; open at 100% and check legibility.
- Optionally export Confluence page PDF; compare framing to macro PDF.
- Record failures and fall back to SVG or source — do not silently substitute screenshots.
When To Use A Different Approach
- Canvas-first diagrams where PNG from a visual editor is the norm — see Mermaid vs draw.io and Gliffy in Confluence.
- Large diagrams that fail raster export — split the map or hand off SVG/source; see Architecture Diagrams in Confluence.
- Repository-backed diagram sync — Diagram Lens public pages state it does not include repository sync; choose a different tool category if Git is the system of record.
Final Recommendation
Teams export Mermaid diagrams from Confluence reliably when they treat Mermaid source and sanitized SVG as primary handoff paths and PNG, raster PDF, and clipboard image as best-effort conveniences validated on real diagrams.
Define the format by audience, fit the viewport before rasterizing, test in more than one browser when exports matter, and keep Confluence page PDF separate from macro client-side PDF. If your macro is Diagram Lens, public support docs align with that hierarchy — but your process should still rest on sandbox tests with your largest diagrams and browsers, not this article.
For authoring discipline that makes exports more useful, see Architecture Diagrams in Confluence: Keeping Mermaid Source Reviewable and Backlog Bridge's Mermaid chart tips guide.