Mermaid is a powerful tool that enables the creation of diagrams using text and code. Its simple syntax and seamless integration with Markdown make it a great choice for technical documentation, project planning, and data visualization.
- Simple Syntax: Easy to learn and write, making it accessible for everyone.
- Supports Various Diagrams: Including flowcharts, sequence diagrams, Gantt charts, class diagrams, and pie charts.
- Integration with Markdown: Embed diagrams directly in Markdown files, perfect for documentation on platforms like GitHub and GitLab.
Mermaid uses a straightforward, human-readable syntax that makes it easy to create diagrams without extensive training or experience. The text-based format ensures that diagrams can be easily read and understood by both humans and machines.
Mermaid supports a wide range of diagrams, including:
- Flowcharts: Visualize processes and workflows.
- Sequence Diagrams: Show interactions between entities over time.
- Gantt Charts: Project planning and scheduling.
- Class Diagrams: Model the structure of object-oriented systems.
- Pie Charts: Represent data distribution.
- Mind Maps: Organize ideas and brainstorm concepts visually with hierarchical branches.
- State Diagrams: Represent states and transitions in a system.
- Entity Relationship Diagrams (ERD): Model the relationships between entities in a database.
- User Journey Diagrams: Visualize user interactions and experiences.
- Git Graphs: Visualize Git branches and commits.
One of the standout features of Mermaid is its seamless integration with Markdown. This allows you to embed diagrams directly into Markdown files, making it easier to include visual aids in documentation, README files, and other text-based formats.
Below is an example of a simple flowchart for user authentication in a web application:
Source:
graph TD
A[Start] --> B[User Enters Credentials]
B --> C{Credentials Valid?}
C -- Yes --> D[Grant Access]
C -- No --> E[Manual Review Required]
D --> F[End]
%% Sub-workflow for Manual Review
E --> E1[Notify Admin]
E1 --> E2[Admin Reviews Request]
E2 --> E3{Approve or Deny?}
E3 -- Approve --> E4[Grant Temporary Access]
E3 -- Deny --> E5[Send Rejection Notice]
E4 --> F[End]
E5 --> F[End]
graph TD
A[Start] --> B[User Enters Credentials]
B --> C{Credentials Valid?}
C -- Yes --> D[Grant Access]
C -- No --> E[Manual Review Required]
D --> F[End]
%% Sub-workflow for Manual Review
E --> E1[Notify Admin]
E1 --> E2[Admin Reviews Request]
E2 --> E3{Approve or Deny?}
E3 -- Approve --> E4[Grant Temporary Access]
E3 -- Deny --> E5[Send Rejection Notice]
E4 --> F[End]
E5 --> F[End]
Here’s a sequence diagram showing interactions between different components of a system:
Source:
sequenceDiagram
participant User
participant Frontend
participant Backend
participant Database
User->>Frontend: Enter Credentials
Frontend->>Backend: Send Credentials
Backend->>Database: Query User
Database-->>Backend: Return User Data
Backend-->>Frontend: Return Authentication Status
Frontend-->>User: Display Status
sequenceDiagram
participant User
participant Frontend
participant Backend
participant Database
User->>Frontend: Enter Credentials
Frontend->>Backend: Send Credentials
Backend->>Database: Query User
Database-->>Backend: Return User Data
Backend-->>Frontend: Return Authentication Status
Frontend-->>User: Display Status
Here’s a Gantt chart for a simple project plan:
Source:
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Section
Task A :a1, 2024-08-01, 2024-08-10
Task B :after a1 , 10d
Task C :2024-08-11 , 10d
gantt
title Project Plan
dateFormat YYYY-MM-DD
section Section
Task A :a1, 2024-08-01, 2024-08-10
Task B :after a1 , 10d
Task C :2024-08-11 , 10d
These diagrams illustrate the relationships between classes in an object-oriented system.
Source:
classDiagram
class Person {
+String name
+int age
+void introduce()
}
class Student {
+int studentId
+void study()
}
class Teacher {
+int employeeId
+void teach()
}
class Course {
+String courseName
+void startCourse()
}
class Department {
+String deptName
+void manage()
}
Person <|-- Student
Person <|-- Teacher
Teacher "1" *-- "many" Course : teaches
Student "many" --|> "1" Course : enrolls
Department "1" o-- "many" Teacher : employs
classDiagram
class Person {
+String name
+int age
+void introduce()
}
class Student {
+int studentId
+void study()
}
class Teacher {
+int employeeId
+void teach()
}
class Course {
+String courseName
+void startCourse()
}
class Department {
+String deptName
+void manage()
}
Person <|-- Student
Person <|-- Teacher
Teacher "1" *-- "many" Course : teaches
Student "many" --|> "1" Course : enrolls
Department "1" o-- "many" Teacher : employs
Source:
pie
title Project Distribution
"Development" : 50
"Testing" : 20
"Documentation" : 15
"Deployment" : 10
"Maintenance" : 5pie
title Project Distribution
"Development" : 50
"Testing" : 20
"Documentation" : 15
"Deployment" : 10
"Maintenance" : 5
Mind maps are great for brainstorming and organizing thoughts. Here’s an example:
Source:
mindmap
root((Root))
branch1((Branch 1))
subbranch1((Sub-branch 1.1))
subbranch2((Sub-branch 1.2))
branch2((Branch 2))
subbranch3((Sub-branch 2.1))
subbranch4((Sub-branch 2.2))
mindmap
root((Root))
branch1((Branch 1))
subbranch1((Sub-branch 1.1))
subbranch2((Sub-branch 1.2))
branch2((Branch 2))
subbranch3((Sub-branch 2.1))
subbranch4((Sub-branch 2.2))
State diagrams are useful for representing states and transitions in a system. Here’s an example:
Source:
stateDiagram-v2
[*] --> S1
S1 --> S2 : Event1
S2 --> S3 : Event2
S3 --> S1 : Event3
S1 --> [*]stateDiagram-v2
[*] --> S1
S1 --> S2 : Event1
S2 --> S3 : Event2
S3 --> S1 : Event3
S1 --> [*]
Source:
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
Source:
journey
title User Journey for Online Shopping
section Start
User: Goes to homepage: 5: User
section Browse
User: Searches for products: 5: User
User: Views product details: 3: User
User: Adds product to cart: 4: User
section Checkout
User: Proceeds to checkout: 5: User
User: Enters shipping information: 3: User
User: Enters payment information: 4: User
User: Confirms order: 5: User
section Post-Purchase
User: Receives order confirmation: 2: User
User: Receives shipment notification: 3: User
User: Receives product: 5: User
journey
title User Journey for Online Shopping
section Start
User: Goes to homepage: 5: User
section Browse
User: Searches for products: 5: User
User: Views product details: 3: User
User: Adds product to cart: 4: User
section Checkout
User: Proceeds to checkout: 5: User
User: Enters shipping information: 3: User
User: Enters payment information: 4: User
User: Confirms order: 5: User
section Post-Purchase
User: Receives order confirmation: 2: User
User: Receives shipment notification: 3: User
User: Receives product: 5: User
Source:
gitGraph
commit id: "Initial commit" tag: "v1.0"
commit id: "Setup project structure"
branch develop
checkout develop
commit id: "Develop feature A"
commit id: "Develop feature B"
checkout main
commit id: "Hotfix on main" tag: "v1.0.1"
merge develop id: "Merge develop into main"
commit id: "Release v1.1" tag: "v1.1"
gitGraph
commit id: "Initial commit" tag: "v1.0"
commit id: "Setup project structure"
branch develop
checkout develop
commit id: "Develop feature A"
commit id: "Develop feature B"
checkout main
commit id: "Hotfix on main" tag: "v1.0.1"
merge develop id: "Merge develop into main"
commit id: "Release v1.1" tag: "v1.1"
- Official Documentation: Mermaid Documentation
- VSCode Extension: Mermaid Preview
- GitHub Integration: Mermaid diagrams can be rendered in GitHub-flavored Markdown.
- GitLab Integration: Mermaid diagrams can be embedded in GitLab Markdown.
Mermaid is a versatile and powerful tool for creating a wide range of diagrams using simple text-based syntax. Its integration with Markdown makes it an excellent choice for enhancing technical documentation and project planning. Start exploring Mermaid today and see how it can improve your workflow!