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 two text-based diagram languages, both authored directly in fenced code blocks so your diagrams live alongside your prose in version control and update just as easily:

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

D2 Diagrams

D2 (“Declarative Diagramming”) turns a concise text description into a polished diagram. Great Docs renders D2 blocks at build time using the d2 command-line tool, producing a self-contained SVG for each diagram.

Prerequisites

D2 rendering requires the d2 binary on your PATH. Install it once:

# macOS (Homebrew)
brew install d2

# or the official install script (macOS / Linux)
curl -fsSL https://d2lang.com/install.sh | sh -s --

See the D2 install guide for other platforms. If d2 is not installed, Great Docs leaves the code block untouched and prints a warning, so builds never fail because of a missing binary (they simply skip diagram rendering until d2 is available).

Basic Usage

To add a D2 diagram, use a fenced code block with {d2} as the language identifier:

```{d2}
Start -> Decision
Decision -> Action: Yes
Decision -> End: No
```

This renders as:

D2 diagram

D2 diagram

Connections use -> (or <->, <-, --), and text after a colon labels the connection. Declaring a shape is as simple as naming it.

Shapes and Containers

D2 supports a rich set of shapes and lets you nest related nodes inside containers using dot notation. Containers are ideal for grouping the pieces of a subsystem:

D2 diagram

D2 diagram

You can change any node’s shape with the shape keyword:

D2 diagram

D2 diagram

Sequence Diagrams

D2 renders sequence diagrams from the same syntax by setting shape: sequence_diagram. They’re ideal for documenting API call flows or request/response cycles where order matters:

D2 diagram

D2 diagram

Options

Fine-tune a diagram with #| option lines at the top of the block. These are stripped before the diagram is rendered:

Option Description Default
theme D2 theme id used for the light rendering 0
dark-theme D2 theme id used for the dark rendering 200
layout Layout engine (dagre, elk, or tala if installed) dagre
sketch true for a hand-drawn look false
pad Padding in pixels around the diagram 20
scale Scale factor for the rendered output auto

For example, a hand-drawn diagram with the ELK layout engine:

D2 diagram

D2 diagram

Run d2 themes to see the full catalog of light and dark theme ids.

Dark Mode Support

Readers who switch between light and dark mode should not have to squint at a bright diagram on a dark background. Because Great Docs renders a dedicated dark-theme SVG for every D2 diagram, dark mode gets a genuinely dark diagram. The switch happens instantly when the reader toggles the theme, with no additional configuration required.

Mermaid Diagrams

Mermaid is rendered in the reader’s browser and supports a broad set of diagram types. Great Docs pins Mermaid to its light theme and, in dark mode, presents each diagram inside a light background container so text and shapes stay clearly readable.

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]

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

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

Text-based diagrams are easy to create, but a few practices help keep them clear and maintainable (whether you use D2 or Mermaid).

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:

D2 diagram

D2 diagram

Choose a Direction that Matches the Flow

Both languages let you set a direction. In D2, add direction: right (or up, down, left); in Mermaid, use graph LR, graph TD, and so on. Pick the direction that best matches the process you’re documenting (left-to-right for pipelines, top-down for hierarchies and decision trees).

Next Steps

Text-based 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.