Diagram examples

Each example shows its Mermaid source and rendered output. The source listing and diagram read the same file, so the text is directly reusable in a mermaid fence or directive. These examples exercise the bundled Pele renderer; they do not imply support for every Mermaid option.

For Sphinx authoring patterns, see reStructuredText examples and how to add diagrams. Styling recipes are in how to style diagrams.

Flowchart with frontmatter

Diagram frontmatter supplies a title, layout settings, font size, and a CSS variable.

---
title: Publishing
config:
  flowchart:
    nodeSpacing: 35
pele:
  autoDirection: false
  fontSize: 18
  cssVariables:
    --pele-accent: "#205ea6"
---
flowchart LR
    Draft --> Review --> Published

---
title: Publishing
config:
  flowchart:
    nodeSpacing: 35
pele:
  autoDirection: false
  fontSize: 18
  cssVariables:
    --pele-accent: "#205ea6"
---
flowchart LR
    Draft --> Review --> Published

Sequence diagram

A caption, named reference, accessible label, width, and zoom controls are attached by the Sphinx directive.

sequenceDiagram
    Client->>Server: GET /docs
    Server-->>Client: HTML

sequenceDiagram
    Client->>Server: GET /docs
    Server-->>Client: HTML

A request and response.

External file

The same UTF-8 file supplies the source listing and diagram. Sphinx tracks it as a build dependency.

flowchart TD
    Source[Mermaid source] --> Pele --> SVG

flowchart TD
    Source[Mermaid source] --> Pele --> SVG

Loaded from a Mermaid document.

Pie chart

A chart with two labeled slices.

pie title Tasks
    "Complete" : 8
    "Remaining" : 2

pie title Tasks
    "Complete" : 8
    "Remaining" : 2

Class diagram

Classes, members, and a composition relationship.

classDiagram
    class Document {
        +String title
        +render()
    }
    class Diagram {
        +String source
        +toSVG()
    }
    Document "1" *-- "many" Diagram : contains

classDiagram
    class Document {
        +String title
        +render()
    }
    class Diagram {
        +String source
        +toSVG()
    }
    Document "1" *-- "many" Diagram : contains

Entity relationship diagram

A documentation collection with pages and embedded diagrams.

erDiagram
    COLLECTION ||--o{ PAGE : contains
    PAGE ||--o{ DIAGRAM : embeds
    PAGE {
        string slug PK
        string title
    }
    DIAGRAM {
        string id PK
        string source
    }

erDiagram
    COLLECTION ||--o{ PAGE : contains
    PAGE ||--o{ DIAGRAM : embeds
    PAGE {
        string slug PK
        string title
    }
    DIAGRAM {
        string id PK
        string source
    }

State diagram

Transitions through a review cycle, including a return to the draft state.

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Draft : revise
    Review --> Published : approve
    Published --> [*]

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Draft : revise
    Review --> Published : approve
    Published --> [*]

Gantt chart

Fixed dates and a disabled today marker keep this example stable across builds.

gantt
    title Documentation work
    dateFormat YYYY-MM-DD
    todayMarker off
    section Writing
    Draft tutorial :done, draft, 2026-10-01, 3d
    Add examples :active, examples, after draft, 4d
    section Review
    Build and review :review, after examples, 2d

gantt
    title Documentation work
    dateFormat YYYY-MM-DD
    todayMarker off
    section Writing
    Draft tutorial :done, draft, 2026-10-01, 3d
    Add examples :active, examples, after draft, 4d
    section Review
    Build and review :review, after examples, 2d

User journey

Scores describe how a reader experiences each part of a documentation task.

journey
    title Add a diagram
    section Author
      Write Mermaid: 5: Writer
      Build docs: 4: Writer
    section Review
      Check rendering: 4: Reviewer
      Publish: 5: Writer, Reviewer

journey
    title Add a diagram
    section Author
      Write Mermaid: 5: Writer
      Build docs: 4: Writer
    section Review
      Check rendering: 4: Reviewer
      Publish: 5: Writer, Reviewer

Git graph

A documentation branch merged back into main.

gitGraph
    commit id: "Start"
    branch docs
    checkout docs
    commit id: "Add examples"
    checkout main
    merge docs
    commit id: "Publish"

gitGraph
    commit id: "Start"
    branch docs
    checkout docs
    commit id: "Add examples"
    checkout main
    merge docs
    commit id: "Publish"

Mind map

A hierarchy of documentation topics.

mindmap
    root((Documentation))
        Tutorial
            First diagram
        Guides
            Style diagrams
            Migrate
        Reference
            Options
            Examples

mindmap
    root((Documentation))
        Tutorial
            First diagram
        Guides
            Style diagrams
            Migrate
        Reference
            Options
            Examples

Timeline

Milestones grouped by month.

timeline
    title Documentation milestones
    October : Tutorial : Diagram gallery
    November : Reader feedback
    December : Reference review

timeline
    title Documentation milestones
    October : Tutorial : Diagram gallery
    November : Reader feedback
    December : Reference review

Quadrant chart

Work items positioned by effort and reader impact.

quadrantChart
    title Documentation priorities
    x-axis Low effort --> High effort
    y-axis Low impact --> High impact
    quadrant-1 Plan
    quadrant-2 Do first
    quadrant-3 Fit in
    quadrant-4 Reconsider
    Tutorial: [0.3, 0.9]
    Examples: [0.4, 0.8]
    New theme: [0.8, 0.3]

quadrantChart
    title Documentation priorities
    x-axis Low effort --> High effort
    y-axis Low impact --> High impact
    quadrant-1 Plan
    quadrant-2 Do first
    quadrant-3 Fit in
    quadrant-4 Reconsider
    Tutorial: [0.3, 0.9]
    Examples: [0.4, 0.8]
    New theme: [0.8, 0.3]

Sankey diagram

Values represent reader traffic between documentation sections.

sankey-beta
Home,Tutorial,40
Home,Reference,60
Tutorial,Examples,30
Reference,Examples,20

sankey-beta
Home,Tutorial,40
Home,Reference,60
Tutorial,Examples,30
Reference,Examples,20

XY chart

Bars show completed examples over four weeks.

xychart-beta
    title "Reviewed examples"
    x-axis [Week1, Week2, Week3, Week4]
    y-axis "Examples" 0 --> 20
    bar [4, 8, 12, 16]

xychart-beta
    title "Reviewed examples"
    x-axis [Week1, Week2, Week3, Week4]
    y-axis "Examples" 0 --> 20
    bar [4, 8, 12, 16]

Requirement diagram

A test element verifies a rendering requirement.

requirementDiagram
    requirement diagram_output {
        id: 1
        text: Diagrams render as SVG
        risk: low
        verifymethod: test
    }
    element browser_test {
        type: "test"
    }
    browser_test - verifies -> diagram_output

requirementDiagram
    requirement diagram_output {
        id: 1
        text: Diagrams render as SVG
        risk: low
        verifymethod: test
    }
    element browser_test {
        type: "test"
    }
    browser_test - verifies -> diagram_output

The sequence figure can be referenced as A request and response..