Creating Organizational Charts with Mermaid#

Organizational charts are essential for visualizing company structures, team hierarchies, and reporting relationships. Mermaid provides a powerful, text-based approach to creating these diagrams that can be easily maintained, version-controlled, and integrated into documentation systems.

This guide demonstrates how to create comprehensive organizational charts using Mermaid syntax, from simple team structures to complex enterprise hierarchies.

Table of Contents#

Introduction to Mermaid#

Mermaid is a diagramming and charting tool that uses markdown-inspired syntax to create diagrams dynamically. It’s particularly useful for:

Documentation: Embedding charts directly in markdown files
Version Control: Text-based diagrams that track changes easily
Automation: Generating charts programmatically
Integration: Working seamlessly with platforms like GitHub, GitLab, and documentation sites

Basic Organizational Chart Structure#

Simple Hierarchy Example#

1
graph TD
2
    CEO["Chief Executive Officer"]
3
    CTO["Chief Technology Officer"]
4
    CFO["Chief Financial Officer"]
5

6
    CEO --> CTO
7
    CEO --> CFO

This creates a basic three-level hierarchy showing the CEO at the top with two direct reports.

Department-Level Organization#

1
graph TD
2
    CEO["Chief Executive Officer"]
3
    CTO["Chief Technology Officer"]
4
    CFO["Chief Financial Officer"]
5
    COO["Chief Operating Officer"]
6

7
    DevLead["Development Team Lead"]
8
    QALead["QA Team Lead"]
9
    DevOpsLead["DevOps Team Lead"]
10

11
    CEO --> CTO
12
    CEO --> CFO
13
    CEO --> COO
14

15
    CTO --> DevLead
16
    CTO --> QALead
17
    CTO --> DevOpsLead

Enterprise-Level Organizational Chart#

Here’s a comprehensive example of a complete enterprise organizational structure:

1
graph TD
2
    CEO["Chief Executive Officer"]
3
    COO["Chief Operating Officer"]
4
    CTO["Chief Technology Officer"]
5
    CFO["Chief Financial Officer"]
6
    CISO["Chief Information Security Officer"]
7

8
    PM["Project Manager"]
9
    Arch["Lead Architect"]
10
    SecArch["Security Architect"]
11

12
    DevLead["Development Team Lead"]
13
    Dev1["Senior Developer"]
14
    Dev2["Mid-level Developer"]
15
    Dev3["Junior Developer"]
16

17
    QA["Quality Assurance Lead"]
18
    QA1["QA Engineer"]
19
    QA2["QA Tester"]
20

21
    DevOpsLead["DevOps Team Lead"]
22
    DevOps1["DevOps Engineer"]
23
    DevOps2["System Administrator"]
24

25
    UXLead["UX/UI Lead Designer"]
26
    UX1["UX Researcher"]
27
    UX2["UI Designer"]
28

29
    SecAnalystLead["Security Analysis Lead"]
30
    SecAnalyst1["Security Analyst"]
31
    SecAnalyst2["Incident Responder"]
32

33
    SecEngLead["Security Engineering Lead"]
34
    SecEng1["Security Engineer"]
35
    SecEng2["Penetration Tester"]
36

37
    CommsLead["Communications Lead"]
38
    Comms1["Technical Writer"]
39
    Comms2["Community Manager"]
40

41
    Legal["Legal Advisor"]
42
    HR["Human Resources Manager"]
43
    FinAnalyst["Financial Analyst"]
44

45
    SalesLead["Sales Director"]
46
    Sales1["Account Manager"]
47
    Sales2["Sales Representative"]
48

49
    CustSuppLead["Customer Support Lead"]
50
    CustSupp1["Support Specialist"]
51
    CustSupp2["Support Technician"]
52

53
    CEO -->|Oversees| COO
54
    CEO -->|Oversees| CTO
55
    CEO -->|Oversees| CFO
56
    CEO -->|Oversees| CISO
57

58
    COO -->|Manages| PM
59
    CTO -->|Leads| Arch
60
    Arch -->|Collaborates with| SecArch
61
    Arch -->|Supervises| DevLead
62

63
    DevLead -->|Guides| Dev1
64
    DevLead -->|Guides| Dev2
65
    DevLead -->|Guides| Dev3
66

67
    PM -->|Coordinates| QA
68
    QA -->|Oversees| QA1
69
    QA -->|Oversees| QA2
70

71
    CTO -->|Manages| DevOpsLead
72
    DevOpsLead -->|Supervises| DevOps1
73
    DevOpsLead -->|Supervises| DevOps2
74

75
    PM -->|Works with| UXLead
76
    UXLead -->|Directs| UX1
77
    UXLead -->|Directs| UX2
78

79
    CISO -->|Heads| SecAnalystLead
80
    SecAnalystLead -->|Manages| SecAnalyst1
81
    SecAnalystLead -->|Manages| SecAnalyst2
82

83
    CISO -->|Oversees| SecEngLead
84
    SecEngLead -->|Leads| SecEng1
85
    SecEngLead -->|Leads| SecEng2
86

87
    COO -->|Oversees| CommsLead
88
    CommsLead -->|Manages| Comms1
89
    CommsLead -->|Manages| Comms2
90

91
    COO -->|Supervises| Legal
92
    COO -->|Supervises| HR
93

94
    CFO -->|Manages| FinAnalyst
95
    CFO -->|Oversees| SalesLead
96
    SalesLead -->|Supervises| Sales1
97
    SalesLead -->|Supervises| Sales2
98

99
    COO -->|Oversees| CustSuppLead
100
    CustSuppLead -->|Manages| CustSupp1
101
    CustSuppLead -->|Manages| CustSupp2

Advanced Mermaid Features for Org Charts#

Styling and Customization#

Adding Colors and Styles#

1
graph TD
2
    CEO["Chief Executive Officer"]
3
    CTO["Chief Technology Officer"]
4
    CFO["Chief Financial Officer"]
5

6
    CEO --> CTO
7
    CEO --> CFO
8

9
    classDef executive fill:#ff9999,stroke:#333,stroke-width:4px
10
    classDef management fill:#99ccff,stroke:#333,stroke-width:2px
11

12
    class CEO executive
13
    class CTO,CFO management

Custom Node Shapes#

1
graph TD
2
    CEO("Chief Executive Officer")
3
    CTO["Chief Technology Officer"]
4
    CFO{{"Chief Financial Officer"}}
5
    COO[("Chief Operating Officer")]
6

7
    CEO --> CTO
8
    CEO --> CFO
9
    CEO --> COO

Different Chart Orientations#

Left-to-Right Hierarchy#

1
graph LR
2
    CEO["CEO"] --> CTO["CTO"]
3
    CEO --> CFO["CFO"]
4
    CTO --> DevLead["Dev Lead"]
5
    CTO --> QALead["QA Lead"]

Top-Down with Subgraphs#

1
graph TD
2
    subgraph "Executive Team"
3
        CEO["Chief Executive Officer"]
4
        COO["Chief Operating Officer"]
5
        CTO["Chief Technology Officer"]
6
        CFO["Chief Financial Officer"]
7
    end
8

9
    subgraph "Technology Division"
10
        Arch["Lead Architect"]
11
        DevLead["Development Lead"]
12
        QALead["QA Lead"]
13
    end
14

15
    subgraph "Development Team"
16
        Dev1["Senior Developer"]
17
        Dev2["Mid-level Developer"]
18
        Dev3["Junior Developer"]
19
    end
20

21
    CEO --> COO
22
    CEO --> CTO
23
    CEO --> CFO
24
    CTO --> Arch
25
    CTO --> DevLead
26
    CTO --> QALead
27
    DevLead --> Dev1
28
    DevLead --> Dev2
29
    DevLead --> Dev3

Practical Implementation Examples#

Technology Team Structure#

1
graph TD
2
    CTO["Chief Technology Officer<br/>Strategic Technology Leadership"]
3

4
    subgraph "Architecture Team"
5
        SolArch["Solutions Architect"]
6
        EntArch["Enterprise Architect"]
7
        SecArch["Security Architect"]
8
    end
9

10
    subgraph "Development Teams"
11
        FELead["Frontend Team Lead"]
12
        BELead["Backend Team Lead"]
13
        MobLead["Mobile Team Lead"]
14

15
        FEDev1["Senior Frontend Developer"]
16
        FEDev2["Frontend Developer"]
17

18
        BEDev1["Senior Backend Developer"]
19
        BEDev2["Backend Developer"]
20

21
        MobDev1["Senior Mobile Developer"]
22
        MobDev2["Mobile Developer"]
23
    end
24

25
    subgraph "Quality & Operations"
26
        QALead["QA Lead"]
27
        DevOpsLead["DevOps Lead"]
28

29
        QAEng["QA Engineer"]
30
        QATest["QA Tester"]
31

32
        DevOpsEng["DevOps Engineer"]
33
        SysAdmin["System Administrator"]
34
    end
35

36
    CTO --> SolArch
37
    CTO --> EntArch
38
    CTO --> SecArch
39

40
    CTO --> FELead
41
    CTO --> BELead
42
    CTO --> MobLead
43
    CTO --> QALead
44
    CTO --> DevOpsLead
45

46
    FELead --> FEDev1
47
    FELead --> FEDev2
48

49
    BELead --> BEDev1
50
    BELead --> BEDev2
51

52
    MobLead --> MobDev1
53
    MobLead --> MobDev2
54

55
    QALead --> QAEng
56
    QALead --> QATest
57

58
    DevOpsLead --> DevOpsEng
59
    DevOpsLead --> SysAdmin
60

61
    classDef cto fill:#ff6b6b,stroke:#333,stroke-width:3px,color:#fff
62
    classDef lead fill:#4ecdc4,stroke:#333,stroke-width:2px,color:#fff
63
    classDef senior fill:#45b7d1,stroke:#333,stroke-width:2px,color:#fff
64
    classDef regular fill:#96ceb4,stroke:#333,stroke-width:1px
65

66
    class CTO cto
67
    class SolArch,EntArch,SecArch,FELead,BELead,MobLead,QALead,DevOpsLead lead
68
    class FEDev1,BEDev1,MobDev1 senior
69
    class FEDev2,BEDev2,MobDev2,QAEng,QATest,DevOpsEng,SysAdmin regular

Security Team Organization#

1
graph TD
2
    CISO["Chief Information Security Officer<br/>Security Strategy & Governance"]
3

4
    subgraph "Security Operations"
5
        SOCLead["SOC Lead"]
6
        SOCAnalyst1["Senior SOC Analyst"]
7
        SOCAnalyst2["SOC Analyst"]
8
        IncidentResp["Incident Response Specialist"]
9
    end
10

11
    subgraph "Security Engineering"
12
        SecEngLead["Security Engineering Lead"]
13
        SecEng1["Senior Security Engineer"]
14
        SecEng2["Security Engineer"]
15
        PenTester["Penetration Tester"]
16
    end
17

18
    subgraph "Governance & Compliance"
19
        CompLead["Compliance Lead"]
20
        RiskAnalyst["Risk Analyst"]
21
        PolicyAnalyst["Policy Analyst"]
22
    end
23

24
    subgraph "Identity & Access"
25
        IAMLead["IAM Lead"]
26
        IAMEng["IAM Engineer"]
27
        PrivAccess["Privileged Access Specialist"]
28
    end
29

30
    CISO --> SOCLead
31
    CISO --> SecEngLead
32
    CISO --> CompLead
33
    CISO --> IAMLead
34

35
    SOCLead --> SOCAnalyst1
36
    SOCLead --> SOCAnalyst2
37
    SOCLead --> IncidentResp
38

39
    SecEngLead --> SecEng1
40
    SecEngLead --> SecEng2
41
    SecEngLead --> PenTester
42

43
    CompLead --> RiskAnalyst
44
    CompLead --> PolicyAnalyst
45

46
    IAMLead --> IAMEng
47
    IAMLead --> PrivAccess
48

49
    classDef ciso fill:#dc3545,stroke:#333,stroke-width:3px,color:#fff
50
    classDef lead fill:#fd7e14,stroke:#333,stroke-width:2px,color:#fff
51
    classDef senior fill:#ffc107,stroke:#333,stroke-width:2px
52
    classDef specialist fill:#28a745,stroke:#333,stroke-width:1px,color:#fff
53

54
    class CISO ciso
55
    class SOCLead,SecEngLead,CompLead,IAMLead lead
56
    class SOCAnalyst1,SecEng1 senior
57
    class SOCAnalyst2,IncidentResp,SecEng2,PenTester,RiskAnalyst,PolicyAnalyst,IAMEng,PrivAccess specialist

Integration with Documentation Systems#

GitHub/GitLab Integration#

Mermaid diagrams can be embedded directly in GitHub and GitLab markdown files:

1
```mermaid
2
graph TD
3
    CEO["Chief Executive Officer"]
4
    CTO["Chief Technology Officer"]
5
    CFO["Chief Financial Officer"]
6

7
    CEO --> CTO
8
    CEO --> CFO
9
```

Documentation Platforms#

Gitiles Integration#

1
<div class="mermaid">
2
  graph TD CEO["Chief Executive Officer"] CTO["Chief Technology Officer"]
3
  CFO["Chief Financial Officer"] CEO --> CTO CEO --> CFO
4
</div>

Confluence Integration#

Use the Mermaid macro in Confluence:

1
{mermaid}
2
graph TD
3
    CEO["Chief Executive Officer"]
4
    CTO["Chief Technology Officer"]
5
    CFO["Chief Financial Officer"]
6

7
    CEO --> CTO
8
    CEO --> CFO
9
{mermaid}

Best Practices for Organizational Charts#

Design Principles#

Clarity: Use clear, descriptive titles for roles
Consistency: Maintain consistent styling throughout
Hierarchy: Make reporting relationships obvious
Readability: Avoid overcrowding with too many connections

Maintenance Tips#

Version Control#

1
name: Update Org Chart
2
on:
3
  push:
4
    paths:
5
      - "docs/org-chart.mmd"
6
jobs:
7
  generate:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v2
11
      - name: Generate SVG
12
        uses: mermaidjs/mermaid-cli-action@v1
13
        with:
14
          files: "docs/org-chart.mmd"

Automated Updates#

1
const fs = require("fs");
2
const employees = require("./employees.json");
3

4
function generateOrgChart(employees) {
5
  let mermaidCode = "graph TD\n";
6

7
  employees.forEach(emp => {
8
    if (emp.manager) {
9
      mermaidCode += `    ${emp.manager}["${emp.managerTitle}"] --> ${emp.id}["${emp.title}"]\n`;
10
    }
11
  });
12

13
  return mermaidCode;
14
}
15

16
const chart = generateOrgChart(employees);
17
fs.writeFileSync("org-chart.mmd", chart);

Accessibility Considerations#

Alt Text and Descriptions#

1
graph TD
2
    CEO["Chief Executive Officer<br/>Responsible for overall strategy"]
3
    CTO["Chief Technology Officer<br/>Leads technology initiatives"]
4
    CFO["Chief Financial Officer<br/>Manages financial operations"]
5

6
    CEO --> CTO
7
    CEO --> CFO

1
graph TD
2
    CEO["Chief Executive Officer"]
3
    CTO["Chief Technology Officer"]
4
    CFO["Chief Financial Officer"]
5

6
    CEO --> CTO
7
    CEO --> CFO
8

9
    classDef executive fill:#2166ac,stroke:#333,stroke-width:2px,color:#fff
10
    classDef management fill:#762a83,stroke:#333,stroke-width:2px,color:#fff
11

12
    class CEO executive
13
    class CTO,CFO management

Advanced Use Cases#

Matrix Organizations#

1
graph TD
2
    CEO["Chief Executive Officer"]
3

4
    subgraph "Functional Managers"
5
        CTO["Chief Technology Officer"]
6
        CPO["Chief Product Officer"]
7
        CMO["Chief Marketing Officer"]
8
    end
9

10
    subgraph "Project Teams"
11
        PM1["Project Manager A"]
12
        PM2["Project Manager B"]
13
    end
14

15
    subgraph "Resources"
16
        Dev1["Developer 1"]
17
        Dev2["Developer 2"]
18
        Designer["Designer"]
19
        Marketer["Marketing Specialist"]
20
    end
21

22
    CEO --> CTO
23
    CEO --> CPO
24
    CEO --> CMO
25

26
    CTO -.-> Dev1
27
    CTO -.-> Dev2
28
    CPO -.-> Designer
29
    CMO -.-> Marketer
30

31
    PM1 --> Dev1
32
    PM1 --> Designer
33

34
    PM2 --> Dev2
35
    PM2 --> Marketer
36

37
    classDef dotted stroke-dasharray: 5 5

Cross-Functional Teams#

1
graph TD
2
    subgraph "Product Team Alpha"
3
        PO1["Product Owner"]
4
        SM1["Scrum Master"]
5
        Dev1["Developer"]
6
        QA1["QA Engineer"]
7
        UX1["UX Designer"]
8
    end
9

10
    subgraph "Product Team Beta"
11
        PO2["Product Owner"]
12
        SM2["Scrum Master"]
13
        Dev2["Developer"]
14
        QA2["QA Engineer"]
15
        UX2["UX Designer"]
16
    end
17

18
    subgraph "Shared Services"
19
        DevOps["DevOps Engineer"]
20
        SecEng["Security Engineer"]
21
        DataEng["Data Engineer"]
22
    end
23

24
    PO1 --> SM1
25
    SM1 --> Dev1
26
    SM1 --> QA1
27
    SM1 --> UX1
28

29
    PO2 --> SM2
30
    SM2 --> Dev2
31
    SM2 --> QA2
32
    SM2 --> UX2
33

34
    Dev1 -.-> DevOps
35
    Dev2 -.-> DevOps
36
    Dev1 -.-> SecEng
37
    Dev2 -.-> SecEng
38
    QA1 -.-> DataEng
39
    QA2 -.-> DataEng

Conclusion#

Mermaid provides a powerful and flexible way to create organizational charts that are:

Maintainable: Text-based format that’s easy to update
Version-controlled: Track changes over time
Scalable: Handle everything from small teams to enterprise structures
Integrable: Work seamlessly with documentation platforms

By following the patterns and best practices outlined in this guide, you can create professional organizational charts that effectively communicate your company’s structure and help stakeholders understand reporting relationships and team dynamics.

Whether you’re documenting a small startup or a large enterprise, Mermaid’s syntax provides the flexibility to represent complex organizational structures while maintaining clarity and readability.