Complete Guide to Markdown with Mermaid Diagrams#

This article demonstrates how to create various complex diagrams using Mermaid in Markdown documents, including flowcharts, sequence diagrams, Gantt charts, class diagrams, and state diagrams.

Flowchart Example#

Flowcharts are excellent for representing processes or algorithm steps.

1
graph TD
2
    A[Start] --> B{Condition Check}
3
    B -->|Yes| C[Process Step 1]
4
    B -->|No| D[Process Step 2]
5
    C --> E[Subprocess]
6
    D --> E
7
    subgraph E [Subprocess Details]
8
        E1[Substep 1] --> E2[Substep 2]
9
        E2 --> E3[Substep 3]
10
    end
11
    E --> F{Another Decision}
12
    F -->|Option 1| G[Result 1]
13
    F -->|Option 2| H[Result 2]
14
    F -->|Option 3| I[Result 3]
15
    G --> J[End]
16
    H --> J
17
    I --> J

Sequence Diagram Example#

Sequence diagrams show interactions between objects over time.

1
sequenceDiagram
2
    participant User
3
    participant WebApp
4
    participant Server
5
    participant Database
6

7
    User->>WebApp: Submit Login Request
8
    WebApp->>Server: Send Auth Request
9
    Server->>Database: Query User Credentials
10
    Database-->>Server: Return User Data
11
    Server-->>WebApp: Return Auth Result
12

13
    alt Auth Successful
14
        WebApp->>User: Show Welcome Page
15
        WebApp->>Server: Request User Data
16
        Server->>Database: Get User Preferences
17
        Database-->>Server: Return Preferences
18
        Server-->>WebApp: Return User Data
19
        WebApp->>User: Load Personalized Interface
20
    else Auth Failed
21
        WebApp->>User: Show Error Message
22
        WebApp->>User: Prompt Re-entry
23
    end

Gantt Chart Example#

Gantt charts are perfect for displaying project schedules and timelines.

1
gantt
2
    title Website Development Project Timeline
3
    dateFormat  YYYY-MM-DD
4
    axisFormat  %m/%d
5

6
    section Design Phase
7
    Requirements Analysis      :a1, 2023-10-01, 7d
8
    UI Design                 :a2, after a1, 10d
9
    Prototype Creation        :a3, after a2, 5d
10

11
    section Development Phase
12
    Frontend Development      :b1, 2023-10-20, 15d
13
    Backend Development       :b2, after a2, 18d
14
    Database Design           :b3, after a1, 12d
15

16
    section Testing Phase
17
    Unit Testing              :c1, after b1, 8d
18
    Integration Testing       :c2, after b2, 10d
19
    User Acceptance Testing   :c3, after c2, 7d
20

21
    section Deployment
22
    Production Deployment     :d1, after c3, 3d
23
    Launch                    :milestone, after d1, 0d

Class Diagram Example#

Class diagrams show the static structure of a system, including classes, attributes, methods, and their relationships.

1
classDiagram
2
    class User {
3
        +String username
4
        +String password
5
        +String email
6
        +Boolean active
7
        +login()
8
        +logout()
9
        +updateProfile()
10
    }
11

12
    class Article {
13
        +String title
14
        +String content
15
        +Date publishDate
16
        +Boolean published
17
        +publish()
18
        +edit()
19
        +delete()
20
    }
21

22
    class Comment {
23
        +String content
24
        +Date commentDate
25
        +addComment()
26
        +deleteComment()
27
    }
28

29
    class Category {
30
        +String name
31
        +String description
32
        +addArticle()
33
        +removeArticle()
34
    }
35

36
    User "1" -- "*" Article : writes
37
    User "1" -- "*" Comment : posts
38
    Article "1" -- "*" Comment : has
39
    Article "1" -- "*" Category : belongs to

State Diagram Example#

State diagrams show the sequence of states an object goes through during its life cycle.

1
stateDiagram-v2
2
    [*] --> Draft
3

4
    Draft --> UnderReview : submit
5
    UnderReview --> Draft : reject
6
    UnderReview --> Approved : approve
7
    Approved --> Published : publish
8
    Published --> Archived : archive
9
    Published --> Draft : retract
10

11
    state Published {
12
        [*] --> Active
13
        Active --> Hidden : temporarily hide
14
        Hidden --> Active : restore
15
        Active --> [*]
16
        Hidden --> [*]
17
    }
18

19
    Archived --> [*]

Pie Chart Example#

Pie charts are ideal for displaying proportions and percentage data.

1
pie title Website Traffic Sources Analysis
2
    "Search Engines" : 45.6
3
    "Direct Access" : 30.1
4
    "Social Media" : 15.3
5
    "Referral Links" : 6.4
6
    "Other Sources" : 2.6

Conclusion#

Mermaid is a powerful tool for creating various types of diagrams in Markdown documents. This article demonstrated how to use flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, and pie charts. These diagrams can help you express complex concepts, processes, and data structures more clearly.

To use Mermaid, simply specify the mermaid language in a code block and describe the diagram using concise text syntax. Mermaid will automatically convert these descriptions into beautiful visual diagrams.

Try using Mermaid diagrams in your next technical blog post or project documentation - they will make your content more professional and easier to understand!