Cách mở tệp .mmd

Bạn thấy gì

No diagram type detected matching given configuration for text: ```mermaid

Vì sao

Bạn đã sao chép sơ đồ từ một tệp Markdown hoặc từ một cuộc trò chuyện và mang theo cả phần rào. Ba dấu huyền là Markdown chứ không phải Mermaid, nên bộ phân tích không bao giờ đi tới được sơ đồ.

Cách sửa

Xóa dòng mở ```mermaid và dòng đóng ```. Tệp phải bắt đầu bằng một từ khóa sơ đồ.

```mermaid
flowchart TD
    A[Bắt đầu] --> B[Kết thúc]
```

flowchart TD
    A[Bắt đầu] --> B[Kết thúc]

Bạn thấy gì

Parse error, kết thúc bằng: got 'NODE_STRING'

Lỗi kết thúc bằng: got 'NODE_STRING'

Vì sao

Định danh nút có khoảng trắng, và đây là cái bẫy lớn nhất với người viết tiếng Việt. Tiếng Việt viết rời từng âm tiết nên gần như mọi danh từ tự nhiên đều có khoảng trắng: «đơn hàng», «thanh toán». Định danh là token đứng trước mũi tên, và khoảng trắng cắt ngang nó.

Cách sửa

Cho nút một định danh viết liền và đưa phần chữ dễ đọc vào nhãn. Dấu tiếng Việt trong định danh thì không sao — chỉ khoảng trắng mới làm hỏng.

flowchart TD
    Đơn hàng --> Thanh toán

flowchart TD
    DonHang[Đơn hàng] --> ThanhToan[Thanh toán]

Bạn thấy gì

Lexical error on line N. Unrecognized text. — mà định danh trông không có gì sai

Vì sao

Định danh được lưu ở dạng Unicode tổ hợp (NFD) thay vì dạng dựng sẵn (NFC). Chữ `ơ` có thể là một ký tự duy nhất, hoặc là `o` cộng một dấu móc tổ hợp; trên màn hình hai dạng giống hệt nhau. Đã đo: dạng NFC chạy được làm định danh, dạng NFD thì đổ. Ở vị trí nhãn thì cả hai đều bình thường và cho ra cùng một kích thước, nên lỗi chỉ lộ ra khi bạn dùng nó làm định danh. Đây là lỗi khó nhìn ra nhất trên trang này.

Cách sửa

Gõ lại định danh bằng bàn phím thay vì dán vào — hầu hết bộ gõ tiếng Việt đều sinh NFC. Chắc chắn hơn nữa là dùng định danh không dấu và để chữ có dấu ở nhãn, vì nhãn không bao giờ dính lỗi này.

flowchart TD
    ĐơnHàng[Đơn hàng] --> B[Xong]

flowchart TD
    DonHang[Đơn hàng] --> B[Xong]

Bạn thấy gì

Parse error, kết thúc bằng: got 'PS'

Lỗi kết thúc bằng: got 'PS'

Vì sao

Một dấu ngoặc đơn mở nằm trong nhãn nút. Trong Mermaid, ngoặc đơn là cú pháp hình dạng — A(văn bản) là nút bo tròn — nên một dấu ngoặc đơn trần bên trong ngoặc vuông bị đọc thành khởi đầu của một hình.

Cách sửa

Đặt nhãn trong dấu nháy. Mọi thứ bên trong dấu nháy đều được coi là văn bản, kể cả dấu ngoặc.

flowchart TD
    A[Gọi ghiNo(đơn hàng)] --> B[Xong]

flowchart TD
    A["Gọi ghiNo(đơn hàng)"] --> B[Xong]

Bạn thấy gì

Parse error, kết thúc bằng: got 'end'

Lỗi kết thúc bằng: got 'end'

Vì sao

Bạn đã dùng end làm định danh nút. Chữ end viết thường sẽ đóng một nhóm con, nên bộ phân tích thấy điểm kết thúc khối ở chỗ nó đang chờ một nút. Chuyện này hay xảy ra khi làm theo ví dụ tiếng Anh.

Cách sửa

Viết hoa chữ đó hoặc cho nút một định danh khác rồi chuyển chữ ấy vào nhãn. `KetThuc` không gây vấn đề gì.

flowchart TD
    A[Bắt đầu] --> end

flowchart TD
    A[Bắt đầu] --> KetThuc[Đã hoàn tất]

Bạn thấy gì

Vẽ được, nhưng trong sơ đồ trạng thái một trạng thái biến thành nhiều ô

Vì sao

Khoảng trắng trong định danh trạng thái. Khác với lưu đồ, sơ đồ trạng thái không phản đối: nó tạo một ô riêng cho mỗi âm tiết rồi vẽ ra tỉnh bơ. Đã đo — `[*] --> Chờ thanh toán` cho ra ba trạng thái là `Chờ`, `thanh` và `toán`, và chỉ cái đầu nối vào mũi tên. Tiếng Việt viết rời từng âm tiết nên đây là ngôn ngữ chịu thiệt nặng nhất ở lỗi này.

Cách sửa

Khai báo trạng thái bằng `state "Nhãn" as id` rồi chỉ tham chiếu tới nó qua định danh.

stateDiagram-v2
    [*] --> Chờ thanh toán
    Chờ thanh toán --> Đã hủy

stateDiagram-v2
    state "Chờ thanh toán" as choThanhToan
    [*] --> choThanhToan
    choThanhToan --> DaHuy

Bạn thấy gì

Vẽ được, nhưng sơ đồ ER có những thực thể bạn không hề viết

Vì sao

Nhãn liên kết có khoảng trắng mà không có dấu nháy. Đây là cái bẫy gây phiền nhất với tiếng Việt, vì động từ quan hệ của ta hầu như đều nhiều chữ: «đặt hàng», «thuộc về». Mermaid không báo lỗi: nó cắt nhãn ở khoảng trắng đầu tiên rồi biến mỗi chữ còn lại thành một thực thể rỗng.

Cách sửa

Đặt dấu nháy quanh mọi nhãn liên kết có khoảng trắng. Với tiếng Việt thì gần như là tất cả.

erDiagram
    KHACH_HANG ||--o{ DON_HANG : đặt hàng

erDiagram
    KHACH_HANG ||--o{ DON_HANG : "đặt hàng"

Bạn thấy gì

No diagram type detected matching given configuration for text: sequencediagram

Vì sao

Từ khóa sơ đồ viết sai hoặc sai hoa thường. Từ khóa của Mermaid phân biệt hoa thường: sequenceDiagram chạy được, sequencediagram thì không. Với stateDiagram-v2 và erDiagram cũng vậy.

Cách sửa

Sửa lại hoa thường. Lưu ý graph vẫn được chấp nhận như bí danh cũ của flowchart, nên cú pháp cũ đó không phải vấn đề của bạn.

sequencediagram
    Client->>API: Xin chào

sequenceDiagram
    Client->>API: Xin chào

Bạn thấy gì

Parse error trong nhãn cạnh nằm giữa hai gạch đứng

Vì sao

Dấu ngoặc đơn nằm trong nhãn cạnh. Nhãn |...| chịu ràng buộc y hệt nhãn nút: ở đó ngoặc đơn cũng là cú pháp chứ không phải văn bản.

Cách sửa

Đặt nhãn cạnh trong dấu nháy.

flowchart TD
    A -->|có (luôn luôn)| B

flowchart TD
    A -->|"có (luôn luôn)"| B

Bạn thấy gì

Parse error chỉ vào dòng cuối cùng của sơ đồ

Vì sao

Một khối đã mở mà không bao giờ đóng: alt, opt, loop, par và subgraph đều đòi end của riêng chúng. Mermaid báo lỗi ở chỗ nó hết dữ liệu vào, nên số dòng chỉ vào cuối tệp chứ không chỉ vào khối còn dang dở.

Cách sửa

Đếm số khối đã mở và số end bạn đã viết. Nếu lỗi chỉ vào dòng cuối thì gần như luôn là chuyện này.

sequenceDiagram
    Client->>API: Yêu cầu
    alt Mọi thứ ổn
        API-->>Client: OK

sequenceDiagram
    Client->>API: Yêu cầu
    alt Mọi thứ ổn
        API-->>Client: OK
    end

Bạn thấy gì

Lexical error on line 1. Unrecognized text.

Vì sao

Hướng không hợp lệ sau từ khóa sơ đồ. Lưu đồ chỉ nhận TB, TD, BT, LR và RL, không có gì khác; một lỗi gõ sẽ đổ ngay ở bước phân tích từ vựng, trước khi đọc được dù chỉ một nút.

Cách sửa

Dùng một trong năm hướng hợp lệ. TD và LR bao gần hết mọi trường hợp.

flowchart XY
    A --> B

flowchart TD
    A --> B

Bạn thấy gì

Ở đây thì vẽ được, trên GitLab, Confluence hay một công cụ cũ thì không

Vì sao

Chênh lệch phiên bản. Trình xem này chạy Mermaid 11.12.2; GitLab.com ghi phiên bản 10, còn các wiki tự cài có thể lạc hậu nhiều năm. Cú pháp ra đời sau phiên bản của công cụ kia sẽ phân tích được ở đây và đổ ở đó.

Cách sửa

Hãy hỏi bộ máy kia đang chạy phiên bản nào. Viết mỗi chữ info trong một sơ đồ sẽ khiến Mermaid vẽ ra số phiên bản của chính nó, nhanh hơn là đọc nhật ký thay đổi.

info