Have you ever wanted to create diagrams in a standard format, without the need to click and drag around? Or you wanted people to make diagrams where the look and feel were automatically consistent?

I like graphical user interfaces as much as everyone else as they naturally have an easier learning curve, however I found this was overkill for some simple diagram types, for example flow diagrams would have different padding and spacing depending on the mood I was on that day.

So I wanted to find a more consistent method, that would allow me to just focus on the content and not the style. I did some research and found two popular alternatives: Mermaid and PlantUML (more on this with challenges later).

What it does

Using markup like:

graph TD
  A[Christmas] -->|Get money| B(Go shopping)
  B --> C{Let me think}
  C -->|One| D[Laptop]
  C -->|Two| E[iPhone]
  C -->|Three| F[fa:fa-car Car]

To create diagrams like:

Flow chart example

Mermaid supports multiple diagram types:

  • Flowchart

  • Sequence diagram

  • Gantt diagram

And a bunch of other ‘experimental’ types.

This a good time to point out that the app I have written is solely for integrating Mermaid’s Live Editor project into Confluence using the Forge framework. Credit should be given to Mermaid and the live editor for creating the markup rendering.

How I built it

The app was created with Forge using the the following modules:

  • macro - to provide the diagram image and the configuration form

  • function - to define the behaviour of rendering the diagram and the form

Credit should be given to the Mermaid project for defining the markdown rendering and Mermaid’s Live Editor project for rendering the diagram to an image format.

The app encodes the markdown added through the macro and displays an image sourced from the live editor project.

Challenges I ran into

From the beginning, I did not know how to approach the problem, all I wanted was to use markup to create diagrams. So I started spikes to determine the paths I could take.

The first spike I conducted was to determine libraries that I could use so that I could render the images in Forge. It became apparent that I could not use most libraries as they all required a window DOM. Given the time limitation for completing the project, I chose not to rewrite a rendering engine.

In my second spike I investigated further into using external services to provide the rendering. I looked at both using Mermaid and PlantUML. PlantUML was more fully featured with support for more diagram types than Mermaid. I ended up not going with PlantUML because it did not secure the connection with SSL and made the whole page appear unsecured.

Accomplishments that I’m proud of

Working with Forge has been a pleasure, and the main accomplishment that I have personally gained is how quick it has been for me to get prototypes working.

What I learned

I learned that Forge apps can be used to build on top of other solutions. In my case, I did not need to rewrite the Mermaid libraries, but instead just extended the Mermaid project.

Whats next for Mermaid

I would like to add more dynamic charts, for example to pull in Jira issues and display a pie chart of the statistics. or maybe a timeline using a start date and end date of issues.

Architecturally, I would like to find a method of rendering the diagrams without an external service whether that is via another serverless application or directly in Forge.

Built With

Share this project: