How to Embed Draw.io Diagrams in Confluence

In this tutorial, you'll learn about How to Embed Draw.io Diagrams in Confluence. We cover key concepts, practical examples, and best practices.

draw.io diagrams embedded in Confluence appear as a white box, fail to load, or show "Plugin not found." The draw.io for Confluence plugin needs configuration.

The Wrong Way

// Pasting a PNG screenshot of the diagram into Confluence
// This makes it uneditable — anyone who needs to change it must recreate it

Static images create maintenance burden. Every edit requires re-exporting from the original draw.io file.

The Right Way

Step 1: Install the draw.io for Confluence plugin

# In Confluence: Settings → Apps → Find new apps
# Search "draw.io" → Install "draw.io for Confluence"
# Requires Confluence admin privileges

Step 2: Embed a diagram using the macro

# In the Confluence editor:
# /drawio → select "draw.io Diagram" macro
# Choose:
# - "Create new" → opens the embedded draw.io editor
# - "Upload file" → imports an existing .drawio file
# - "From URL" → links to a diagram URL

Step 3: Configure display options

# Macro properties:
# - Width: 100% (responsive)
# - Height: 400px (or auto)
# - Show border: Yes/No
# - Lightbox: Enable for full-screen editing

Step 4: Edit embedded diagrams

# Click the diagram on the Confluence page → "Edit diagram"
# The draw.io editor opens inline
# Changes save back to the Confluence page automatically

Embedded draw.io diagram renders on the Confluence page — editable inline, updates instantly, no file management needed.

Prevention

• Use draw.io's Confluence macro instead of uploading images for any diagram that may change.
• Store diagrams as Confluence page attachments (the macro does this automatically).
• The inline-editing pattern is the same one used by Doda Browser's developer tools — edit and preview in the same context without switching windows.

Common Mistakes with confluence embed

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world DRAWIO code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ