Diagrams with Mermaid

Originally published: 24th September 2018

See the original blog post here.

This is a small intro into building HTML diagrams on the fly.

I really, really want to be able to visualise some stacks I am building on the go down the track, so I thought this would be a very convenient way to explore that.

Getting started

tl;dr

create-react-app hello-mermaid
cd hello-mermaid
yarn add mermaid debounce

Basics

For this particular example, I decided just to use create-react-app hello-mermaid just to get things up and going.

Once this installs, changed into the folder and either yarn add mermaid or npm install mermaid --save .

In this scenario, I want to also dynamically update the chart, so also add in yarn add debounce or npm install debounce as I will use a textarea html element for this which I want to only fire once after being debounced. Check my original blog post on debouncing in React for more information.

The code

I decided to start using the intro learn page for mermaid to get up an going. Following the instructions, I updated my src/App.js file to look like the following:

Updated CRA App.js file

What’s going on here? First of all, I am importing the required packages.

1. Import downloaded packages

Secondly, I have updated the render code to give me a `div` to target with the outputted graph and a text area I can add markdown into:

2. Updated render() method

Third, I want to initialise the graph with a basic chart on mount:

3. Add in the componentDidMount lifecycle method

Finally, I add the `handleChange` function to attempt an update to the graph.

4. Handle any changes to the text box

Now, when we run `yarn start` on the terminal and the web page opens up, we get the following site:

Aftermath of our updated App.js file

Great! Now thanks to our handleChange function and graceful handling, we can also dynamically update the chart on the fly.

I’ve added a few examples from the web that you can now copy and paste into our text box to see how it works!

graph LR
  A[Hard edge] -->|Link text| B(Round edge)
  B --> C{Decision}
  C -->|One| D[Result one]
  C -->|Two| E[Result two]

Graph LR after updating the textarea

sequenceDiagram
  Alice->>+John: Hello John, how are you?
  Alice->>+John: John, can you hear me?
  John-->>-Alice: Hi Alice, I can hear you!
  John-->>-Alice: I feel great!

Sequence diagram

Any while the code for the gantt chart will be omitted from the Medium article, update the textarea with more complicated examples like that give the following:

Gantt chart example

Next steps

Very cool! Now we can easily start creating some cool dynamic flows. What next? Be creative! I am planning to parse the markdown or html from the outputs and use it to help generate important reports or pseudocode to help build out some infrastructure or database schemas.

You can see the final code on the repo here.

Also, checkout their docs to see what else you can do!

Depth is a series that goes into more detail for projects than it’s friendly counterpart series “Hello”.

See the original blog post here.