tools-only Diagrams
Quarto natively supports Mermaid and Graphviz diagrams, rendering them automatically across output formats.
Mermaid Diagrams
Mermaid is a JavaScript-based diagramming tool using text definitions.
Basic Syntax
```{mermaid}
flowchart LR
A[Start] --> B[Process]
B --> C[End]
```
Flowcharts
```{mermaid}
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
```
Direction options: TB (top-bottom), TD (top-down), BT, RL, LR.
All standard Mermaid diagram types are supported: sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, etc. Use standard Mermaid syntax inside {mermaid} code cells.
Mermaid Cell Options
Use %%| for options:
```{mermaid}
%%| label: fig-flowchart
%%| fig-cap: "Process flowchart."
flowchart LR
A --> B --> C
```
Common Options
| Option | Description | Example |
|---|---|---|
label |
Cross-reference ID | fig-diagram |
fig-cap |
Caption | "My diagram." |
fig-width |
Width | 6 (inches) |
fig-height |
Height | 4 (inches) |
fig-responsive |
Responsive sizing | true, false |
External File
```{mermaid}
%%| file: diagram.mmd
```
Graphviz/DOT Diagrams
Graphviz uses DOT language for graph descriptions.
Basic Syntax
```{dot}
digraph G {
A -> B -> C;
B -> D;
}
```
Use digraph for directed graphs, graph for undirected. Standard DOT features (subgraphs, node styling, rank direction) all work.
Graphviz Cell Options
Use //| for options:
```{dot}
//| label: fig-graph
//| fig-cap: "Network diagram."
digraph {
A -> B -> C;
}
```
External File
```{dot}
//| file: network.dot
```
Cross-Referencing Diagrams
Both Mermaid and Graphviz diagrams can be cross-referenced:
```{mermaid}
%%| label: fig-process
%%| fig-cap: "The data processing workflow."
flowchart LR
Input --> Process --> Output
```
See @fig-process for the workflow.
Sizing
Use %%| fig-width and %%| fig-height cell options. Diagrams are responsive by default in HTML; disable with %%| fig-responsive: false.
Theming
Mermaid Themes
Configure Mermaid theming using a YAML block inside the code cell:
```{mermaid}
---
config:
theme: forest
---
flowchart LR
A --> B
```
Available themes: default, forest, dark, neutral, base.
Custom Theme Variables
```{mermaid}
---
config:
theme: base
themeVariables:
primaryColor: "#f0f0f0"
primaryBorderColor: "#333"
fontFamily: "Fira Code, monospace"
---
flowchart LR
A --> B
```
Theming and Render Format
When using mermaid-format: js (the default for HTML), Quarto controls theming and may override custom theme configurations.
The YAML config block inside the Mermaid cell might appear to have no effect.
To ensure custom theming works:
- Use native Quarto theming options in document YAML.
- Change to
mermaid-format: svgormermaid-format: png.
format:
html:
mermaid:
theme: forest
Or use a different render format:
format:
html:
mermaid-format: svg
With svg or png format, the YAML config block inside Mermaid cells will be respected.
CSS Customization
For additional styling in HTML:
:root {
--mermaid-font-family: "Fira Code", monospace;
}
Graphviz Styling
Use DOT attributes:
```{dot}
digraph {
bgcolor="transparent";
node [fontname="Helvetica", fontsize=12];
edge [color=gray];
A -> B;
}
```
Rendering
HTML Output
Diagrams rendered with JavaScript (Mermaid) or as SVG (Graphviz).
PDF/DOCX Output
Rendered as images using Chrome/Chromium.
Requires Chrome or Edge installed, or set:
mermaid:
puppeteer:
executablePath: /path/to/chrome
Diagram in Figures
Combine with figure elements:
::: {#fig-workflow}
```{mermaid}
flowchart TD
A --> B --> C
```
Complete workflow diagram.
:::
Tips
Complex Diagrams
For complex diagrams, use external files:
```{mermaid}
%%| file: complex-diagram.mmd
%%| fig-cap: "Complex system architecture."
```
Accessibility
Add alt text:
```{mermaid}
%%| fig-alt: "Flowchart showing three sequential steps."
flowchart LR
A --> B --> C
```