# Diagrams

Some concepts are hard to explain with words alone. Architecture diagrams, workflow charts, and sequence diagrams communicate structure and flow far more effectively than prose. But maintaining diagrams as image files is fragile: they go out of date, they're hard to diff in version control, and they require external tools to edit.

Great Docs supports [Mermaid](https://mermaid.js.org/) diagrams directly in your documentation. Mermaid renders diagrams from text definitions inside fenced code blocks, so your diagrams live alongside your prose in version control and update just as easily. You can create flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and pie charts without needing external image files.

Diagrams work seamlessly in both light and dark mode, automatically adapting their colors for readability.


# Basic Usage

To add a Mermaid diagram, use a fenced code block with `{mermaid}` as the language identifier:

```` markdown
```{mermaid}
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```
````

This renders as:


*\[Rich HTML output -- view on the documentation site\]*


The diagram is rendered at build time and embedded directly in the page. No JavaScript is needed on the reader's side.


# Flowcharts

Flowcharts are the most common diagram type in technical documentation. They're useful for documenting workflows, decision trees, or multi-step processes. Use `graph LR` for left-to-right flow or `graph TD` for top-down:


*\[Rich HTML output -- view on the documentation site\]*


## Flowchart Node Shapes

Mermaid supports various node shapes:


*\[Rich HTML output -- view on the documentation site\]*


# Sequence Diagrams

Sequence diagrams show how components interact over time. They're ideal for documenting API call flows, request/response cycles, or system interactions where the order of operations matters:


*\[Rich HTML output -- view on the documentation site\]*


The `participant` declarations control the column order. Solid arrows (`->>`) represent calls, and dashed arrows (`-->>`) represent returns.


# Class Diagrams

Class diagrams are perfect for documenting object-oriented code structures:


*\[Rich HTML output -- view on the documentation site\]*


Class diagrams support visibility modifiers (`+` public, `-` private, `#` protected) and relationship types (inheritance, composition, association).


# State Diagrams

State diagrams help document state machines, lifecycle stages, or any system where items transition between well-defined states:


*\[Rich HTML output -- view on the documentation site\]*


The `[*]` node represents the start and end states.


# Gantt Charts

Gantt charts are useful for documenting project timelines, release schedules, or migration plans:


*\[Rich HTML output -- view on the documentation site\]*


Tasks can be marked as `done`, `active`, or left unmarked for upcoming work.


# Pie Charts

Pie charts provide a quick visual summary of proportions:


*\[Rich HTML output -- view on the documentation site\]*


Values are automatically converted to percentages.


# Dark Mode Support

Readers who switch between light and dark mode should not have to squint at a bright white diagram on a dark background. Great Docs automatically adjusts Mermaid diagrams for dark mode by displaying them in a light background container, ensuring text and shapes remain clearly readable. No additional configuration is required.


# Tips for Better Diagrams

Mermaid diagrams are easy to create, but a few practices help keep them clear and maintainable.


## Keep Diagrams Focused

Each diagram should illustrate one concept. If a diagram becomes too complex, consider breaking it into multiple smaller diagrams.


## Use Descriptive Labels

Node labels should be self-explanatory. Use action verbs for process steps and clear nouns for entities:


*\[Rich HTML output -- view on the documentation site\]*


## Add Direction for Clarity

Choose the direction that best matches the flow you're documenting:

- `graph LR` (left to right): for processes, pipelines
- `graph TD` (top down): for hierarchies, decision trees
- `graph RL` (right to left): rarely used, but available
- `graph BT` (bottom to top): for build-up processes


## Use Subgraphs for Grouping

Group related nodes using subgraphs:


*\[Rich HTML output -- view on the documentation site\]*


For the complete Mermaid syntax reference, see the [Mermaid documentation](https://mermaid.js.org/intro/). Quarto also provides additional options for diagram sizing and placement in the [Quarto Diagrams guide](https://quarto.org/docs/authoring/diagrams.html).


# Next Steps

Mermaid diagrams let you visualize architecture, workflows, and relationships directly in your documentation. Because they're defined in text, they stay in version control, diff cleanly, and update alongside your prose.

- [Authoring QMD Files](authoring-qmd-files.md) covers other content building blocks like callouts, tabsets, and code blocks
- [Videos](videos.md) covers embedding YouTube, Vimeo, and Loom content
- [Cross-Referencing](cross-referencing.md) explains how to link diagram pages to API reference items
- [Theming & Appearance](theming.md) explains how diagrams inherit your site's color scheme