Mermaid, Graph Building with Markdown
First published by Pat Godfrey: November 1 2019
…
Mermaid is an interesting project for creating SVG-based flow charts and other graphs using a form of Markdown. This makes it an attractive proposition for illustrating API and similar documentation.
This article's scope is to a technical writer's perspective. Developers can extend their Mermaid using APIs, etc. Review the Mermaid Documentation for full details.
Shared Learning
Flag this content to your friends, connections, and colleagues.
What is Mermaid?
Mermaid is an award-winning documentation feature created by Knut Sveidqvist. It combines HTML and a form of Markdown with JavaScript to create SVG images of flows and other charts, which can be styled with CSS.
Keep Calm. It's only code
The code may be scary to non-digital workers with no interest in, or capacity to learn our creative medium of HTML. It isn't scary at all.
Writers using WYSIWYG text editors including for Drupal and Wordpress CMS applications will need to switch to their HTML views. Some basic HTML knowledge is needed if only to avoid breaking stuff by accident.
Why Use Mermaid?
The short answer is to implement flow charts and other graphic content into API documentation. YAML (YML) files support Markdown, so the logical connection is to employ Mermaid.
Creating diagrams is easy using Microsoft PowerPoint, or other vector image applications that output PNG or JPG. High-end applications such as Adobe Illustrator export vectors as SVG. And not everyone can.
The attraction of Mermaid is that it puts a standard graphic creation tools in the hands of workers who may not have the graphic skills, software (who doesn't have PowerPoint?), or ability to post a responsive picture
formatted image array into thier products.
Important: Mermaid is not natively accessible to everyone. Discover more in the Accessibility section below.
Mermaid removes the common image issues caused by workers who are not familiar with the performance or accessibility of online products including:
- Image file preparation and design
- Image file scale.
- Image file type and optimisation.
- Alternative texts and long descriptions.
In short, Mermaid could save on resources and enable local standards controlled by the technical writing lead.
Mermaid Examples
The example (at Figure 1.) is encoded in the HTML as follows:
<div class="mermaid"> graph TD A[Web Content] -->|Orientation| B(User Task) B --> C{Let me think} C -->|One| D[Orientation] C -->|Two| E[Findability] C -->|Three| F[Usability] C -->|Four| G[Learnabillity] <div>
The Mermaid <script>
is linked to on the host page to a directory containing all the files necessary for the Markdown to work:
<script src="../resources/mermaid/mermaid.min.js"></script> <script>mermaid.initialize({startOnLoad:true});</script>
The display is left-aligned and is not natively fluid-responsive. We can fix this with a touch of CSS to justify the content to the center, and enable scaling in narrower viewports. (See Figure 2.)
Setting Up Mermaid
Mermaid requires a number of files to be saved and then accessed from a local directory.
For playing on your local machine or webspace, the files can be downloaded from https://unpkg.com/browse/mermaid@8.4.0/dist/, where "8.4.0" is the version number. Update the version number when required.
If you "right-click" and Save As, the files may become corrupted with HTML in the process. I fixed this patiently by:
- Opening each link individually.
- Choosing to View Raw
- Copy and pasting the "raw" code into a text editor.
- Saving the file per the original file name.
See Figure 3.
Note: Take care that your text editor saves the files with the correct extentions.
CMS Installaton
Consult your CMS administrator when wanting to install the Mermaid files.
Styling Your Mermaid
A full reference to styling Mermaid is available from the unpkg.com/mermaid (v0.5.6.) documentatation. By example, the background colours added to the flowchart at Figure 3 are styled as follows:
%% Set the classes. classDef success fill:#8FD27F,stroke:#8FD27F; classDef flow fill:#A2C3FB,stroke:#A2C3FB; classDef quest fill:#FABE78,stroke:#FABE78; %% Assign the classes. class A,I success; class B,C,D,E,F,G,H flow; class C quest;
The syntax is to define the style declarations using a class and then to assign the class to the node or nodes.
IMPORTANT: Try to keep a contrast between the text colour and the background. Look up WCAG contrast ratios for guidance. (The contrast ratios in the styled example are just on the 7:1 ratio recommended).
Mermaid Initial Review
This Mermaid lark isn't out-of-the-box easy to create. It takes a little (and for me, much) more cognitive effort than only dragging boxes around an image editor.
Once I had created the original spider's web of a Set Up flow chart above, I pasted my Frankensteinian creation into the Mermaid Live Editor. After some faffing around and learning how to string the nodes together, re-jigging the identities, and interconnecting the ones I wanted connected, it all clicked into place.
Performance Cost
The rendered code output is not excessively heavy and is still weighty enough to look heavy. (See Figure 4).
Although the result is reasonable lightweight, the browser must make a number of HTTP requests and download a very weighty collection of resources, which can slow down page loading times when combined with other scripts needed to run the page successfully.
On a rural connection throttled to 6 MBps, this page can take several seconds to load the Mermaid graphs.
Swimming With Mermaid
A popular flow diagram is the swim-laned process, or sequence diagram.
I recently inherited a swim laned flow and converted it into a PNG image to accommodate accessibility and its responsive rendition in a browser. Unfortunately, neither the <picture>
element or inline-CSS is available to the client, so the single-file image is still not ideal. In Mermaid, we have hope.
So, let's give it a go. (See Figure 5).
Hmmm?
Well, OK. It's a process flow diagram. And it responds badly when the viewport narrows. Quickly, the copy text gets so small we cannot even see it—never mind read it. Can we fix that?
Yes. We can! At least, sufficiently to enable its use. We can:
- Park the mermaid
<div class="mermaid"...>
inside an<article>
(or other block element). - Give the
<article>
anoverflow-x:scroll;
style declaration. - Give the
div class="mermaid"
a minimum width.
When the viewport narrows and the chart reaches its narrowest allowed width, the <article>
scrolls.
Here's an overview of the code used in the horizontaly scrolling sample at Figure 6:
<article class="scrollHorizontal"> <div class="mermaid mermaidContainer"> <!-- Graphic goes here--> </div> </article> <style> (Note: for demo purposes only) .scrollHorizontal { width:100%; height:auto; overflow-x:auto; } .mermaidContainer { min-width:800px; } </style>
The graphic is now made available for narrow viewports on larger dipslays. However, scrolling is not always signalled by mobile device browsers. When a scrollbar is available, increased cognitive and motor effort both need considering.
As always, it depends.
Accessibility
Being compiled using JavaScript, Mermaid graphics will not display meaningfully when JavaScript is disabled.
Note: Statistically, over 400,000 of our UK users have JavaScript disabled in their browser.
Mermaid is not (very) accessible. The texts can be accessed and then the meaningful and contextual visual node connections and boxes are lost to less able users.
Solution?
A solution is to:
- Screen-grab the graphic and then save as a PNG or JPG file.
- Display the image in the Mermaid div by default.
- On load, hide the image using JavaScript.
- Offer an inline or separate 'text only' description.
Non-JavaScript browsers will now render the image. Then use JavaScript to remove the image before Mermaid scripts load.
Note: We can use the accessible and responsive <picture>
to serve images most approriate to the viewport.
Alternative Access to Content
The provision of a comparable and equitable experience is too often overlooked in our digital production. Access to our content is our users' right as enshrined in modern Human Rights acts. Discover more on this from my MSc UX research blog.
A text only description must be offered for users unable to access Mermaid content. This can be within the page copy or in a separate file.
Overcoming Ableism
Our ableist design fails to offer a comparable and equitable experience.
The basic premise is that HTML is (90%) natively accessible. Our visual-biased and ableist design imposes barriers to access, which we then add accessibility adjuncts to and complicate or frustrate our less able users' experience.
Accessing Figure 3
An accessibility strategy was discussed for Mermaid graphics above. And what about providing a comparable and equitable experience? We need a strategy:
- Understand our able users' experience.
- Create a visualisation of the flow.
- Enhance the flow with the content.
- Review the content in isolation. Does it offer a comparable experience in isolation?
- Design strategies to close the experiencial gap.
- Test, where possible.
- Implement. And make this a standard for your product.
A hasty example is at Figure 7.
Summary
Mermaid is an interesting proposition that requires some knowledge and skill to implement well. It needs only minimal thought to make its content accessible and unfortunately, the procedures and techniques required may be beyond our workers' or our CMS capabilities.
All is not lost. Our workers can easily pick up a touch of HTML and within an enabled CMS environment, overcome the difficiencies and produce Mermaid graphics confident they are not discriminating our less able users.
Reference this article
Godfrey, P. (Year, Month Day). Article Heading. Retrieved Month Day, Year, from URL