diagrams.qmd

---
title: "Diagrams"
aliases:
  - /docs/prerelease/1.3/mermaid.html
---

## Overview

Quarto has native support for embedding [Mermaid](https://mermaid-js.github.io/mermaid/#/) and [Graphviz](https://graphviz.org/) diagrams. This enables you to create flowcharts, sequence diagrams, state diagrams, gantt charts, and more using a plain text syntax inspired by markdown.

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

```{mermaid}
%%| echo: fenced
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 cells. Note that cell options are added with slightly different syntax: `%%|` for `{mermaid}`, and `//|` for `{dot}`. 


::: callout-note
For print output formats like `pdf` or `docx`, diagram rendering makes 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, you can install a lighter-weight version called Chrome Headless Shell (see [Chrome Install](#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.

Mermaid diagrams use `%%` as their comment syntax, and so cell options are declared using `%%|`. Cell options **must** be included 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}
%%| echo: fenced
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](#mermaid-formats) for additional details.

To learn more about using Mermaid, see the [Mermaid website](https://mermaid-js.github.io/mermaid/) or the [Mermaid book](https://www.amazon.com/Official-Guide-Mermaid-js-beautiful-flowcharts-dp-1801078025/dp/1801078025) (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.

Graphviz diagrams use `//` as their comment syntax, and so cell options are declared using `//|`. Cell options **must** be included directly beneath the start of the diagram code chunk.

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

```{dot}
//| echo: fenced
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](https://graphviz.org/), this list of simple [Graphiz Examples](https://renenyffenegger.ch/notes/tools/Graphviz/examples/index), or the [Graphviz Gallery](https://graphviz.org/gallery/).

## Authoring

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

1)  The [Mermaid Live Editor](https://mermaid.live/) is an online tool for editing and previewing Mermaid diagrams in real time.

2)  [Graphviz Online](https://dreampuf.github.io/GraphvizOnline/) provides a similar tool for editing Graphviz diagrams.

3)  [RStudio](https://www.rstudio.com/products/rstudio/download/) includes support for editing and previewing `.mmd` and `.dot` files (with help from the [DiagrammeR](https://rich-iannone.github.io/DiagrammeR/) package).

4)  The Quarto Extension for VS Code and Positron (available on both [OpenVSX](https://open-vsx.org/extension/quarto/quarto) and [Microsoft's marketplace](https://marketplace.visualstudio.com/items?itemName=quarto.quarto)) supports live preview of diagrams embedded in `.qmd` files and in `.mmd` and `.dot` files:

    ![](images/vscode-graphviz.gif){.border fig-alt="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"}

## Cross-References

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:

```{dot}
//| label: fig-simple
//| fig-cap: "This is a simple graphviz graph."
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;
}
```

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

```markdown
@fig-simple
```

{{< include _cross-reference-divs-diagram.qmd >}}

## File Include

You might find it more convenient to edit your diagram in a standalone `.dot` or `.mmd` 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
```

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

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}
%%| echo: fenced
%%| fig-width: 6.5
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
```

## Mermaid Formats {#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](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/) and [GitLab](https://docs.gitlab.com/ee/user/markdown.html#mermaid) 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](#chrome-install).

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

``` yaml
---
format:
  gfm:
    mermaid-format: png
---
```

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

::: callout-warning
## SVG Format Limitations with PDF Output through LaTeX

When rendering to LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues:

- **Requires installation:** `rsvg-convert` or `inkscape` must be available in your system PATH for Quarto to convert SVG to PDF to include in LaTeX.
- **Potential rendering issues:** Text clipping in diagrams with multi-line labels
- **Recommended:** Keep default `mermaid-format: png` for PDF output with LaTeX.

For more details, including installation instructions and Inkscape configuration, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images).
:::

## Mermaid Themes {#mermaid-theming}

{{< include _mermaid-theming.qmd >}}

## 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 {#chrome-install}

{{< prerelease-callout 1.9 >}}

For printing to output formats like `pdf` or `docx`, diagram rendering makes 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 installed, you can install Chrome Headless Shell for use by Quarto:

``` {.bash filename="Terminal"}
quarto install chrome-headless-shell
```

[Chrome Headless Shell](https://developer.chrome.com/blog/chrome-headless-shell) is a lightweight, headless-only browser from Google's [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) infrastructure. It has fewer system dependencies than full Chromium, making it a good fit for Docker containers and WSL environments.

::: callout-warning
## Chromium (Deprecated)

The `quarto install chromium` command is deprecated as of Quarto 1.9 and will be removed in a future release. It still works but displays a deprecation warning. To migrate to Chrome Headless Shell, run:

``` {.bash filename="Terminal"}
quarto uninstall chromium
quarto install chrome-headless-shell
```

The Puppeteer-bundled Chromium installed by the old command may not work in Docker or WSL — see [Puppeteer troubleshooting](https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#running-puppeteer-in-docker) for details. Chrome Headless Shell does not have these limitations and also supports arm64 Linux.
:::