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

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

This renders as:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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. Quarto also provides additional options for diagram sizing and placement in the Quarto Diagrams guide.

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.