Diagrams

Overview

Quarto has native support for embedding Mermaid andgraphviz diagrams. This enables you to create flowcharts,sequence diagrams,state diagrams,gantt charts,andmore 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,Mermaid diagrams are embedded using { mermaid } executable cells. graphviz diagrams are embedded using { dot } executable cell . note that cell option are add with slightly different syntax :%%| for { mermaid },and//| for { dot }.

For print output formats like pdf ordocx,diagram rendering makes use of the Chrome orEdge web browser to create a high-quality PNg. Quarto can automatically use an existing version of Chrome orEdge on your system,oralternatively 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 andcharting tool that uses Markdown-inspired text definitions anda renderer to create andmodify complex diagrams.

Mermaid diagrams use %% as their comment syntax ,andso cell option are declare using%%|. cell option must be include directly beneath the start of the diagram code chunk .

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 format for additional details.

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

graphviz

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

graphviz diagrams use // as their comment syntax ,andso cell option are declare using//|. cell option must be include directly beneath the start of the diagram code chunk .

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;
}
` ` `

To learn more about graphviz,see the graphviz website,this list of simple graphiz Examples,orthe 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 andpreviewing Mermaid diagrams in real time.

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

3. RStudio includes support for editing andpreviewing .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 andin .mmd and.dot files:

   

   note that you should be sure to have instal the very late version of the Quarto VS Code extension to try this out .

Cross-References

Diagrams can be treated as figures the same way that images andplot 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 is get ’d get this output :

Figure 1:This is a simple graphviz graph.

We could then create a cross-reference to the diagram with:

To create a cross-references to a diagram using div syntax,treat it like a figure. For example,Figure 2 is created using:

:::{#fig-simple}

` ` `{ dot }
graph {
  A  --B
}
` ` `

This is a simple graphviz graph
:::

Figure 2:This is a simple graphviz graph

If you would rather give diagrams a label andcounter distinct from figures,consider defining Custom Cross-Reference Types.

File Include

You might find it more convenient to edit your diagram in a standalone .dot or.mmd file andthen reference it from within your .qmd document. You can do this by adding the file option to a Mermaid orgraphviz 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
` ` `

system

processing

proc & sysfs file systems device Model system run, modules, generic HW access bus driver bus: PCI,USB … Sockets networking

protocol families protocols: TCP,UDP,IP network interface and driver network : Ethernet,WiFi … NFS Processes memory

Tasks synchronization scheduler interrupt core, CPU arch CPU © 2007-2022 Costa Shulyupin http://www.MakeLinux.net/kernel/diagram

memory access virtual memory memory mapping logical memory swap page Allocator MMU,ram block device and driver storage device: SCSI ,NVMe … page cache storage

files and directories virtual File System logical filesystem : ext3 ,xfs … char device human interface

input subsystem hi class driver HI peripherals driver

keyboard,mouse, display,audio function

layer

user space interface virtual subsystems

bridges

logical hardware interface electronics, hardware Linux kernel diagram

Figure 3:A diagram of the Linux kernel.

note that thelabel andfig-cap attributes still work as expected with file include .

size

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 anddynamic JavaScript widgets.

You can disable responsive sizing by specifying the fig-responsive:false option. You can also specify explicit sizes via fig-width andfig-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 format

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

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 andgitLab natively support rendering Mermaid diagrams from code.

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

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

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

Valid values for mermaid-format include js,png,andsvg,

Mermaid Themes

The follow sections is describe describe the way in which you can control the color theme of mermaid diagram :

• Using the current document theme.
• Using one of Mermaid ’s own color theme via a yaml option .
• Using SCSS andCSS variables.

Default Colors for Mermaid diagram

If you use Quarto’s bootswatch built-in themes,including the default theme,ora custom theme that uses the same SCSS variables,your Mermaid diagrams will automatically follow your theme.

The following examples demonstrate this with a few of Quarto’s built-in bootswatch themes.

You can read more about the correspondence between Bootstrap’s SCSS variables andQuarto’s Mermaid SCSS variables,andhow to change it,below in Customizing the Mermaid Theme.

Using Mermaid’s Built-in Themes

If you want to use Mermaid’s own themes,you can do so by configuring the mermaid option in your YAML front matter:

format:
  html:
    mermaid:
      theme: forest

The available themes is are from mermaid are :default,dark,forest,andneutral.

Customizing the Mermaid Theme

Quarto provides its own Mermaid SCSS andCSS variables that can be overwritten to allow some customization of the diagram theme. The SCSS variables,together with their default values,are:

$ mermaid - bg - color:$body-bg;
$mermaid-edge-color:$secondary;
$mermaid-node-fg-color:$ body - color;
$mermaid-fg-color:$ body - color;
$mermaid-fg-color--lighter:lighten ($ body - color, 10%);
$mermaid-fg-color--lightest:lighten ($ body - color, 20%);
$ mermaid - font - family:$font-family-sans-serif;
$mermaid-label-bg-color:$body-bg;
$mermaid-label-fg-color:$primary;
$ mermaid - node - bg - color:rgba ($primary, 0.1);
$mermaid-node-fg-color:$primary;

Their CSS variable counterparts are:

: root {
  --mermaid - bg - color: #{$mermaid - bg - color};
  --mermaid-edge-color: #{$mermaid-edge-color};
   --mermaid - node - fg - color:  # { $ mermaid - node - fg - color } ;
  --mermaid-fg-color: #{$mermaid-fg-color};
   --mermaid - fg - color -- light: #{$mermaid-fg-color--lighter};
   --mermaid - fg - color -- light:  # { $ mermaid - fg - color -- light } ;
  --mermaid-font-family: #{$ mermaid - font - family};
   --mermaid - label - bg - color:  # { $ mermaid - label - bg - color } ;
  --mermaid-label-fg-color: #{$mermaid-label-fg-color};
  --mermaid - node - bg - color: #{$ mermaid - node - bg - color};
   --mermaid - node - fg - color:  # { $ mermaid - node - fg - color } ;
}

For example,to provide a custom color for the background of the nodes you could add a custom CSS stylesheet containing:

: root {
  --mermaid - node - bg - color: #375a7f;
}

You can find the correspondence between Quarto’s variables andMermaid’s native CSS classes in Quarto’s source code in the file embed-mermaid.css.

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 printing to output formats like pdf ordocx,diagram rendering makes use of the Chrome orEdge web browser to create a high-quality PNg.

Quarto can automatically use an existing version of Chrome orEdge 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:

Quarto installs headless Chromium via Puppeteer. The bundled Chromium that Puppeteer installs may not work on Docker containers; please check the Puppeteer documentation as well as this article if you are attempting to install within Windows Subsystem for Linux (WSL).