← Better Diagrams

Documentation

Better Diagrams for Confluence

Better Diagrams is a Confluence macro for creating Mermaid diagrams from text. It provides a Mermaid source editor and renders a live diagram preview directly in Confluence.

Create a diagram

  1. On a Confluence page, insert the Better Diagrams macro.
  2. In the editor, enter Mermaid diagram source.
  3. Use Code, Preview, or Split mode while editing.
  4. Review the live draft preview.
  5. Select Save revision to save the diagram to the page.

On a newly created Confluence page, publish the page once before saving the first Better Diagrams revision.

Supported diagram formats

Better Diagrams renders Mermaid source. The app recognizes and supports these Mermaid diagram families:

  • Flowcharts
  • Sequence diagrams
  • Class diagrams
  • State diagrams
  • Entity-relationship diagrams
  • Gantt charts
  • User journeys
  • Pie charts
  • Mind maps
  • Timelines
  • Git graphs

The editor uses Mermaid with strict security settings. HTML labels are disabled.

Edit, save, and restore

  • Each save creates a new immutable revision rather than replacing prior content.
  • The current saved revision is displayed in the Confluence page macro.
  • A revision history is available, with up to the ten most recent revisions shown in the editor.
  • You can restore an earlier revision; restoration creates a new revision rather than overwriting the old one.
  • If someone else saved a newer revision, the app prevents overwriting it and asks the user to reload.
  • Existing diagrams remain available even if a save fails.
  • Saving or restoring requires a valid Marketplace trial or license. Existing diagrams can still be viewed and their source recovered in read-only mode.

View and inspect diagrams

  • Readers see the saved diagram on the Confluence page.
  • Diagrams can be enlarged, zoomed in or out, reset, and closed.
  • The app verifies the saved SVG's integrity before displaying it.

Import, recovery, and export

  • There is currently no separate file-import workflow. To create or change a diagram, paste or type Mermaid source into the editor.
  • From revision history, users can copy Mermaid source or download a revision as a .mmd Mermaid source file or an .svg diagram file.
  • Better Diagrams supports Confluence PDF and Word export through its macro export handler.
  • For Confluence exports, the app creates a PNG derivative stored as a Confluence attachment so the saved diagram can be included in exported documents.

Permissions and privacy

Better Diagrams runs on Atlassian Forge and has no external remote backend or external-host data egress.

Diagram source, rendered SVG revisions, and revision metadata are stored using Forge-hosted storage. Export artifacts are stored as attachments on the applicable Confluence page.

The app requests only the permissions needed to:

  • Store app data
  • Read Confluence content details and attachments
  • Create and manage the diagram export attachment on the Confluence page

Before saving or creating an attachment, the app checks that the current user has permission to update that Confluence page. It does not collect Atlassian passwords, API tokens, or third-party credentials.

Rendered SVG is sanitized before it is saved. The app removes scripts, embedded frames, event handlers, unsafe URLs, and other executable content.

Support

For help, contact lxxndr119@gmail.com.