Flowchart fiend? Let Quarto’s mermaid integration cast its spell

R
Quarto
Mermaid
Author

Luke Morris

Published

2022-08-28

For anybody who makes tons of flowcharts, mermaid.js may be the siren song that draws you to Quarto.

The Quarto’s documentation and functionality is extremely robust, so there are bound to be pieces we’ve all missed. The built-in mermaid.js functionality is quickly growing into a can’t-miss feature for me and likely anybody who spends a lot of time creating flowcharts – hi other healthcare folx!

flowchart LR
  A((Can I 
have pizza?)) A --> B{What time
of day is it?} B --> C(Morning) B --> D(Evening) B --> E(Supper Time) C --> F{Is said pizza
on a bagel?} D --> F E --> F F -->|Yes| G[YOU CAN EAT
PIZZA
ANYTIME!] F -->|NO| H[NO PIZZA
FOR YOU!]

There are inputs for almost every tweak you could think of making: shape, color, line type, subgroup, etc.

And it’s not just flowcharts you can make with mermaid. They’ve got sequence diagrams, user journey diagrams, entity relationship diagrams, git graphs that look like Metro rail maps, and Gantt diagrams, aka swimlane diagrams in healthcare parlance.

Unfortunately some of those formats are a hit-and-miss with properly rendering in Quarto at the moment (at least for me). We’re not going to talk about the two hours I just lost trying to get a swimlane chart to show at the proper width.

Let’s take a look at what’s behind a couple samples I was able to get to work:


```{mermaid}
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }
```
%%| echo: fenced
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

Example via Mermaid Live

I highly recommend using Mermaid Live for a WYSIWYG look at your changes on the fly. However, I don’t copy their specific Markdown output. Instead I just copy what I’ve been tweaking into a new Quarto mermaid block.


```{mermaid}
flowchart TD
A[Patient has <br> acute symptoms] --> B{Triage in ER: <br> Evidence of MI?}
B --> |Yes| C[Early anti-ischemia <br> /infarction therapy]
B --> |No| D[Ambulatory care: <br> Initial evaluation]
C --> E[Inpatient evaluation <br> and therapy]
C --> F[Ambulatory care: <br> Follow-up care]
F --> G{Invasive <br> evaluation done?}
G --> |No| H[Ambulatory care: <br> Rehab and follow-up]
G --> |Yes| I{Procedure <br> initiated?}
I --> |No| H
I --> |Yes| J[Revascularization <br> procedure]
J --> H
```
%%| echo: fenced
flowchart TD
A[Patient has 
acute symptoms] --> B{Triage in ER:
Evidence of MI?} B --> |Yes| C[Early anti-ischemia
/infarction therapy] B --> |No| D[Ambulatory care:
Initial evaluation] C --> E[Inpatient evaluation
and therapy] C --> F[Ambulatory care:
Follow-up care] F --> G{Invasive
evaluation done?} G --> |No| H[Ambulatory care:
Rehab and follow-up] G --> |Yes| I{Procedure
initiated?} I --> |No| H I --> |Yes| J[Revascularization
procedure] J --> H

Example adapted from the Institute for Healthcare Improvement’s Quality Improvement Essentials Toolkit

Even with all the hiccups of mermaid and Quarto not playing nice together, I think this can be a huge boon in my workday, and that of many others I imagine.