Hướng dẫn đầy đủ về sơ đồ Mermaid.js

Mermaid.js là gì?

Vì sao nên dùng Mermaid.js?

• Kiểm soát phiên bản: sơ đồ là tệp văn bản nên có thể theo dõi trong Git cùng với mã
• Cập nhật nhanh: thay đổi vài dòng văn bản thay vì vẽ lại toàn bộ sơ đồ
• Tính nhất quán: Mermaid tự động xử lý bố cục và kiểu dáng để đảm bảo sơ đồ nhất quán
• Không cần công cụ thiết kế: không cần Visio, Lucidchart hay các công cụ đắt tiền khác
• Tài liệu như mã: giữ sơ đồ trong cùng kho với tài liệu của bạn
• Đa nền tảng: chạy trên trình duyệt và Node.js, tích hợp với nhiều nền tảng
• Miễn phí và mã nguồn mở: không chi phí giấy phép, cộng đồng năng động
• Nhiều loại sơ đồ: hỗ trợ lưu đồ, sơ đồ tuần tự, sơ đồ lớp và hơn nữa

Các loại sơ đồ được hỗ trợ

Mermaid hỗ trợ nhiều loại sơ đồ để đáp ứng các nhu cầu tài liệu khác nhau:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[Alternative]
    C --> E[End]
    D --> E

sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Request data
    API->>DB: Query
    DB-->>API: Results
    API-->>User: Response

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Start
    Loading --> Success: Complete
    Loading --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    CUSTOMER {
        int id
        string name
        string email
    }

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design :a1, 2024-01-01, 30d
    Development :a2, after a1, 45d

pie title Distribution
    "Category A" : 42
    "Category B" : 30
    "Category C" : 28

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Bắt đầu với Mermaid

Thực hành tốt nhất

• Giữ sơ đồ tập trung vào một khái niệm hoặc quy trình duy nhất
• Sử dụng nhãn có ý nghĩa phản ánh logic nghiệp vụ thực tế
• Chia sơ đồ phức tạp thành các sơ đồ nhỏ hơn, liên kết với nhau
• Thêm chú thích bằng %% để giải thích các phần phức tạp
• Sử dụng quy ước đặt tên nhất quán trong sơ đồ
• Kiểm thử sơ đồ trong môi trường mục tiêu trước khi hoàn thiện
• Thêm gợi ý hướng (TD, LR) để kiểm soát bố cục khi cần
• Dùng subgraph để nhóm các nút liên quan trong lưu đồ
• Sử dụng tùy chọn tạo kiểu một cách tiết chế để giữ khả năng đọc
• Quản lý phiên bản các tệp nguồn sơ đồ cùng với mã

Các trường hợp sử dụng phổ biến

Tài nguyên bổ sung

• Tài liệu chính thức Mermaid
• Kho Mermaid trên GitHub
• Tham chiếu cú pháp Mermaid