🌱 Mermaid - Công cụ vẽ sơ đồ mạnh mẽ trong Lập trình
Document nói chung và Diagram nói riêng có vai trò quan trọng trong các dự án, nó sử dụng để design flow, giúp việc develop và maintain code dễ dàng hơn, cũng như góp phần vào việc "báo cáo" ở phase cuối của dự án.
Hơn nữa, hiện nay việc coding với sự hỗ trợ của AI ngày càng trở nên phổ biến trong giới lập trình, nên nhiều dev cũng quen với việc sử dụng AI để gen Diagram. Tuy nhiên việc gen diagram/flow ảnh rất khó khăn và mất thời gian, nên chúng ta cần một cách thể hiện diagram bằng text để dễ dàng thay đổi và tích hợp AI. Mermaid chính là một chiếc chìa khóa ở đây!
Bài viết này mình sẽ cùng mọi người tìm hiểu về Mermaid và cách sử dụng cơ bản của mermaid trong lập trình!
1. Giới thiệu về Mermaid và cách sử dụng
Mermaid là một thư viện JavaScript cho phép bạn tạo sơ đồ (diagrams) bằng văn bản (plain text) — ví dụ flowchart, sequence diagram, class diagram, state diagram... Ưu điểm lớn của Mermaid là nhanh, ít phụ thuộc, và rất phù hợp khi viết tài liệu kỹ thuật, README, hoặc nhúng trực tiếp vào blog/slide hoặc wiki.
Note: Trong bài này chúng ta dùng Mermaid để minh họa các luồng xử lý (flow), state machine và sequence thường gặp trong lập trình embedded (driver init, ISR flow...).
Cài đặt & cách chạy
Có nhiều cách để dùng Mermaid:
- CDN: cách nhanh nhất là chèn
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>vào trang HTML — Mermaid sẽ auto-render các block code có classlanguage-mermaidhoặc thẻ<div class="mermaid">. - CLI / preprocessor: bạn có thể dùng
mmdc(Mermaid CLI) để render SVG/PNG offline:npm i -g @mermaid-js/mermaid-cli. - Trong Markdown: nhiều hệ thống (GitLab, Obsidian, MkDocs + plugin) hỗ trợ Mermaid trực tiếp hoặc qua plugin.
↪ Generate Mermaid Flow Chart qua website sau:
2. Cú pháp Mermaid cơ bản
Dưới đây là các ví dụ ngắn cho những kiểu sơ đồ phổ biến.
2.1. Flowchart
graph TD
Start([Start]) --> Init{initialise?}
Init -- yes --> Run[Run main loop]
Init -- no --> Error[Show error]
Ghi chú: graph TD (Top → Down). Dùng graph LR cho left-right.
2.2. Sequence diagram
sequenceDiagram MCU->>LCD: init() MCU-->MCU: setup pins MCU->>LCD: send data LCD-->>MCU: ACK
2.3. State diagram (State machine)
stateDiagram-v2 [*] --> Idle Idle --> Init : power_on Init --> Ready : init_done Ready --> Busy : start_op Busy --> Ready : op_done Ready --> Error : fault Error --> Idle : reset
↪ Bạn có thể tham khảo thêm các cú pháp khác của mermaid tại trang chủ!
3. Nhúng Mermaid trong Markdown & Blogger
Trong Markdown (ví dụ GitLab/GitHub/GitLab pages), bạn có thể dùng fenced code block với class mermaid:
```mermaid
graph TD
A-->B
```Trong Blogger (Blogspot):
- Ở đầu bài viết (phần
<head>trong template) chèn CDN Mermaid như phần 2.1. - Trong nội dung bài viết, chèn thẻ `...` hoặc fenced code với class
language-mermaid. - Nếu Blogger tự động escape ký tự, bạn có dùng HTML entity hoặc đặt block trong chế độ HTML editor (khuyến nghị).
<div class="mermaid">
stateDiagram-v2
[*] --> Idle
Idle --> Running : start
Running --> Idle : stop
</div>Mermaid sẽ render sơ đồ khi trang được load (nếu đã include script).
4. Một số Ví dụ cho Embedded Developer
Dưới đây là các ví dụ áp dụng Mermaid cho các tình huống phổ biến trong Embedded System.
4.1. Flowchart: driver init
flowchart TD
PowerOn([Power ON]) --> Reset
Reset --> ConfigPins[Configure GPIOs]
ConfigPins --> InitPeriph[Init Peripheral (I2C/SPI/UART)]
InitPeriph --> SelfTest{Self test OK?}
SelfTest -- yes --> Ready[Driver Ready]
SelfTest -- no --> Error[Set error state]
4.2. State machine: Sensor sampling states
stateDiagram-v2 [*] --> Sleep Sleep --> Wake : timer Wake --> Sample : start_sampling Sample --> Process : data_ready Process --> Transmit : send Transmit --> Sleep : done Process --> Error : bad_data Error --> Sleep : recover
4.3. Sequence: ISR và Main loop interaction
sequenceDiagram participant ISR as ISR participant MCU as Main ISR-->>MCU: set flag MCU-->MCU: if(flag) process() MCU-->>Periph: read data Periph-->>MCU: return data
Ứng dụng: bạn có thể đặt những đoạn trên vào tài liệu thiết kế (spec) để developer nhanh hiểu luồng, hoặc dùng để review code với team.
4.4. Tự động chuyển thành code hoặc comment trong repo
Bạn có thể render Mermaid sang SVG (bằng mmdc) rồi commit file SVG vào repository docs/ — giúp tài liệu luôn tồn tại mà không phụ thuộc runtime Mermaid.
5. Kết luận
Mermaid là công cụ rất mạnh và nhẹ cho tài liệu kỹ thuật — đặc biệt hữu ích với lập trình viên embedded vì giúp mô tả flow, state và interaction mà không cần công cụ đồ họa nặng. Bạn có thể nhúng trực tiếp trong Blogger hoặc render offline bằng CLI để lưu dưới dạng SVG.
Note: Bạn có thể tự generate hình minh họa Mermaid (SVG/PNG) bằng mmdc hoặc công cụ online nếu muốn chèn ảnh đẹp vào bài.
>>>>>> Follow ngay <<<<<<
Để nhận được những bài học miễn phí mới nhất nhé 😊
Chúc các bạn học tập tốt 😊
