Diagrams

Overview

Quarto has native support for embedding Mermaid and Graphviz diagrams. This enables you to create flowcharts, sequence diagrams, state diagrams, gnatt charts, and more using a plain text syntax inspired by markdown.

For example, here we embed a flowchart created using Mermaid:

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

As illustrated above, diagrams are embedded using {mermaid} and {dot} executable cells (dot is underlying language of Graphviz)

Diagrams are a recent addition to Quarto—you should make sure to update to the very latest version of Quarto (v0.9.518 or higher) before trying out the features described below.

Note

For print output formats like pdf or docx, diagram rendering makes use use of the Chrome or Edge web browser to create a high-quality PNG. Quarto can automatically use an existing version of Chrome or Edge on your system, or alternatively if you don’t have either installed, can use a lighter-weight library version of Chrome (see Chrome Install below for details).

Mermaid

Mermaid is a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams.

Above we demonstrated a flowchart created with Mermaid, here is a sequence diagram (also embedded using a {mermaid} executable cell):

```{mermaid}
sequenceDiagram
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
    John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!
```

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
    John->>John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail!
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

Note that Mermaid output varies depending on the target format (e.g. HTML vs. print-based). See the section below on Mermaid Formats for additional details.

To learn more about using Mermaid, see the Mermaid website or the Mermaid book (which is written by the creator of Mermaid).

Graphviz

The Graphviz layout programs take descriptions of graphs in a simple text language, and make diagrams in useful formats. Graphviz has many useful features for concrete diagrams, such as options for colors, fonts, tabular node layouts, line styles, hyperlinks, and custom shapes.

For example, here is a simple undirected graph created using graphviz:

```{dot}
graph G {
  layout=neato
  run -- intr;
  intr -- runbl;
  runbl -- run;
  run -- kernel;
  kernel -- zombie;
  kernel -- sleep;
  kernel -- runmem;
  sleep -- swap;
  swap -- runswap;
  runswap -- new;
  runswap -- runmem;
  new -- runmem;
  sleep -- runmem;
}
```

G run run intr intr run–intr kernel kernel run–kernel runbl runbl intr–runbl runbl–run zombie zombie kernel–zombie sleep sleep kernel–sleep runmem runmem kernel–runmem sleep–runmem swap swap sleep–swap runswap runswap swap–runswap runswap–runmem new new runswap–new new–runmem

Note that the cell options syntax is slightly different for {mermaid} and {dot} (%%| and //|, respectively) because they have distinct character sequences for single-line comments.

To learn more about Graphviz, see the Graphviz website, this list of simple Graphiz Examples, or the Graphviz Gallery.

Authoring

There are a variety of tools available to improve your productivity authoring diagrams:

  1. The Mermaid Live Editor is an online tool for editing and previewing Mermaid diagrams in real time.

  2. Graphviz Online provides a similar tool for editing Graphviz diagrams.

  3. RStudio includes support for editing and previewing .mmd and .dot files (with help from the DiagrammeR package).

  4. The Quarto VS Code Extension supports live preview of diagrams embedded in .qmd files and in .mmd and .dot files:

    A Quarto document being edited in Visual Studio Code, with a live preview of the currenly edited diagram shown in a pane to the right

    Note that you should be sure to have installed the very latest version of the Quarto VS Code extension to try this out.

Figures

Diagrams can be treated as figures the same way that images and plot output are. For example, if we added the following figure options to the diagram above:

```{dot}
//| label: fig-simple
//| fig-cap: This is a simple graphviz graph.
```

We’d get this output:

G run run intr intr run–intr kernel kernel run–kernel runbl runbl intr–runbl runbl–run zombie zombie kernel–zombie sleep sleep kernel–sleep runmem runmem kernel–runmem sleep–runmem swap swap sleep–swap runswap runswap swap–runswap runswap–runmem new new runswap–new new–runmem

Figure 1: This is a simple graphviz graph

File Include

You might find it more convenient to edit your diagram in a standalone file and then reference it from within your .qmd document. You can do this by adding the file option to a Mermaid or Graphviz cell.

For example, here we include a very complex diagram whose definition would be too unwieldy to provide inline:

```{dot}
//| label: fig-linux-kernel
//| fig-cap: "A diagram of the Linux kernel."
//| file: linux-kernel-diagram.dot
```

Linux_kernel_diagram SCI System calls system system system->system_ processing processing sysfs proc & sysfs file systems SCI->sysfs DM Device Model sysfs->DM log_sys system run, modules, generic HW access DM->log_sys bus_drv bus drivers log_sys->bus_drv buses buses: PCI, USB … bus_drv->buses sock Sockets networking networking networking->networking_ prot_fam protocol families sock->prot_fam log_prot protocols: TCP, UDP, IP prot_fam->log_prot netif network interfaces and drivers log_prot->netif net_hw network: Ethernet, WiFi … netif->net_hw NFS NFS NFS->log_prot proc Processes processing->processing_ memory memory Tasks Tasks proc->Tasks sync synchronization Tasks->sync sched Scheduler sync->sched IRQ interrupts core, CPU arch sched->IRQ CPU CPU IRQ->CPU bottom © 2007-2022 Costa Shulyupin http://www.MakeLinux.net/kernel/diagram MA memory access VM Virtual memory MA->VM mmap memory mapping VM->mmap log_mem logical memory mmap->log_mem SW Swap mmap->SW PA Page Allocator log_mem->PA RAM MMU, RAM PA->RAM block Block devices and drivers SW->block SD storage devices: SCSI, NVMe … block->SD PC page cache PC->PA memory->memory_ storage storage FS files and directories storage->storage_ VFS Virtual File System FS->VFS VFS->NFS VFS->mmap VFS->PC logFS logical filesystems: ext3, xfs … VFS->logFS logFS->block char char devices HI human interface HI->HI_ input input subsystem char->input F7 HI class drivers input->F7 HID HI peripherals drivers F7->HID display keyboard, mouse, display, audio HID->display functions functions functions->functions_ layers layers usr user space interfaces usr->usr_ virt virtual subsystems usr->virt virt->D0 bridges bridges virt->bridges bridges->E0 logical logical bridges->logical logical->F0 HWI hardware interfaces logical->HWI HWI->G0 HW electronics, hardware HWI->HW HW->H0 layers->usr LKD Linux kernel diagram

Figure 2: A diagram of the Linux kernel.

Note that the label and fig-cap attributes still work as expected with file includes.

Sizing

By default, diagrams are rendered at their natural size (i.e. they are not stretched to fit the default figure size for the current document). Within HTML output formats, diagrams are also made responsive, so that their width doesn’t overflow the current page column. This is similar to the treatment given to images and dynamic JavaScript widgets.

You can disable responsive sizing by specifying the fig-responsive: false option. You can also specify explicit sizes via fig-width and fig-height. For example, here we want to make a mermaid diagram a bit bigger because it contains only a few elements:

```{mermaid}
%%| fig-width: 6.5
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}

Mermaid Formats

When you include a Mermaid diagram in a document, the diagram format used is chosen automatically based on the output format:

Format Output
HTML (html, revealjs, etc.) Mermaid native (JavaScript)
GitHub Flavored Markdown (gfm) Mermaid code block
Other Formats (pdf, docx, etc.) PNG image

The Mermaid native format is used by default whenever the underlying output format supports JavaScript.

When using format: gfm, diagrams will be emitted as plain mermaid code blocks. This is because both GitHub and GitLab natively support rendering Mermaid diagrams from code.

For formats that don’t do special handling of Mermaid or lack a JavaScript run-time (e.g. formats like pdf, docx, epub, etc.) a PNG image is created using Chrome.

You can change the default behavior using the mermaid-format option. For example:

---
format:
  gfm:
    mermaid-format: png
---

Valid values for mermaid-format include js, png, and svg,

Code Echo

Note that unlike other executable cell handlers (e.g. {python}), cells with diagrams don’t display their code in the rendered document by default. You can display code by adding an echo: true option in a comment at the top the cell.

To include code for {mermaid}, add %%| echo: true to the top of the cell. For example:

```{mermaid}
%%| echo: true
```

To include code for {dot}, add //| echo: true to the top of the cell. For example:

```{dot}
//| echo: true
```

Chrome Install

For print output formats like pdf or docx, diagram rendering makes use use of the Chrome or Edge web browser to create a high-quality PNG.

Quarto can automatically use an existing version of Chrome or Edge on your system for rendering. Alternatively, if you don’t have either, you can install a minimal version of Chrome for use by Quarto with the following command:

Terminal
quarto tools install chromium
Note

Quarto installs headless Chromium via Puppeteer. The bundled Chromium that Puppeteer installs may not work on Docker containers; please check the Puppeteer documentation.