---
title: "Diagrams"
guide-section: "Site Content"
bread-crumbs: false
tags: [Content, Multimedia]
versions: ">=0.2"
---

# 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:

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

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:

```{mermaid}
graph TD
    A[great-docs init] --> B[Configure great-docs.yml]
    B --> C[Write docstrings]
    C --> D[great-docs build]
    D --> E{Preview OK?}
    E -->|Yes| F[Deploy to GitHub Pages]
    E -->|No| C
```

### Flowchart Node Shapes

Mermaid supports various node shapes:

```{mermaid}
graph LR
    A[Rectangle] --> B(Rounded)
    B --> C{Diamond}
    C --> D([Stadium])
    D --> E[[Subroutine]]
    E --> F[(Database)]
```

## 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:

```{mermaid}
sequenceDiagram
    participant User
    participant CLI
    participant Core
    participant Quarto

    User->>CLI: great-docs build
    CLI->>Core: GreatDocs.build()
    Core->>Core: Parse docstrings
    Core->>Core: Generate .qmd files
    Core->>Quarto: quarto render
    Quarto-->>Core: HTML output
    Core-->>CLI: Build complete
    CLI-->>User: Site ready in great-docs/_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:

```{mermaid}
classDiagram
    class GreatDocs {
        +project_root: Path
        +config: Config
        +install()
        +build()
        +preview()
    }

    class Config {
        +package_name: str
        +exclude: list
        +logo: dict
        +load()
        +save()
    }

    GreatDocs --> Config : uses
```

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:

```{mermaid}
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Accept
    Review --> Draft: Request changes
    Approved --> Published: Deploy
    Published --> [*]
```

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

## Gantt Charts

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

```{mermaid}
gantt
    title Documentation Release Schedule
    dateFormat YYYY-MM-DD
    section Phase 1
        API Documentation    :done, api, 2024-01-01, 2024-01-15
        User Guide          :done, guide, 2024-01-10, 2024-01-25
    section Phase 2
        CLI Reference       :active, cli, 2024-01-20, 2024-02-05
        Deployment Guide    :deploy, 2024-02-01, 2024-02-10
```

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

## Pie Charts

Pie charts provide a quick visual summary of proportions:

```{mermaid}
pie title Documentation Coverage
    "API Reference" : 45
    "User Guide" : 30
    "Recipes" : 15
    "CLI Docs" : 10
```

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:

```{mermaid}
graph LR
    A[Parse Config] --> B[Discover Exports]
    B --> C[Generate Pages]
    C --> D[Render HTML]
```

### 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:

```{mermaid}
graph TD
    subgraph Build Process
        A[Parse] --> B[Generate]
        B --> C[Render]
    end
    subgraph Deploy
        D[Upload] --> E[Verify]
    end
    C --> D
```

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.qmd) covers other content building blocks like callouts,
tabsets, and code blocks
- [Videos](videos.qmd) covers embedding YouTube, Vimeo, and Loom content
- [Cross-Referencing](cross-referencing.qmd) explains how to link diagram pages to API reference
items
- [Theming & Appearance](theming.qmd) explains how diagrams inherit your site's color scheme
